docs: reorganize repository documentation (#17)

Author: ThomasK33

AGENTS.md

@@ -29,8 +29,9 @@ Session state is stored under `~/.agent-terminal` by default. In tests and autom
 - `src/renderer/ghosttyWeb/backend.ts` — reference renderer and Playwright browser harness.
 - `src/export/asciicast.ts` and `src/export/webm.ts` — recording export logic.
 - `src/util/assert.ts` — shared fail-fast assertion helpers.
-- `design/20260319_agent-terminal-v1.md` — architecture and product intent.
-- `dogfood/` — proof bundles plus scripts for reviewer-facing validation artifacts.
+- `design/ARCHITECTURE.md` — stable architecture and product intent overview.
+- `ROADMAP.md` and `RELEASE.md` — shipped scope vs deferred scope at the repo root.
+- `dogfood/README.md` and `dogfood/CATALOG.md` — proof-bundle navigation and reviewer-facing validation artifacts.
 
 ## Important directories
 
@@ -43,7 +44,8 @@ Session state is stored under `~/.agent-terminal` by default. In tests and autom
 - `test/integration/` — CLI-level behavior against isolated temp homes.
 - `test/e2e/` — higher-level fixture-driven flows that assert rendered output and artifacts.
 - `test/fixtures/apps/` — tiny terminal apps used by e2e and dogfooding.
-- `design/` — architecture, roadmap, and dogfooding docs.
+- `design/` — architecture references and archived planning/status docs.
+- `docs/` — contributor and maintainer workflow docs.
 
 ## Architecture
 

README.md

@@ -30,6 +30,14 @@ agent-terminal --home "$AGENT_HOME" snapshot "$SESSION_ID" --format text --json
 agent-terminal --home "$AGENT_HOME" destroy "$SESSION_ID" --json
 ```
 
+## Documentation map
+
+- [`RELEASE.md`](./RELEASE.md) — the current `0.1.0` release contract.
+- [`ROADMAP.md`](./ROADMAP.md) — intentionally deferred work and post-release direction.
+- [`design/README.md`](./design/README.md) — architecture references plus archived week-by-week planning.
+- [`dogfood/CATALOG.md`](./dogfood/CATALOG.md) — curated proof bundles and recommended review paths.
+- [`docs/README.md`](./docs/README.md) — contributor and maintainer navigation.
+
 ## Feature highlights
 
 - Full session lifecycle management: create, inspect, list, wait, destroy, and garbage-collect.
@@ -41,9 +49,8 @@ agent-terminal --home "$AGENT_HOME" destroy "$SESSION_ID" --json
 ## 0.1.0 release focus
 
 `agent-terminal` `0.1.0` is the first release aimed at reliable, isolated, reviewable TUI automation.
-Week 9 closes the release-readiness bar around the new `run` command, isolated-environment renderer reliability, and isolation-aware `doctor` diagnostics.
-For the explicit release contract, see [`RELEASE.md`](./RELEASE.md).
-Reviewer-facing proof bundles live under `dogfood/`, including `dogfood/20260326-week9-release-readiness/`, `dogfood/run-command/`, and `dogfood/20260325-week8-contract-locks/`.
+For the explicit shipping contract, see [`RELEASE.md`](./RELEASE.md). For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md).
+Reviewer-facing proof bundles are curated in [`dogfood/CATALOG.md`](./dogfood/CATALOG.md), with current release-signoff evidence in `dogfood/20260326-week9-release-readiness/` and evergreen workflow coverage such as `dogfood/run-command/`.
 
 ## TUI Workflow
 
@@ -214,15 +221,16 @@ npm run verify
 ```
 
 That runs formatting, linting, typechecking, unit/e2e tests, and the production build.
+For contributor workflow and release hygiene, see [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) and [`docs/RELEASE-PROCESS.md`](./docs/RELEASE-PROCESS.md).
 
 ## Design docs
 
-Design and implementation notes live under `design/`, especially `design/20260319_agent-terminal-v1/`.
-See `design/20260319_agent-terminal-v1/` for architecture, weekly plans, and status docs through Week 9, and see [`RELEASE.md`](./RELEASE.md) for the `0.1.0` contract.
+Design and implementation notes live under [`design/`](./design/README.md).
+Start with [`design/ARCHITECTURE.md`](./design/ARCHITECTURE.md) for the stable overview, use [`design/20260319_agent-terminal-v1/`](./design/20260319_agent-terminal-v1/) for the active reference set, and use [`design/archive/`](./design/archive/) for week-by-week project history.
 
 ## Repository notes
 
 - CI uses `mise` for tool provisioning and quality-gate entrypoints.
 - Chromium is required locally for screenshot and replay export coverage.
 - Platform support tiers are documented in this README; see also the design docs for detailed status.
-- Dogfood proof bundles and validation notes live under `dogfood/` and `design/`.
+- Dogfood proof bundles and review guidance live under [`dogfood/README.md`](./dogfood/README.md) and [`dogfood/CATALOG.md`](./dogfood/CATALOG.md).

RELEASE.md

@@ -2,7 +2,8 @@
 
 `agent-terminal` `0.1.0` is the first release that explicitly targets isolated, reviewable terminal automation for real TUI workflows.
 The contract below is the bar for what maintainers should feel comfortable supporting at release time.
-If a workflow depends on behavior outside this document, it should be treated as future-scope or best-effort rather than a guaranteed `0.1.0` capability.
+If a workflow depends on behavior outside this document, treat it as future-scope or best-effort rather than a guaranteed `0.1.0` capability.
+For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md). For reviewer-facing proof bundles, start with [`dogfood/CATALOG.md`](./dogfood/CATALOG.md).
 
 ## What 0.1.0 delivers
 
