#2819 stagecraft: a user-facing README for first release (what it is, getting started, studio, trackers)

Write stagecraft's user-facing README: the first release's documentation, and the page users see on the registry.

Re-scoped on 2026-10-01 (Seth). This issue was the full go-live user documentation. Following direction from Seth and Paul for the first release, it is now the README only. The full manual (concept pages, a reference with every validate finding, migrating from software-factory) waits until after launch. The previous scope is preserved in this issue's history.

Why

Today's README (gatorwalk-factory/README.md, about 26 KB) is written for people working on the extension: layout, internals, the go-live rule and design pointers. A new user needs a landing page that says what stagecraft is, why they'd use it, and how to get started in a few minutes.

Contents

1. What stagecraft is, in a few sentences. It is a factory maker: you build your own factories, where agents do the work or drive a process. A factory can be for software, web posts, incident reviews, swamp models or extensions, or anything else you can express as stages that produce artifacts and evidence, with gates that set the rules for moving between them. Inside a stage, the work can be anything, including calling a swamp model or workflow. Show that breadth with a few short examples.
2. Getting started. Install, then ask your agent to set up a factory. This is the interactive walkthrough from #2931; point to it rather than duplicating it. Show the handful of commands someone actually types.
3. The studio: see your factory, click to understand it, and simulate work moving through it. Explain how to start it and what it is (local, read-only; your agent makes the edits). Include one screenshot or image if it earns its place.
4. Concepts on one screen: factory, factory definition, stage, gate, transition, product (artifact and evidence), work item, human stop, journal, tracker. One line each.
5. Trackers. Built-in by default, plus Linear setup in short (key in a vault, teamId, statuses, labels). Use what the Linear live test learned, if it has finished. The swamp-club Lab adapter is the swamp-club team's own and isn't presented as an option (#2842).
6. Driving work: how an agent moves a work item, where people decide, and what overrides are. Short, with links into the skill's references.
7. Where to go next: the skill's references, the examples, saved scenarios, and DESIGN.md for how it works.

Scope

• Move the internal material out of the README, into DESIGN.md or a short CONTRIBUTING-style section, so nothing is lost. That covers the layout tree, the unpublished/manifest rule (#2820 removes it anyway), test harness notes and developer tasks.
• Write against the final name, stagecraft. #2932 renames the extension. Land after #2932, or write with the new names and let #2932's script handle the rest; say which.
• Every command shown must run. Check them the way integration/extension/skill_test.ts checks the skill, or add the README to that check.
• Keep it short: a reader should get from zero to their first factory in about five minutes of reading.

Done when

• A new user can read the README alone and know what stagecraft is, install it, and start the getting-started walkthrough.
• Every command shown runs.
• The internal material lives somewhere else and nothing was dropped.
• The README renders well as the registry page. Check how the registry displays an extension README, for example @swamp/software-factory's page.

Out of scope: the full manual, the getting-started walkthrough itself (#2931), the rename (#2932) and publishing (#2820).