Route the README by Reader and Document the Cross-Owner Write Grant

[ptr727]

The README opened straight into prose written for an agent, so a human arriving from GitHub had no path to what they actually ask: how to use this repo, how to deploy the host rules, how to diverge from one, and where to file an issue. It now forks by reader, and it carries the write-grant documentation that TODO.md recorded as ready in #629 without doing.

The README, routed by reader

A Getting Started table above the Table of Contents states the human/agent split outright, an agent starting at AGENTS.md and a human starting at the table, then routes six reader shapes to one destination each. Three new sections fill the gaps, placed in the slots spec/readme-structure.md already orders them in so the redesign does not fight the hub's own spec:

• Using This Repo (Installation slot), covering the host guardrails, carrying the rules into a repository, and an honest note that the registry does not transfer, so adopting outside this fleet means running your own hub.
• Diverging From a Rule (Configuration slot), which separates the two kinds of exception that get confused: a repository diverging from a carried unit, where the fidelity level usually already grants the freedom and the rest is recorded in spec/divergences.json, and a write the host guard denies.
• Questions or Issues, previously absent entirely, saying what an issue needs and that a downstream agent filing here is the normal path rather than an exception.

The cross-owner write grant

The guard denies a gh write whose explicit target sits under another owner and names GH_WRITE_GUARD_ALLOW in the denial, and no document said how to give one. docs/host-setup.md now carries it where the reader already is when the denial arrives:

• The fork asymmetry that raises it, where origin is your fork and only the half of the work aimed at upstream denies.
• The channel that works, an env block in the checkout's .claude/settings.local.json, which scopes the grant to that checkout rather than the host, and the session restart that loads it.
• The value's exact shape: one string and never a JSON array, split on any run of whitespace or commas, with owner/* granting a whole owner and a token carrying no / silently granting nothing. Verified against _granted_targets and _target_permitted.
• The two forms that fail silently, an inline VAR=x gh ... prefix and an export in a shell call, neither of which reaches a hook running as its own process. That is the property making a grant a deliberate act outside the session rather than something an agent does for itself once blocked.
• A confirmation that does not involve making the write. Worth recording: feeding the hook a synthetic payload is not a usable probe from inside a session, because the payload text carries the very write shape the guard matches, so the guard denies the probe command itself. Observed twice while writing this.

host-setup/agent-safety/README.md carries the mechanics beside the hook description and links across.

Also here

• The license shield moves into the closing License section, matching the form PlexCleaner carries. spec/readme-structure.md still states the old placement under Build and Distribution, so this README is deliberately ahead of the spec, and reconciling the two is the decision-state README Structure Rework cluster's edit rather than a loose end here. That cluster's Settled bullet asserting the old placement as fact is rewritten to record it.
• Proxmox drops out of every supported-platform list, since it is Linux. The two remaining mentions name the actual Proxmox host in the rollout, which is correct.
• untriaged joins the cspell word list, since the new Diverging section names the literal value the divergence report renders.
• TODO.md loses the shipped cluster and its orphaned link definitions, and the stale "Refresh the README" chore becomes the open question this change leaves behind: whether these human entry points belong in the spec so fleet repos are measured on them. The per-section index alternative is recorded as declined, with the reason.

Verification

markdownlint, cspell, editorconfig-checker, spec/validate.py, and scripts/prose_lint.py --diff develop all clean locally. CRLF preserved in every Markdown file, LF preserved in install.sh. Every relative link target and every in-file anchor resolves, checked mechanically.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the repository’s human-facing entry points and host write-safety documentation so humans can quickly find “how to use this repo” guidance, while keeping agent routing explicit and documenting the cross-owner write grant mechanics in the place readers will hit them.

Changes:

• Add a “Getting Started” reader-routing table and new sections (“Using This Repo”, “Diverging From a Rule”, “Questions or Issues”) to the README, and move the license shield into the License section.
• Document how to grant cross-owner GitHub write targets via GH_WRITE_GUARD_ALLOW (including scope, restart requirements, and confirmation) in docs/host-setup.md, with a corresponding pointer section in the agent-safety kit README.
• Clean up backlog tracking in TODO.md and add untriaged to the cspell word list.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
TODO.md	Removes the shipped “cross-owner write grant” cluster and updates README-structure backlog notes and link definitions.
README.md	Adds reader-routing and new guidance sections; relocates the license shield to the License section and adds issue/discussion entry guidance.
host-setup/agent-safety/README.md	Adds a “Granting a Cross-Owner Write” section pointing to the worked example in docs/host-setup.md.
host-setup/agent-safety/install.sh	Updates platform list in the wrapper comment (removes Proxmox mention).
docs/host-setup.md	Adds a detailed “Granting a Write the Guard Denies” section and updates platform list (removes Proxmox mention).
cspell.json	Adds untriaged to the dictionary.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.