@@ -32,6 +33,6 @@ If a workflow depends on behavior outside this document, it should be treated as
 
 ## Validation
 
-- Current release bar: 595 tests across 56 test files.
-- Reviewer-facing proof bundles live under `dogfood/`, including `dogfood/20260326-week9-release-readiness/`, `dogfood/run-command/`, and `dogfood/20260325-week8-contract-locks/`.
+- Current release bar: 602 tests across 56 test files.
+- Reviewer-facing proof bundles are cataloged in [`dogfood/CATALOG.md`](./dogfood/CATALOG.md), including `dogfood/20260326-week9-release-readiness/`, `dogfood/run-command/`, and `dogfood/20260325-week8-contract-locks/`.
 - Run `npm run verify` for the full validation bar.

ROADMAP.md

@@ -0,0 +1,39 @@
+# agent-terminal roadmap
+
+`RELEASE.md` defines what `0.1.0` ships today. This roadmap tracks intentionally deferred work and post-release direction so the repository front door separates shipped scope from future scope.
+For historical week-by-week planning and status context, see [`design/archive/`](./design/archive/). For the stable design overview, see [`design/ARCHITECTURE.md`](./design/ARCHITECTURE.md).
+
+## Near-term refinements
+
+- Broader reviewer-oriented introspection in `inspect --json`, especially around live renderer/session state when that adds clear operational value.
+- Stronger proof-bundle conventions and automation so canonical `dogfood/` bundles stay easy to review and harder to let drift.
+- Continued hardening around renderer/bootstrap ergonomics in isolated environments.
+
+## Renderer and platform expansion
+
+- Native renderer adapters beyond the current `ghostty-web` reference backend.
+- Broader native-platform parity work, especially where Windows or native terminals diverge from the reference renderer.
+- Follow-on renderer hardening such as tighter CSP or sandbox assumptions if the backend model evolves.
+
+## Input and automation expansion
+
+- Mouse input support.
+- Richer semantic TUI automation beyond the current shell-oriented lifecycle, wait, snapshot, screenshot, and export flows.
+- Additional higher-level workflows only after they fit the event-log-as-truth model and do not undermine the stable CLI surface.
+
+## System integration
+
+- Remote or networked session control.
+- An MCP wrapper or other external control layers built on top of the CLI contract.
+
+## Data-model redesigns
+
+- Broader failure-taxonomy work beyond the current shipped termination/reporting categories.
+- Event-log redesign only if the current append-only model proves too limiting for replay or recovery needs.
+- Snapshot-schema expansion where the existing structured surface is not sufficient for review or automation use cases.
+
+## Prioritization notes
+
+1. Preserve the current release contract before widening scope.
+2. Prefer incremental additions that reuse the existing CLI, storage, replay, and artifact model.
+3. Archive historical planning/status detail instead of mixing it back into the roadmap.

WEEK2-GAPS.md

@@ -58,7 +58,7 @@ The current renderer/export path is:
 
 `inspect` now also exposes shipped artifact-health reporting derived from the artifact manifest plus on-disk files. That summary reports artifact totals, `byKind` counts, `missingCount`, an overall `health` value (`healthy`, `missing-artifacts`, `manifest-invalid`, `no-artifacts`, or `unknown`), and optional per-artifact `missing` details when files referenced by the manifest are absent on disk.
 
-Remaining follow-on work is now mostly about design parity and broader future-scope renderer/runtime expansion rather than missing artifact classes. The repo already ships scrollback snapshots, optional per-cell snapshot data, bundled deterministic fonts, and replay timing modes. The main still-open design items are the fuller event-log and snapshot-schema redesigns plus later native/parity work tracked in [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md).
+Remaining follow-on work is now mostly about design parity and broader future-scope renderer/runtime expansion rather than missing artifact classes. The repo already ships scrollback snapshots, optional per-cell snapshot data, bundled deterministic fonts, and replay timing modes. The main still-open design items are the fuller event-log and snapshot-schema redesigns plus later native/parity work tracked in [`../../ROADMAP.md`](../../ROADMAP.md).
 
 ## 4. Canonical replay model
 
@@ -544,4 +544,4 @@ The remaining design-level follow-ons are now narrower:
 - whether to expand per-cell metadata beyond the currently shipped fields (for example `width`, `inverse`, `blink`, `dim`, or richer cursor metadata),
 - runtime renderer capability discovery beyond the current static backend list,
 - larger event-log and snapshot-schema redesign questions,
-- and later native renderer/parity work tracked in [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md).
+- and later native renderer/parity work tracked in [`../../ROADMAP.md`](../../ROADMAP.md).