README: an overview and quick start; the reference detail moves to docs

AGENTS.md

@@ -4,4 +4,4 @@ Factory is a GitHub Action (`action.yml`), a plugin (`plugin/`: skills, agents,
 
 Use an existing SDK or library before writing your own: for a protocol, a file format, a codec or a provider's API, look first for the official SDK, then for a maintained library whose licence the repository can take, because hand-written protocol code falls behind its standard and every line of it is ours to maintain. Write it yourself only when nothing fits (no library, a licence that does not fit, an unwanted install script or native binary, or output that must be byte-for-byte deterministic), and say in the PR what you looked at and why it did not fit, then add it to `docs/PLAN.md`'s Dependencies list; a PR that hand-writes such code without that is a review finding. A runtime library ships vendored in `plugin/vendor`, the same section says how.
 
-Read `docs/PLAN.md` (what Factory is, its contracts, 0.9.x releases and the 1.0 bar), `docs/LOCAL.md` (local mode: setup, sandboxes, settings), `docs/ADAPTERS.md` (third-party adapter contracts: the cloud sandbox and the decision model) and `bench/README.md` (the scorecard and drills). Docs describe Factory as it is now; git is the history, so write no logs, dated narratives or ledgers. Code decides on structure only: JSON the harness writes, GitHub fields, exit codes, counts; never prose. Tests: `node --test plugin/test/*.test.mjs bench/test/*.test.mjs`; each test file that touches the file system imports `plugin/test/temp.mjs` first (its temp files then live in a root removed when the file ends), and CI fails when the suite leaves anything in the temp folder.
+Read `docs/PLAN.md` (what Factory is, its contracts, 0.9.x releases and the 1.0 bar), `docs/LOCAL.md` (local mode: setup, sandboxes, settings), `docs/ADAPTERS.md` (third-party adapter contracts: the cloud sandbox and the decision model) and `bench/README.md` (the scorecard and drills). For adopters: `docs/INSTALL.md` (the install footprint, cost inputs, upgrade, uninstall) and `docs/USAGE.md` (writing and following an Objective). `README.md` is the overview and quick start for a first-time reader: keep it short, and put reference detail in `docs/`. Docs describe Factory as it is now; git is the history, so write no logs, dated narratives or ledgers. Code decides on structure only: JSON the harness writes, GitHub fields, exit codes, counts; never prose. Tests: `node --test plugin/test/*.test.mjs bench/test/*.test.mjs`; each test file that touches the file system imports `plugin/test/temp.mjs` first (its temp files then live in a root removed when the file ends), and CI fails when the suite leaves anything in the temp folder.

CONTRIBUTING.md

@@ -1,3 +1,21 @@
 # Contributing
 
-Factory takes no outside pull requests until its owner says otherwise, through 0.9.x and 1.0 alike; only maintainers open them. Issues are welcome: bugs, questions and ideas. Report a security problem privately instead (see [SECURITY.md](SECURITY.md)).
+Issues are welcome: bugs, questions and ideas. Factory takes no outside pull requests until its owner says otherwise, through 0.9.x and 1.0 alike; only maintainers open them.
+
+## Reporting a bug
+
+[Open an issue](https://github.com/clockgrove/factory/issues/new) with:
+
+- the Factory tag your workflow pins (`clockgrove/factory@vX.Y.Z`), the harness (Claude Code, Codex or Copilot) and the route (Actions, local mode or the cloud sandbox);
+- what you expected and what happened, with a link to the Objective's issue or PR when it is public;
+- the Blocked or Question comment's text, and `/factory:doctor`'s lines when setup is involved.
+
+Leave out tokens, keys and private code. Report a security problem privately instead (see [SECURITY.md](SECURITY.md)).
+
+## Questions and ideas
+
+Open an issue for these too. Say what you are trying to do; a real Objective that Factory handled badly is the most useful report there is.
+
+## Working in this repository
+
+[AGENTS.md](AGENTS.md) holds the rules for maintainers and their agents, and [docs/PLAN.md](docs/PLAN.md) the design.