Docs + minimal community-health files for self-service human/agent onboarding

[BreadrichEngels]

Goal

Let a first-time human editor — or an AI agent acting on their behalf — clone the repo, run it, edit content via Keystatic, and ship a PR using only the repo's own docs. No prior training required.

Note

Spec/audit issue. The actual file contents are to be authored by @rathermercurial — this issue just describes what should exist and why. Don't pre-write the files here.

Audit (main @ e936576)

• README.md — mixes human onboarding with deep technical reference, embeds command/code blocks, and duplicates the Keystatic workflow that also lives in AGENTS.md.
• AGENTS.md — already at repo root per the agents.md standard; solid, but internally duplicated (Keystatic workflow appears twice) and missing a few lifecycle steps (clone, stopping the dev server, running checks, resolving conflicts).
• CONTRIBUTING.md / GOVERNANCE.md — absent.

Changes

README.md — human-facing

• Rewrite for a non-technical reader: what it is → how to get involved → where to go next.
• Prose, no code examples; link to AGENTS.md / CONTRIBUTING.md instead of repeating them.
• Tight and accurate (no slop); checked against package.json and configs.

AGENTS.md — agent manual

• Collapse to one clean end-to-end recipe; remove the duplicated Keystatic walkthrough.
• Make the full lifecycle explicit: clone → verify prereqs → branch → run dev server → edit via Keystatic (or on the user's behalf) → open/manage PR → run checks & fix conflicts → stop the dev server → GitHub follow-up.
• Reference the merge policy from GOVERNANCE.md.

CONTRIBUTING.md — new, minimal

• The two paths: content via Keystatic, code/config via PR.
• Branch convention, how to open a good PR, where to get help; link to GOVERNANCE.md for merge rules.

GOVERNANCE.md — new, minimal

• Who can merge and how decisions get made — lightweight.
• Write a minimum-viable merge policy in proper form. Treat the note below only as a rough seed to iterate from — refine the wording and structure, don't lift it as-is:

  e.g. content-only changes that pass checks can merge; code changes need a maintainer review + merge; failing checks or conflicts get fixed on the branch before review is requested.

Keep community-health scope to CONTRIBUTING.md + GOVERNANCE.md only — no code of conduct, issue/PR templates, or license work in this issue.

One decision for @rathermercurial

You mentioned a .agents/agents.md location. The standard that agent runtimes auto-load is root AGENTS.md, which is already in place — recommend keeping it there. (.agents/ is only a draft proposal.) Confirm and we leave it at root.

References

• agents.md standard
• contributing.md (guides + governance patterns)
• GitHub community health files
• Keystatic — GitHub mode