[clabonte]

Adds docs/flows.html, an interactive guide for spec authors in the same shape as the loop's flows page. It is a new overlay entry, so init and upgrade put it at .specfuse/authoring/docs/flows.html, and it always describes the installed kit. It opens from disk with no external script.

Merge order. The page describes the kit as it will be once these land, so merge them first:

• docs: bring the idea and initiative lifecycles up to spec-before-mint specfuse#223: the State machine view mirrors and links to the updated unit-lifecycles.md.
• docs: component-repo setup guide #173: the Specs and components view links to docs/component-repos.md.
• feat(scaffold): ship generate.sh and advance-state.sh #176: that view's regen flow uses generate.sh and advance-state.sh.
• fix(generate): pass the generator's own verb; drive groups from the project file #174: the generate skill wording it relies on.

Views

1. Big picture: where the kit sits among the specs repo, generator, handoff, orchestration repo and implementation, and which repo owns what.

2. Idea to specs: three paths as clickable tracks:

   • specs before the mint (the default)
   • mint first
   • no orchestrator

   Each stage shows the skill, what it writes, the backlog state, and where a person steps in.

3. State machine: the idea and initiative machines as clickable diagrams.

   • Selecting a state lists how it is reached and left. Selecting an arrow names who moves it, what it writes and what it needs.
   • A toggle shows a project without an orchestration repo: the dependent transitions grey out, the initiative machine does not exist, the undocumented ready → delivered ending shows as a gap, and a table gives every skill's status there.

4. Your project: a clickable tree of a scaffolded project, colored by owner (kit, yours, generated, or upgrade's record), with what upgrade does to each path.

5. Which skill?: "I want to…" choices with a filter, covering all 28 skills and 6 agents.

6. Validation: the nine validate-specs.sh layers. Picking one of 13 common mistakes highlights the layer that catches it, including the Spectral "crash looks clean" case.

7. Upgrades: a simulator that follows scaffold.upgrade's manifest rules, including the quoted warnings.

8. Project file: a clickable example <project>-project.json (three component repos plus docs). Each key explains itself, says whether it is required and links its Project_File.md section. The keys that bite are highlighted. Panels cover the foot-guns, the blocks not in the example, and what the generator does with the file.

9. Specs and components: the spec repo fanning out to its component repos through each group's destination. Per language: where generated code lives, how hand-written code extends it, build wiring and post-generate steps. Then the five-step regen flow and the house rules.

10. The loop: the three spec front-ends, plus an "I want to" picker. It says whether to use a loop feature and where (spec repo or component), with the command chain and the rules for each case, and compares the loop with the orchestrator.

Links into handbooks, samples, schemas and templates are relative and resolve both in this repo and in an installed project. Repo-only docs link to GitHub.

Drift check

scripts/check-flows-page.py runs in CI and fails when the page's embedded data disagrees with the kit. It checks:

• skills and agents against the plugin, and that the finder and the no-orchestrator table cover every skill
• backlog states and the readiness checklist against the templates, and the idea machine against those states
• every transition's skill and states
• validation layers against validate-specs.sh
• cited Spectral rules against the rulesets
• the overlay and quoted upgrade output against scaffold.py
• every relative link in both layouts
• the project file example's keys against Project_File.md's quick reference, its artifact ids against the per-language lists, and every Project_File.md anchor the page links
• the loop picker's skill names

The CI smoke test also asserts a fresh project gets a byte-identical copy of the page.

Testing

• The drift check passes; injecting drift (renamed skill, missing rule, broken link) makes it fail with the expected messages.
• init from source installs the page and records it in the manifest.
• In node with a stub DOM, all views render and 100 state/arrow selections work in both modes.
• I checked the diagrams' layout in headless Chrome.
• Not run locally: the wheel build (blocked by the sandbox), so the force-include change is tested only by CI.

Follow-up

Without an orchestrator no skill moves an idea past ready, and ideation-groom keeps reporting those ideas as ready to mint. The page and the core docs now say so; fixing it needs a skill change.

🤖 Generated with Claude Code