docs: rewrite the flow docs for the new flow API

[futrime]

Unit 6 (Docs) of the new flow API. Every page that shows how a flow is written, run, called or tested is rewritten to match hmz.flows (the protocols) and hmz.runtime.flowing (the engine and its drivers). Only docs/** changes. README needed nothing.

What changed

• docs/reference/flows.md: rewritten from scratch. Its headings keep the old anchors where the topic survived.
  • Topics: the @flow contract, and AgentCollection/EnvCollection roles.
  • Mixins, with the per-harness capability table.
  • Permission and how it maps onto each harness. local=ALL means bypass on every harness, and user/system are not fenced; that widening is written down. Codex runs with untrusted approvals while a permission-request hook is hung; Kimi Code and ZCode use their ask-and-approve rung while a permission or ask-user hook is hung.
  • Sessions and turns: /goal, /loop, steer, fork.
  • Environments: the mixins, worktrees, temporary clones and scratch directories, and how long each lasts.
  • Hooks: one on_* method per kind. The outworlder: away, Outworlder.new(), on_outworlder_run.
  • FlowParams and -p. ctx. Budgets: nesting, deadlines, sticky exhaustion, graceful.
  • Resuming: the journal, --resume, and how subflows are matched.
  • Refs, the bare-ref rule, and what a called flow is handed (narrowing, auto roles).
  • The exception tree. Testing on the fake kit.
• docs/weaver/*: every page rewritten.
  • tools.md becomes "The agent asking the flow". Callbacks as tools are gone, and on_ask_user and the other hooks are the way back from a turn to the flow.
  • worktrees.md covers worktrees, copies and scratch directories.
  • testing-flows.md replaces the old checking and proving docs with the public fake kit.
  • New tutorial: tutorials/build-under-test.md.
• docs/features/*, docs/flows/*, docs/index.md: the new API throughout.
  • Flowverse invocations use the pinned role names (agent, worker, first_chaser/second_chaser, actor/reviewer, …). human and workspace are auto-filled.
  • Every invocation has a -b. Per-flow default budgets are gone.
  • fixed-juice-ralph is dropped.
  • parallel-flame-chase-mission is replaced by parallel-flame-chase-git-pr.
• docs/reference/{cli,agents,sdk,tui,…}.md, docs/user/*, docs/contributing/*:
  • The hmz exec section: -a/-e/-p/-b, --resume, --json, and what is refused before anything runs.
  • The Codex approvals override and the flow API's permission mapping in agents.md.
  • The TUI's role, environment, params and budget sheets; /afk and /resume.
  • The layer table in architecture.md.
• Deleted pages: weaver/atlas, features/prophecy, weaver/checking-flows, weaver/tutorials/{checked-build,prove} and flows/fixed-juice-ralph, plus the HmzProphecy component.
  • Each old path now redirects to its successor through a new GONE table in config.mts, instead of returning a 404.
  • Theme dead code left behind by fixed_juice_ralph (the governor family and the juice meter) is removed.
• docs/tapes/stage.py: the two demo flows (twice and the resumable nightly) are ported to the new API. checks.tape now shows new refusals. The GIFs are not re-rendered.

Checked

• cd docs && pnpm install --frozen-lockfile && pnpm build && pnpm check:anchors: the build completes, and every #fragment resolves.
• uv run pre-commit run --all-files passes. That includes pyright on docs/tapes/stage.py.
• uv run pytest --ignore=tests/system: 4314 passed, 11 skipped.
• The code examples were run on the fake kit (run_fake), including the full test file on the testing page against the flow it tests. The ported stage flows load, run and resume from a journal.
• A code-review pass found 15 issues. All were fixed except the expected one: the docs describe CLI/TUI behaviour that Unit 5 has not landed yet.

For the coordinator to reconcile after Unit 5 and the flowverse units land

• CLI and TUI are described per the plan's decisions:
  • error text of the form hmz exec: error: <engine message>, the missing--b usage error, and exit statuses;
  • --json, and --resume meaning the newest resumable run of the flow in this workspace;
  • the /flow role, environment, params and budget sheets, what is remembered per flow, /afk making the outworlder away, and /resume.
• Journal location is assumed to be beside the epic; the file name is not stated.
• chat is assumed to have roles assistant and human, the full view, and no -b.
• The SDK is not claimed to re-export the fakes. The pages import hmz.runtime.flowing.fakes directly.
• Flowverse behaviour is written ahead of the port (Units 7–12): the ralph loops' "three stalled rounds", the humanize1:rlcr builder → gates → reviewer loop, and the Git PR page, which is a summary of the flowverse README.
• hmz.runtime.flowing.running still maps to the legacy module. The docs point to engine.running().
• Stale runtime references: run.tape still reads state.json, and HmzSurfaces.vue still names the SDK's Run and runner. Both depend on Unit 5.

🤖 Generated with Claude Code