Galley Docs

This is the routing index for Galley documentation, and the single source of truth for what to read when. AGENTS.md carries only the highest-frequency subset of the task table below; when the two disagree, this index wins and AGENTS.md needs the fix.

Read By Role

Role	Start Here
User evaluating Galley	README, then architecture
Agent / Supervisor integrator	Supervisor SOP, then Supervisor reference or agent-api
Contributor	CONTRIBUTING, then engineering workflow
Maintainer	project status, release / update SOP, release workflow, GA baseline
Historical reader	devlog, then archive
Coding agent	AGENTS.md, then the focused docs below

Read By Task

Task	Read First
Understand current project state	project status — current version, release gates, phase state
Understand the architecture	architecture — external-facing system overview
Change product behavior or roadmap	PRD — product definition and roadmap
Change CLI output or Agent API	agent-api — stable CLI / socket contract; v1 is frozen, additive-only
Change the Core ↔ runner wire protocol	IPC protocol — change docs first, then code
Change Supervisor / Agent integration	Supervisor SOP, then Supervisor reference
Plan or design Galley Native runtime	Galley Native — charter, RFC set, implementation slices
Check architecture invariants	architecture demo — code-level proofs and grep gates; hard engineering invariants (I3/I5/I6/I9/I11) are in engineering workflow
Prepare or update a release	release / update SOP (runbook), then release workflow (background)
Write GitHub Release notes	release notes guide — writing rules and bilingual templates
Close a long coding session or sync project knowledge	session close SOP
Smoke Windows builds	Windows checklist
Touch GenericAgent integration	GA baseline — pinned upstream compatibility
Touch app packaging / runtime	desktop runtime
Touch managed / bundled GA runtime	managed GA runtime — mode boundaries, patch discipline, state rules
Touch GUI or engineering workflow	engineering workflow — conventions plus hard invariants
Touch visual design	DESIGN.md
Look up domain vocabulary (turn numbering, seams, protocol terms)	CONTEXT.md — the ubiquitous-language glossary; engineering skills read it before exploring
Check whether a refactor direction was already decided against	ADRs — accepted architecture decisions; reviews must not re-litigate them
Track issues / PRDs for an in-flight feature	issue tracker — local markdown under .scratch/, triage states in triage labels
Grow the domain model (glossary + ADRs)	domain — how CONTEXT.md and docs/adr/ are maintained
Understand or change Galley's temperament / brand character	temperament charter — the "why" above the execution specs
Touch UI copy, terminology, or localization	copy and language guidelines (what to call things), copy austerity principles (how to say it)
Touch conversation text rendering / CJK typography	typography principles — render-only red line
Reshoot README screenshots / demo assets	screenshot playbook — includes the binary-asset policy
Review product / UX audit findings	audits — evidence-backed decision input, not specs
Understand history or decisions	devlog — chronological decision provenance
Dig into completed-mission docs (B-phase refactor, old drafts, handoffs)	archive

Lifecycle

Status is encoded by location, not per-file headers:

• docs/archive/** — archived. Mission complete; kept verbatim for provenance. Never a current rule.
• docs/devlog/** — historical by definition. Dated decision narrative; entries are never rewritten, only superseded by newer entries.
• Everything else under docs/ — living. Current rules and references, expected to be accurate today.

To archive a doc: pull any still-binding rules into a living doc, git mv the file into docs/archive/, add a short > **ARCHIVED <date>** banner saying where the living rules went, and update the table in archive README.

When a living doc grows past what one session can afford to read (~1000 lines), split it into a directory with its own README.md routing index, grouped by what a session typically needs together. The original path stays behind as a redirect stub so external references keep resolving. Current stubs: docs/DESIGN.md, docs/agent-api.md, docs/managed-ga-runtime.md.

Update Triggers

Living docs drift when nothing says who updates them and when. One table, one trigger event per doc — if you just did the event in the left column, the doc on the right is part of your change, not a follow-up:

When you…	You must update
Ship a release	project status (already in the release SOP)
Upgrade the GA baseline	GA baseline + managed patch notes; audit starts at runner/ga_session.py
Change the Agent API or IPC protocol	agent-api / IPC protocol first, then code (Rule 3)
Land a new seam, module, or pinned term	CONTEXT.md; record rejected directions as ADRs
Add a top-level module or cross-tier seam	architecture + architecture demo (file + symbol refs, never line numbers)
Write a devlog entry	add its row to devlog README in the same change
Change UI copy rules or visual specs	copy guidelines / design
Update the Supervisor SOP	re-sync the verbatim copy in .claude/skills/galley-supervisor/references/

Keep Docs Lean

Do not duplicate long history into task documents. Prefer:

• current rule in the focused document
• link to the devlog for why
• link to the playbook for how
• update AGENTS.md only for global rules every session must know
• this index is the only full routing table; do not grow parallel indexes

When adding a major new document: add one row to the task table above, and (only if it is truly high-frequency) one row to AGENTS.md. Binary assets follow the policy in screenshot playbook.