docs(stagecraft): a user-facing README, with the reference and contributor material moved out (swamp-club #2819) #436

Merged

seth merged 1 commit from cue/2819-stagecraft-user-facing into main

2026-10-02 13:24:48 +00:00

seth commented

2026-10-02 13:23:01 +00:00

Owner

Summary

swamp-club #2819. stagecraft's README is now the page for people using it, and the registry page at publish: what stagecraft is (with examples from software to incident follow-up and OpenAPI-to-models), getting started (swamp init, swamp extension pull @swamp/stagecraft, then ask the agent, which starts #2931's walkthrough), the studio with a screenshot, concepts, trackers (built-in and Linear in short), driving work and where to go next. It is written as if published and never names the swamp-club Lab.

Nothing is dropped:

REFERENCE.md (new) holds the method-level sections word for word: the model types (the old Vocabulary), the definition format, loops, examples (with #2931's three), saved scenarios, running it, the studio's controls, summary and metrics, the built-in tracker, Linear, start from a ticket, and the swamp-club Lab last, still labelled the team's own.
DESIGN.md opens with "Working on stagecraft": the not-published rule, the layout tree, developer tasks, the skill test and how to retake the screenshot. A decision-log entry records the move.
docs/studio.png: Design mode on starter with plan-review selected.

Rewordings for a published extension: "Running it" starts from swamp extension pull; the quality waiver drops "stagecraft needs this until go-live"; the ${{ rule now says the definition lives in globalArguments, where swamp evaluates ${{ }} (it said a separate file, stale since #2884).

Tests

integration/extension/skill_test.ts:

Every README command names a real method with inputs it accepts, through the skill's checker (README instance names map to its placeholders).
init, extension pull, vault create and vault put have exact shapes; a vault put with the secret on the line is refused.
Every relative README link resolves, anchors included (reusing #2931's slug helper).
The README never mentions the Lab; REFERENCE.md's mentions must be labelled.

Each was checked by breaking a link, a command and the Lab rule.

For #2820 and later

#2820's manifest must list README.md, REFERENCE.md and docs/studio.png in additionalFiles.
Whether the registry resolves a relative image is only visible after publish; if not, switch to the repo's raw URL.
Linear setup details are refined in a follow-up ticket.
Review notes, non-blocking: the README name mapping is position-blind, the link regex skips titled links, REFERENCE.md's commands stay unchecked (as the old README's were), and one DESIGN.md line is long.

Verification: verify-build and verify-reviews passed on 150685bab (attestation 0a65fac1-6aaa-43ae-a2d9-14b299125d9a).

🤖 Generated with Claude Code

## Summary swamp-club #2819. stagecraft's README is now the page for people using it, and the registry page at publish: what stagecraft is (with examples from software to incident follow-up and OpenAPI-to-models), getting started (`swamp init`, `swamp extension pull @swamp/stagecraft`, then ask the agent, which starts #2931's walkthrough), the studio with a screenshot, concepts, trackers (built-in and Linear in short), driving work and where to go next. It is written as if published and never names the swamp-club Lab. Nothing is dropped: - **REFERENCE.md** (new) holds the method-level sections word for word: the model types (the old Vocabulary), the definition format, loops, examples (with #2931's three), saved scenarios, running it, the studio's controls, summary and metrics, the built-in tracker, Linear, start from a ticket, and the swamp-club Lab last, still labelled the team's own. - **DESIGN.md** opens with "Working on stagecraft": the not-published rule, the layout tree, developer tasks, the skill test and how to retake the screenshot. A decision-log entry records the move. - **docs/studio.png**: Design mode on `starter` with `plan-review` selected. Rewordings for a published extension: "Running it" starts from `swamp extension pull`; the quality waiver drops "stagecraft needs this until go-live"; the `${{` rule now says the definition lives in `globalArguments`, where swamp evaluates `${{ }}` (it said a separate file, stale since #2884). ## Tests `integration/extension/skill_test.ts`: - Every README command names a real method with inputs it accepts, through the skill's checker (README instance names map to its placeholders). - `init`, `extension pull`, `vault create` and `vault put` have exact shapes; a `vault put` with the secret on the line is refused. - Every relative README link resolves, anchors included (reusing #2931's slug helper). - The README never mentions the Lab; REFERENCE.md's mentions must be labelled. Each was checked by breaking a link, a command and the Lab rule. ## For #2820 and later - #2820's manifest must list `README.md`, `REFERENCE.md` and `docs/studio.png` in `additionalFiles`. - Whether the registry resolves a relative image is only visible after publish; if not, switch to the repo's raw URL. - Linear setup details are refined in a follow-up ticket. - Review notes, non-blocking: the README name mapping is position-blind, the link regex skips titled links, REFERENCE.md's commands stay unchecked (as the old README's were), and one DESIGN.md line is long. Verification: verify-build and verify-reviews passed on 150685bab (attestation 0a65fac1-6aaa-43ae-a2d9-14b299125d9a). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

seth added 1 commit

2026-10-02 13:23:01 +00:00

docs(stagecraft): a user-facing README, with the reference and contributor material moved out (swamp-club #2819 )

CI / Review Integrity (pull_request) Successful in 1m17s

Details

CI / Validate Attestation (pull_request) Successful in 1m19s

Details

150685bab8

The README is the registry page and a new user's first read. The
method-level material moves word for word to REFERENCE.md, the layout
and developer tasks to DESIGN.md's Working on stagecraft. skill_test
checks the README's commands and links, and that it never names the
swamp-club Lab.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

seth merged commit 7dbd8d5ff2 into main

2026-10-02 13:24:48 +00:00

seth deleted branch cue/2819-stagecraft-user-facing

2026-10-02 13:24:48 +00:00

seth referenced this pull request from a commit

2026-10-02 13:24:49 +00:00

docs(stagecraft): a user-facing README, with the reference and contributor material moved out (swamp-club #2819) (#436)