[kirkmarple-clockgrove]

The README was one long reference page. A first-time reader met the whole install footprint, seven tuning inputs and the cloud sandbox's session limits before learning how to try Factory.

What guided the rewrite:

• GitHub's Open Source Guides: a README answers what the project does, why it is useful, how to get started and where to get help, and says plainly when contributions are not accepted or the project is not production-ready.
• The Standard Readme spec: title, a one-line description, install, usage, contributing, and the license last.
• "Cognitive funneling" from the Art of README essay: the broadest facts first, each section more specific, so a reader can stop as soon as they know whether it fits.

The new README (148 lines):

• One line and a short paragraph on what Factory does, with its status.
• How it works, in five steps, and the two ways a run stops.
• Know before you start: it merges on its own by default, it spends money, what the agent can and cannot touch.
• A four-step quick start: install the plugin, /factory:setup, /factory:doctor, file an issue (with an example issue). Then the same setup as scripts, and local mode as a way to try it first.
• What Factory adds to a repository, including the App's permission list.
• Where it runs, a map of the docs, Versioning (unchanged in substance), help and contributing, and the license.

Nothing is dropped; the reference detail moves:

• docs/INSTALL.md (new): requirements, the three routes, the install footprint table, what each credential can do, setup by hand (including creating the App), check and run, the cost inputs as a table, upgrade and uninstall.
• docs/USAGE.md (new): writing an Objective, what the issue shows during a run, Blocked and Question and how to answer, auto-merge, siblings, one repository per Objective, and the commands.
• CONTRIBUTING.md: says what helps in a bug report. The no-outside-PRs rule is unchanged.
• AGENTS.md: maps the two new pages and says the README stays a short overview.

Checked:

• Every statement of the old README is in one of the three pages. I compared them sentence by sentence; the old text moved verbatim except where a paragraph became a list or a table.
• Every relative link resolves.
• The quick start's commands were run: the clone at the latest release tag, and setup's preview against a scratch repository.
• The new statements in docs/USAGE.md were checked against the code: the acceptance headings, priority order, who may file, and the six-part limit.
• The full suite passes (791/791). doctor.test.mjs still finds the App's permission list in the README.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CS53Gu2D3bE8mKgFN92XP5