Expand the documentation with measured figures and operational detail

Most of this replaces "roughly 550 characters per tool" with the actual
per-tool measurements, and fills in the parts a reader hits after the happy
path: what a specific error means, what a setting costs, what is not covered.

Measured rather than estimated:
- Per-tool byte cost, all fourteen, and the per-set totals. 7,673 B for the
  full set, averaging 548.
- Builtin skill bodies at 5,284 B against a 681 B catalogue, which is the
  argument for loading bodies on demand.
- Full system prompt 3,571 chars, core-only 2,045.

New sections:
- tools: which sets to keep and why, the jail function itself, an output-cap
  table, and the real error strings for edit_file and multi_edit.
- configuration: env var per provider preset, cost-estimate limits, what each
  --no-* flag isolates, and three settings that do more than they look like.
- agents: step caps per variant, which variant to reach for, and the fact that
  reasoning is charged as output and discarded first by compaction.
- headless: exit code 0 means "the turn completed", not "the answer was yes" —
  with the jq pattern for gating on content. Timeouts, concurrent -c runs
  fighting over one session, CI recipes for --no-skills.
- mcp: parallel connect, startup cost, a debugging ladder, and that toolSets
  does not gate MCP tools.
- registry: publishing, local testing over http://localhost, and a
  troubleshooting section keyed on the actual validator messages.
- memory: what compaction discards in what order, /compact versus automatic
  pruning, and that -c matches on cwd.
- skills: the frontmatter reader's limits, and how to verify a skill loaded.

Corrections found while cross-checking against the source:
- The guard table was missing --force-with-lease and > /dev/sd…
- The done event's token fields are optional, so the jq example filters on one
  rather than assuming it.

Two honest limits now written down: the guard matches command strings, so a
base64-decoded or script-wrapped command is not caught; and a registry index is
trusted for its contents, not its authorship.

Verified: all internal links and heading anchors resolve, every docs/ page is
reachable from the README, 538 tests pass, typecheck clean.

docs/registry.md

@@ -126,3 +126,53 @@ add skill:review` disambiguates, and an ambiguous name is refused rather than gu
 
 A private index is just a URL you control. There is no account, no token, and no telemetry —
 `/registry` makes exactly one GET for the index and one for the entry you install.
+
+## Publishing
+
+Two files and a static host. GitHub raw works, and so does anything that serves JSON over https.
+
+```
+your-registry/
+  index.json
+  skills/migration.md
+  plugins/no-secrets.json
+```
+
+Three rules the validator enforces, so worth getting right first:
+
+- The name in `index.json` must match the name inside the file. A skill's frontmatter `name` and a
+  plugin manifest's `name` are both checked against the index entry.
+- Names are `^[a-z0-9][a-z0-9-]*$`. No uppercase, no dots, no slashes.
+- A plugin needs at least one deny rule. A manifest with an `appendix` and no rules is prompt
+  text, which is what a skill is for.
+
+Test it locally before publishing. `registryUrl` accepts `http://localhost`, so:
+
+```bash
+cd your-registry && python -m http.server 8000
+```
+
+```json
+{ "registryUrl": "http://localhost:8000/index.json" }
+```
+
+`/registry` then exercises the real fetch, the real validation, and the real install path against
+your files. That is the whole loop, without pushing anything.
+
+## Troubleshooting
+
+**"the registry index is malformed: …"** — the message names the first failing field. The usual
+causes are an uppercase name, a `url` that is not https, or a plugin entry with no `deny`.
+
+**"X calls itself Y but the index calls it X"** — the file's own name disagrees with the index.
+Fix one of the two; the check exists so an index cannot serve something else under a name you
+trusted.
+
+**"invalid pattern …"** — a `pathPattern` or `commandPattern` is not a valid regex. Remember it is
+JSON, so a backslash needs doubling: `\\.env$`, not `\.env$`.
+
+**Installed but nothing happens** — installs load at startup. Restart, then check `/skills` or
+`/plugins` for the entry and its origin.
+
+**In `/plugins` with an error beside it** — the manifest on disk no longer validates. It is skipped
+rather than fatal, so the agent still starts; `/registry remove` and reinstall.