journey: no measured path takes one newcomer from install through author, break, rehearse, run durably, approve, and recover — each step has a surface, and nothing checks that they connect or how long the whole takes

Observed behavior

At 7530b29, every stage of a first day has a surface: README.md's Quickstart (scaffold, flow run local, flow run against flow server dev), flow validate with positioned diagnostics, flow test and the debugger (docs/DEBUGGING.md), wait_for_signal gates answered by flow signal, MCP and the webhook bridge, flow watch, undo: compensation, and docs/DEPLOYMENT.md for the durable side. What does not exist is a single journey that walks them in order and is held to a measurement.

The tracker records the pieces that make the journey long, each separately: the language reference is a 5,758-line decision record (#1653); rehearsing authentication locally takes ten steps and four refusals (#1695); flow run cannot submit a workflow that names a plugin task (#1548); a rebuilt plugin is invisible until restart (#1535); the debugger has no line breakpoints or source frames (#1507); the humans a gate waits on have no browser surface (#1748); recovery has no documented procedure (#1736); and flow run's local-versus-server ergonomics are an open design (#371). None of those issues asks the question a newcomer asks, which is whether the whole thing hangs together, and no artifact in the tree would fail if it stopped doing so.

Two related facts the journey would surface. docs/ARCHITECTURE.md documents driver agreement in detail but does not say in one place what local rehearsal cannot reproduce (persistence, deployment, resource and external side-effect failures), so a reader who passed flow test does not know what they have not yet proved. And the README does not say whether a full setup needs anything beyond Go and the flow binary; the editor extension does, the core product should not, and neither is stated.

Desired outcome

A single guided journey, written and measured, that a person and an agent can each complete with the same underlying APIs:

1. Install into an isolated environment with Go and flow only.
2. Start from one small example whose inputs and outputs are understood in a paragraph.
3. Make a deliberate error and receive a precise, positioned repair.
4. Rehearse an approval, a timeout, a refusal and a compensation in flow test.
5. Run the same workload durably and find its current position.
6. Answer the pending gate through an authenticated interface.
7. Break an operation, diagnose it, and follow the documented recovery path.

The journey is a document (docs/JOURNEY.md or the README's Quickstart grown to cover it) plus a script or flowtest corpus that executes every command in it, so the document cannot drift from the binary. The measured quantities are wall-clock time to complete, the number of manual interventions, the number of errors whose message did not say what to do next, and the number of documents a reader had to open. The same journey is run by an agent through MCP and by a person through the CLI, and the two transcripts are kept beside the document.

The document also states plainly what step 4 proves and what it does not: local rehearsal reproduces the workflow's logic, its gates and its compensation, and not persistence, deployment, resource or external side-effect failures; those are step 5 and step 7's evidence.

Acceptance criteria

• The journey document exists and every command in it is executed by a CI job (the examples-matrix pattern) against flow server dev, failing on any exit code or message change.
• The measured numbers are recorded in the document with the revision they were taken at, and re-taken when the journey's commands change.
• The agent transcript and the human transcript reach the same final state from the same APIs; a divergence is filed as a defect against the surface, not the journey.
• docs/ARCHITECTURE.md or the journey names what local rehearsal cannot reproduce, in one place, linked from docs/DEBUGGING.md.

Constraints and dependencies

• This is the "supported golden path" criterion #1216 lists before release planning resumes; it does not itself authorize any release.
• The journey is the consumer that decides which of #1653, #1695, #1548, #1535, #1507, #1748, #1736 and #371 block a newcomer today; sequencing follows what the measurement shows, not the issue list.
• Recommended first audience for the worked example: a platform team's approval-driven integration runbook, since that exercises typed tasks, policy, identity, long waits and compensation together. This is a hypothesis about audience, not evidence of demand.

Open questions

• Whether the journey lives in the README or a separate document the README points to; the README's current Quickstart stops at step 5.
• Which example is the journey's workload; examples/approval-gate is the closest today.

Start with README.md's Quickstart, docs/ARCHITECTURE.md, docs/DEBUGGING.md, docs/DEPLOYMENT.md, examples/approval-gate, and the examples-matrix pattern. Trace the existing flow commands, flowtest corpus, MCP path, and CI entry points before choosing the journey location and workload. Done means the documented steps execute in CI, record revisioned measurements, and produce matching human and agent final states.