diff --git a/AGENTS.md b/AGENTS.md index 9bfa1e7..940aec1 100644 --- a/AGENTS.md +++ b/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 diff --git a/README.md b/README.md index efce60c..585e16d 100644 --- a/README.md +++ b/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). diff --git a/RELEASE.md b/RELEASE.md index 46470ec..b85c672 100644 --- a/RELEASE.md +++ b/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. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..fa5a837 --- /dev/null +++ b/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. diff --git a/WEEK2-GAPS.md b/WEEK2-GAPS.md deleted file mode 100644 index 01af5c9..0000000 --- a/WEEK2-GAPS.md +++ /dev/null @@ -1,65 +0,0 @@ -# Remaining future-scope gaps after Week 7 - -> Historical note: this file keeps its original filename (`WEEK2-GAPS.md`) because earlier design docs and proof bundles already reference it. Its contents now describe the current post-Week-7 delta rather than the original Week 2-only gap list. - -Week 1 control-plane work, Week 2 renderer-backed inspection, Week 3 export / retention, Week 4 CLI / artifact / lifecycle hardening, Week 5 config/rendering/platform closeout, Week 6 contract/introspection/failure-taxonomy reconciliation, and the Week 7 contract/doc synchronization pass have all landed. This file now tracks only intentionally deferred future scope. - -## Week 6 closures (now shipped) - -### CLI contract and inspection surfaces - -- **`inspect` result-shape enrichment** — **Shipped / closed:** `src/cli/commands/inspect.ts` now emits `lastEventSeq`, derived `terminationCategory`, computed `artifacts`, and `usedOfflineReplay`, with schema support in `src/protocol/messages.ts` and contract coverage in `test/unit/commands/inspect.test.ts` plus `test/unit/commands/golden-envelopes.test.ts` (`9b14ed2`, `387fc2e`). -- **`version --json` backend reporting** — **Shipped / closed:** `src/cli/commands/version.ts` now reports `rendererBackends: ['ghostty-web']`, with unit and integration coverage in `test/unit/commands/version.test.ts` and `test/integration/cli.test.ts` (`a4ae0c9`). -- **Golden-envelope contract coverage** — **Shipped / closed:** `test/unit/commands/golden-envelopes.test.ts` now locks the shipped `inspect`, `version`, and representative error envelopes so machine-facing drift fails loudly (`387fc2e`). - -### Artifact introspection - -- **Artifact-health surfacing** — **Shipped / closed:** `src/storage/artifactHealth.ts` computes total counts, `byKind`, missing-artifact detection, and overall health; `inspect` now exposes that summary directly so reviewers do not need to spelunk `artifacts/manifest.json` by hand (`a8f33cf`, `9b14ed2`). - -### Failure semantics and recovery reporting - -- **Persisted `failureOrigin` plus derived `terminationCategory`** — **Shipped / closed:** `src/protocol/schemas.ts` now carries structured `failureOrigin` in session state, `src/host/lifecycle.ts` stamps stale-host reconciliation as `host-death`, `src/host/terminationCategory.ts` derives the higher-level termination summary, and `inspect` exposes the result (`9782608`). -- **Broader recovery reporting coverage** — **Shipped / closed for the planned Week 6 scope:** the repo now distinguishes clean exit, non-zero exit, signal exit, host death, renderer failure, destroyed sessions, and offline replay fallback in the public inspection surface and related tests. - -### Supporting closeout work - -- **Doctor result-shape cleanup** — **Shipped / closed:** `DoctorCheck` now requires `durationMs`, removing an avoidable contract inconsistency (`56276de`). -- **Week 6 design/code reconciliation** — **Shipped / closed:** the Week 6 docs now record the contract/introspection/failure work as shipped status rather than leaving it in the open-gap bucket. - -## Week 7 closures (now shipped) - -- **`send-keys` result enrichment** — **Shipped / closed:** the shipped result now exposes `accepted`, `bytesWritten`, and `seq` via `src/cli/commands/send-keys.ts` and `SendKeysResultSchema`, with coverage in `test/unit/protocol/messages.test.ts`, `test/integration/pty-basics.test.ts`, and the relevant e2e flows. -- **`destroy` result-schema alignment** — **Shipped / closed:** the shipped result now exposes `{ sessionId, destroyed }` via `src/cli/commands/destroy.ts` and `DestroyResultSchema`, with coverage in `test/unit/protocol/messages.test.ts`, `test/integration/lifecycle.test.ts`, and the relevant e2e flows. -- **High-value CLI contract/doc ratification** — **Shipped / closed:** `design/20260319_agent-terminal-v1/02-cli-contract.md` and the top-level design entrypoint now match the shipped `create`, `list`, `type`, `paste`, `send-keys`, `snapshot`, `screenshot`, `resize`, and `destroy` behavior instead of leaving Week 7 doc drift in the open-gap bucket. - -## Remaining future-scope gaps - -- **Runtime renderer capability discovery** — **Future scope:** `version --json` currently reports the static compiled-in backend list `['ghostty-web']`; it does not yet discover capabilities dynamically at runtime. -- **Richer live renderer-state reporting in `inspect`** — **Future scope:** the shipped `inspect` surface now reports artifact health and termination categories, but it does not expose a larger live renderer-state block. -- **Broader failure taxonomy beyond the current shipped categories** — **Future scope:** Week 6 made the current categories explicit, but it did not introduce a larger redesign of every possible host/renderer/storage failure class. - -### Renderer/runtime expansion - -- **Native renderer adapters** — **Future scope / not started:** still not implemented. -- **Mouse input support** — **Future scope / not started:** still not implemented. -- **Remote/network sessions** — **Future scope / not started:** still not implemented. -- **MCP wrapper** — **Future scope / not started:** still not implemented. -- **Cross-platform rendering parity** — **Future scope:** the reference renderer remains the source of deterministic review truth, and Windows/native parity is still behind the design's broader ambition. -- **Renderer CSP hardening** — **Future scope:** the localhost-only `ghostty-web` harness still carries the current CSP trade-off. - -### Larger model/data redesigns - -- **Full event-log redesign** — **Future scope:** Week 6 did not replace the current append-only event-log model with a broader new format. -- **Full snapshot-schema redesign** — **Future scope:** the shipped snapshot surface is richer than Week 2 but still narrower than the fullest schema described in the design docs. - -## Recommended next step - -The next planned milestone is Week 8. It should treat the Week 1–7 contract/doc ratification work as closed and first close the remaining runtime-capability/reporting discipline gaps before moving further down the broader deferred roadmap: - -1. runtime renderer capability discovery plus richer live renderer state/reporting, -2. the remaining lower-priority public-envelope locks and proof-bundle validation, -3. native renderers and broader platform parity, -4. mouse input, remote/network sessions, and an MCP wrapper, -5. and larger model/data redesigns such as fuller failure taxonomy, event-log redesign, snapshot-schema expansion, and renderer CSP hardening. - -See `design/20260319_agent-terminal-v1/16-week-8-plan.md` for the current next-step plan, `design/20260319_agent-terminal-v1/15-week-7-plan.md` for the completed Week 7 ratification context, and the design docs under `design/20260319_agent-terminal-v1/` for the broader roadmap context. diff --git a/design/20260319_agent-terminal-v1/03-rendering-and-artifacts.md b/design/20260319_agent-terminal-v1/03-rendering-and-artifacts.md index 5efda45..b1065eb 100644 --- a/design/20260319_agent-terminal-v1/03-rendering-and-artifacts.md +++ b/design/20260319_agent-terminal-v1/03-rendering-and-artifacts.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). diff --git a/design/20260319_agent-terminal-v1.md b/design/ARCHITECTURE.md similarity index 87% rename from design/20260319_agent-terminal-v1.md rename to design/ARCHITECTURE.md index 8792fb9..0ef97f7 100644 --- a/design/20260319_agent-terminal-v1.md +++ b/design/ARCHITECTURE.md @@ -3,7 +3,7 @@ author: "@mux" date: 2026-03-19 --- -# agent-terminal v1 +# agent-terminal architecture overview `agent-terminal` is a CLI-first terminal automation system for AI agents and humans. @@ -40,7 +40,9 @@ The repository now ships the first three milestones of this design plus Weeks 4 - macOS CI validation, - and proof bundles under `dogfood/`. -Week 7 closed the design-synchronization pass for the shipped v1 surface. Week 8 then completed runtime capability discovery, richer renderer/session introspection, the remaining lower-priority public-envelope locks, and proof-bundle normalization/validation. Week 9 then closed the pre-`0.1.0` release-readiness milestone: isolated-environment renderer reliability is now part of the shipped contract, the higher-level in-session `run` primitive is documented and shipped, TUI-focused diagnostics/docs are in place, and the remaining large asks are intentionally deferred future-scope work rather than release blockers. The intentionally deferred platform/runtime work is tracked separately in [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md). See [14-week-6-status.md](./20260319_agent-terminal-v1/14-week-6-status.md), [15-week-7-plan.md](./20260319_agent-terminal-v1/15-week-7-plan.md), [16-week-8-plan.md](./20260319_agent-terminal-v1/16-week-8-plan.md), [17-week-9-plan.md](./20260319_agent-terminal-v1/17-week-9-plan.md), [`../RELEASE.md`](../RELEASE.md), and [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md) for the current state. +Week 7 closed the design-synchronization pass for the shipped v1 surface. Week 8 then completed runtime capability discovery, richer renderer/session introspection, the remaining lower-priority public-envelope locks, and proof-bundle normalization/validation. Week 9 then closed the pre-`0.1.0` release-readiness milestone: isolated-environment renderer reliability is now part of the shipped contract, the higher-level in-session `run` primitive is documented and shipped, TUI-focused diagnostics/docs are in place, and the remaining large asks are intentionally deferred future-scope work rather than release blockers. + +The stable contract and deferred work now have dedicated homes: use [`../RELEASE.md`](../RELEASE.md) for the shipping bar, [`../ROADMAP.md`](../ROADMAP.md) for future scope, [`./README.md`](./README.md) for the design index, and [`./archive/`](./archive/) for the historical week-by-week planning/status trail. ## Executive summary @@ -195,25 +197,30 @@ Asciicast and replay-video export remain intended follow-on capabilities rather ## Deliverables in this design set -This design file is the entry point. Detailed supporting docs live in `design/20260319_agent-terminal-v1/`. +This design file is the entry point. Detailed supporting docs live in the active reference set under `design/20260319_agent-terminal-v1/`, while historical planning/status material lives under `design/archive/`. + +### Active reference set - [01-architecture.md](./20260319_agent-terminal-v1/01-architecture.md) - [02-cli-contract.md](./20260319_agent-terminal-v1/02-cli-contract.md) - [03-rendering-and-artifacts.md](./20260319_agent-terminal-v1/03-rendering-and-artifacts.md) - [04-implementation-plan.md](./20260319_agent-terminal-v1/04-implementation-plan.md) - [05-dogfooding-and-validation.md](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md) -- [06-roadmap-and-week-1-plan.md](./20260319_agent-terminal-v1/06-roadmap-and-week-1-plan.md) -- [07-week-2-plan.md](./20260319_agent-terminal-v1/07-week-2-plan.md) -- [08-week-3-status.md](./20260319_agent-terminal-v1/08-week-3-status.md) -- [09-week-4-plan.md](./20260319_agent-terminal-v1/09-week-4-plan.md) -- [10-week-4-status.md](./20260319_agent-terminal-v1/10-week-4-status.md) -- [11-week-5-plan.md](./20260319_agent-terminal-v1/11-week-5-plan.md) -- [12-week-5-status.md](./20260319_agent-terminal-v1/12-week-5-status.md) -- [13-week-6-plan.md](./20260319_agent-terminal-v1/13-week-6-plan.md) -- [14-week-6-status.md](./20260319_agent-terminal-v1/14-week-6-status.md) -- [15-week-7-plan.md](./20260319_agent-terminal-v1/15-week-7-plan.md) -- [16-week-8-plan.md](./20260319_agent-terminal-v1/16-week-8-plan.md) -- [17-week-9-plan.md](./20260319_agent-terminal-v1/17-week-9-plan.md) + +### Historical archive + +- [06-roadmap-and-week-1-plan.md](./archive/06-roadmap-and-week-1-plan.md) +- [07-week-2-plan.md](./archive/07-week-2-plan.md) +- [08-week-3-status.md](./archive/08-week-3-status.md) +- [09-week-4-plan.md](./archive/09-week-4-plan.md) +- [10-week-4-status.md](./archive/10-week-4-status.md) +- [11-week-5-plan.md](./archive/11-week-5-plan.md) +- [12-week-5-status.md](./archive/12-week-5-status.md) +- [13-week-6-plan.md](./archive/13-week-6-plan.md) +- [14-week-6-status.md](./archive/14-week-6-status.md) +- [15-week-7-plan.md](./archive/15-week-7-plan.md) +- [16-week-8-plan.md](./archive/16-week-8-plan.md) +- [17-week-9-plan.md](./archive/17-week-9-plan.md) ## High-level architecture diff --git a/design/README.md b/design/README.md new file mode 100644 index 0000000..2a2bc8f --- /dev/null +++ b/design/README.md @@ -0,0 +1,35 @@ +# Design documentation + +Use this directory as the navigation hub for architecture and design material. +The active reference set stays separate from the week-by-week project history so newcomers can find the stable docs first. + +## Start here + +1. [`ARCHITECTURE.md`](./ARCHITECTURE.md) — stable product and architecture overview. +2. [`20260319_agent-terminal-v1/02-cli-contract.md`](./20260319_agent-terminal-v1/02-cli-contract.md) — CLI contract details. +3. [`20260319_agent-terminal-v1/03-rendering-and-artifacts.md`](./20260319_agent-terminal-v1/03-rendering-and-artifacts.md) — replay, screenshot, and export model. +4. [`20260319_agent-terminal-v1/05-dogfooding-and-validation.md`](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md) — proof-bundle expectations. + +## Active reference set + +The original v1 design review produced a focused reference set that is still useful as evergreen technical documentation: + +- [`20260319_agent-terminal-v1/01-architecture.md`](./20260319_agent-terminal-v1/01-architecture.md) +- [`20260319_agent-terminal-v1/02-cli-contract.md`](./20260319_agent-terminal-v1/02-cli-contract.md) +- [`20260319_agent-terminal-v1/03-rendering-and-artifacts.md`](./20260319_agent-terminal-v1/03-rendering-and-artifacts.md) +- [`20260319_agent-terminal-v1/04-implementation-plan.md`](./20260319_agent-terminal-v1/04-implementation-plan.md) +- [`20260319_agent-terminal-v1/05-dogfooding-and-validation.md`](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md) + +## Historical archive + +Week-by-week plans and status reports now live under [`archive/`](./archive/). They remain part of the repository because they explain how the current surface evolved, but they are historical context rather than the primary discovery path. + +- [`archive/README.md`](./archive/README.md) +- [`archive/06-roadmap-and-week-1-plan.md`](./archive/06-roadmap-and-week-1-plan.md) +- [`archive/17-week-9-plan.md`](./archive/17-week-9-plan.md) + +## Related docs + +- [`../RELEASE.md`](../RELEASE.md) — current shipping contract. +- [`../ROADMAP.md`](../ROADMAP.md) — deferred work and post-release direction. +- [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) — curated proof bundles. diff --git a/design/20260319_agent-terminal-v1/06-roadmap-and-week-1-plan.md b/design/archive/06-roadmap-and-week-1-plan.md similarity index 100% rename from design/20260319_agent-terminal-v1/06-roadmap-and-week-1-plan.md rename to design/archive/06-roadmap-and-week-1-plan.md diff --git a/design/20260319_agent-terminal-v1/07-week-2-plan.md b/design/archive/07-week-2-plan.md similarity index 100% rename from design/20260319_agent-terminal-v1/07-week-2-plan.md rename to design/archive/07-week-2-plan.md diff --git a/design/20260319_agent-terminal-v1/08-week-3-status.md b/design/archive/08-week-3-status.md similarity index 100% rename from design/20260319_agent-terminal-v1/08-week-3-status.md rename to design/archive/08-week-3-status.md diff --git a/design/20260319_agent-terminal-v1/09-week-4-plan.md b/design/archive/09-week-4-plan.md similarity index 100% rename from design/20260319_agent-terminal-v1/09-week-4-plan.md rename to design/archive/09-week-4-plan.md diff --git a/design/20260319_agent-terminal-v1/10-week-4-status.md b/design/archive/10-week-4-status.md similarity index 97% rename from design/20260319_agent-terminal-v1/10-week-4-status.md rename to design/archive/10-week-4-status.md index a956f96..37fab7e 100644 --- a/design/20260319_agent-terminal-v1/10-week-4-status.md +++ b/design/archive/10-week-4-status.md @@ -106,7 +106,7 @@ This documentation update is the WS5 landing step: - `02-cli-contract.md` now marks shipped vs future CLI items, - `03-rendering-and-artifacts.md` now marks shipped vs future rendering items, - `05-dogfooding-and-validation.md` now records current coverage and remaining validation gaps, -- and `WEEK2-GAPS.md` now tracks the post-Week-4 remaining delta rather than the older post-Week-3 view. +- and [`../../ROADMAP.md`](../../ROADMAP.md) now tracks the post-Week-4 remaining delta rather than the older post-Week-3 view. ## Test coverage summary @@ -170,4 +170,4 @@ Week 4 did not eliminate the need for the larger v1 design docs; it narrowed the - a record of the intended v1 contract, - annotated by what shipped in Week 4, -- with the remaining follow-on work captured in `WEEK2-GAPS.md`. +- with the remaining follow-on work captured in [`../../ROADMAP.md`](../../ROADMAP.md). diff --git a/design/20260319_agent-terminal-v1/11-week-5-plan.md b/design/archive/11-week-5-plan.md similarity index 100% rename from design/20260319_agent-terminal-v1/11-week-5-plan.md rename to design/archive/11-week-5-plan.md diff --git a/design/20260319_agent-terminal-v1/12-week-5-status.md b/design/archive/12-week-5-status.md similarity index 98% rename from design/20260319_agent-terminal-v1/12-week-5-status.md rename to design/archive/12-week-5-status.md index 079d9a1..6746876 100644 --- a/design/20260319_agent-terminal-v1/12-week-5-status.md +++ b/design/archive/12-week-5-status.md @@ -58,4 +58,4 @@ The remaining future scope is now concentrated in native/platform/runtime expans ## What remains for future work - The post-Week-5 delta is now concentrated in native renderer work, broader failure semantics, cross-platform parity, and related platform/runtime hardening rather than foundational CLI/config wiring. -- See `WEEK2-GAPS.md` for the detailed remaining gap list. +- See [`../../ROADMAP.md`](../../ROADMAP.md) for the detailed remaining gap list. diff --git a/design/20260319_agent-terminal-v1/13-week-6-plan.md b/design/archive/13-week-6-plan.md similarity index 100% rename from design/20260319_agent-terminal-v1/13-week-6-plan.md rename to design/archive/13-week-6-plan.md diff --git a/design/20260319_agent-terminal-v1/14-week-6-status.md b/design/archive/14-week-6-status.md similarity index 97% rename from design/20260319_agent-terminal-v1/14-week-6-status.md rename to design/archive/14-week-6-status.md index 2af1dab..0625d3d 100644 --- a/design/20260319_agent-terminal-v1/14-week-6-status.md +++ b/design/archive/14-week-6-status.md @@ -79,4 +79,4 @@ So the Week 6 functional/contract work shipped, but proof-bundle completeness re - The high-value `inspect` / `version` / artifact-health / failure-reporting code gaps that Week 6 set out to close are done, but full CLI/example ratification and proof-bundle completeness still remain as Week 7 carry-over work. - Beyond that carry-over work, the remaining larger delta is future-scope platform/runtime expansion and data-model redesign questions. -- See `WEEK2-GAPS.md` and [15-week-7-plan.md](./15-week-7-plan.md) for the current detailed gap list and next-step plan. +- See [`../../ROADMAP.md`](../../ROADMAP.md) and [15-week-7-plan.md](./15-week-7-plan.md) for the current detailed gap list and next-step plan. diff --git a/design/20260319_agent-terminal-v1/15-week-7-plan.md b/design/archive/15-week-7-plan.md similarity index 100% rename from design/20260319_agent-terminal-v1/15-week-7-plan.md rename to design/archive/15-week-7-plan.md diff --git a/design/20260319_agent-terminal-v1/16-week-8-plan.md b/design/archive/16-week-8-plan.md similarity index 99% rename from design/20260319_agent-terminal-v1/16-week-8-plan.md rename to design/archive/16-week-8-plan.md index 49c7d22..4ad7fbd 100644 --- a/design/20260319_agent-terminal-v1/16-week-8-plan.md +++ b/design/archive/16-week-8-plan.md @@ -25,7 +25,7 @@ That audit found that the Week 1–7 plan and status docs are materially reflect - the intentionally deferred lower-priority public-envelope locks for `doctor`, `gc`, and `record export`, - and proof-bundle standard enforcement, where the docs describe a stronger preferred minimum than the repo currently validates automatically. -See [15-week-7-plan.md](./15-week-7-plan.md), [05-dogfooding-and-validation.md](./05-dogfooding-and-validation.md), and [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md) for the current context this plan continues from. +See [15-week-7-plan.md](./15-week-7-plan.md), [05-dogfooding-and-validation.md](./05-dogfooding-and-validation.md), and [`../../ROADMAP.md`](../../ROADMAP.md) for the current context this plan continues from. As work lands, this file should be updated in place the same way the earlier weekly plan/status docs were kept in sync: diff --git a/design/20260319_agent-terminal-v1/17-week-9-plan.md b/design/archive/17-week-9-plan.md similarity index 100% rename from design/20260319_agent-terminal-v1/17-week-9-plan.md rename to design/archive/17-week-9-plan.md diff --git a/design/archive/README.md b/design/archive/README.md new file mode 100644 index 0000000..4d76be7 --- /dev/null +++ b/design/archive/README.md @@ -0,0 +1,6 @@ +# Historical design archive + +This directory preserves the week-by-week planning and status trail that accompanied the initial `agent-terminal` v1 build-out. +These files remain useful for historical context, but they are no longer the primary entry point for understanding the current product surface. + +Use [`../README.md`](../README.md) for the current design index and [`../ARCHITECTURE.md`](../ARCHITECTURE.md) for the stable overview. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..5bd0c93 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing + +## Setup + +Preferred setup uses `mise`: + +```bash +mise install +mise run bootstrap +``` + +Fallback setup if `mise` is unavailable: + +```bash +npm ci +npx playwright install chromium +``` + +## Day-to-day workflow + +- Use `npx tsx src/cli/main.ts ...` while developing from the source tree. +- Prefer `--json` when a workflow needs machine-readable output. +- Use an isolated absolute `AGENT_TERMINAL_HOME` for tests and manual dogfooding. +- Keep storage writes, manifests, and protocol updates inside the existing validated helpers and schemas. + +## Validation + +Run the smallest meaningful checks while iterating, then finish with the full repo bar when the change warrants it: + +```bash +npm run format:check +npm run lint +npm run typecheck +npm run test +npm run build +``` + +Or use the combined entry point: + +```bash +npm run verify +``` + +If you touch the public skill, also run: + +```bash +npm run intent:validate +``` + +## Documentation and proof expectations + +- Keep the root docs split clear: `README.md` for overview, `RELEASE.md` for current scope, `ROADMAP.md` for future scope. +- Update [`design/README.md`](../design/README.md) when the active vs archived design split changes. +- Update [`dogfood/CATALOG.md`](../dogfood/CATALOG.md) when you add or promote a reviewer-facing proof bundle. +- Prefer public `agent-terminal ...` invocations in shipped skill/docs examples; do not commit repo-local `npx tsx src/cli/main.ts ...` substitutions into public-facing examples. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e171a5f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +# Contributor and maintainer docs + +Use this directory when you need project workflow guidance rather than product-facing documentation. + +- [`../README.md`](../README.md) — product overview and quick start. +- [`../RELEASE.md`](../RELEASE.md) — current shipping contract. +- [`../ROADMAP.md`](../ROADMAP.md) — deferred work and post-release direction. +- [`../design/README.md`](../design/README.md) — architecture and design references. +- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — setup, validation, and day-to-day contribution flow. +- [`RELEASE-PROCESS.md`](./RELEASE-PROCESS.md) — maintainer release checklist and proof expectations. +- [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) — curated proof bundles for review. diff --git a/docs/RELEASE-PROCESS.md b/docs/RELEASE-PROCESS.md new file mode 100644 index 0000000..1e6e784 --- /dev/null +++ b/docs/RELEASE-PROCESS.md @@ -0,0 +1,30 @@ +# Release process + +`RELEASE.md` defines the shipping contract. This document describes how maintainers should validate and present that contract. + +## Before cutting a release + +1. Re-read [`../RELEASE.md`](../RELEASE.md) and confirm it still matches the shipped surface. +2. Re-read [`../ROADMAP.md`](../ROADMAP.md) and confirm deferred work is not mixed back into the release contract. +3. Verify the primary docs route correctly from [`../README.md`](../README.md) to release, roadmap, design, and dogfood materials. +4. Review [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) and make sure the release-signoff bundle is current and easy to find. + +## Validation bar + +Run the full repo validation command: + +```bash +npm run verify +``` + +If the public skill changed, also run: + +```bash +npm run intent:validate +``` + +## Proof expectations + +- Keep at least one current release-readiness bundle under `dogfood/`. +- Keep evergreen scenario bundles easy to discover from the dogfood catalog. +- When a change affects renderer, screenshot, wait, export, or review UX, include screenshots and recordings in the relevant proof bundle when feasible. diff --git a/dogfood/20260323-week5-platform-closure/notes.md b/dogfood/20260323-week5-platform-closure/notes.md index 0232fc8..0751ba4 100644 --- a/dogfood/20260323-week5-platform-closure/notes.md +++ b/dogfood/20260323-week5-platform-closure/notes.md @@ -19,10 +19,10 @@ Lane D completed the Week 5 platform/documentation closeout on 2026-03-23. This ## Documentation changes - `README.md` now includes a `## Platform Support` section that spells out Linux tier-1, macOS tier-1, and Windows tier-2. -- `design/20260319_agent-terminal-v1.md` updates the design entrypoint to the 2026-03-23 shipped status and calls out Week 5 foundational scaffolding plus macOS CI validation. -- `design/20260319_agent-terminal-v1/12-week-5-status.md` records the actual Week 5 outcome and marks Workstream D as completed. -- `design/20260319_agent-terminal-v1/11-week-5-plan.md` now includes a status update pointing readers to the Week 5 outcome. -- `WEEK2-GAPS.md` is reclassified as the post-Week-5 remaining-gap tracker with explicit shipped / scaffolded / future annotations. +- `design/ARCHITECTURE.md` updates the design entrypoint to the 2026-03-23 shipped status and calls out Week 5 foundational scaffolding plus macOS CI validation. +- `design/archive/12-week-5-status.md` records the actual Week 5 outcome and marks Workstream D as completed. +- `design/archive/11-week-5-plan.md` now includes a status update pointing readers to the Week 5 outcome. +- `ROADMAP.md` is reclassified as the post-Week-5 remaining-gap tracker with explicit shipped / scaffolded / future annotations. ## Validation results @@ -40,20 +40,20 @@ All requested validation gates passed for the platform/documentation closeout: npm run verify (runs format:check, lint, typecheck, test, build) npx prettier --check .github/workflows/ci.yml npx prettier --check README.md -npx prettier --check WEEK2-GAPS.md -npx prettier --check design/20260319_agent-terminal-v1.md -npx prettier --check design/20260319_agent-terminal-v1/12-week-5-status.md -npx prettier --check design/20260319_agent-terminal-v1/11-week-5-plan.md +npx prettier --check ROADMAP.md +npx prettier --check design/ARCHITECTURE.md +npx prettier --check design/archive/12-week-5-status.md +npx prettier --check design/archive/11-week-5-plan.md ``` ## Files changed 1. `.github/workflows/ci.yml` — added the `quality-gates-macos` tier-1 validation job alongside the existing Ubuntu job. 2. `README.md` — added the top-level `## Platform Support` section describing Linux tier-1, macOS tier-1, and Windows tier-2. -3. `design/20260319_agent-terminal-v1.md` — updated the design entrypoint shipped-status section to 2026-03-23 and linked Week 5 status/current gaps. -4. `design/20260319_agent-terminal-v1/12-week-5-status.md` — added the dedicated Week 5 status record documenting what shipped vs what remains future scope. -5. `design/20260319_agent-terminal-v1/11-week-5-plan.md` — updated the status section near the top to reflect the Week 5 outcome and cross-link the status doc. -6. `WEEK2-GAPS.md` — reclassified the tracker into the post-Week-5 gap list with shipped, scaffolded, and future-scope labels. +3. `design/ARCHITECTURE.md` — updated the design entrypoint shipped-status section to 2026-03-23 and linked Week 5 status/current gaps. +4. `design/archive/12-week-5-status.md` — added the dedicated Week 5 status record documenting what shipped vs what remains future scope. +5. `design/archive/11-week-5-plan.md` — updated the status section near the top to reflect the Week 5 outcome and cross-link the status doc. +6. `ROADMAP.md` — reclassified the tracker into the post-Week-5 gap list with shipped, scaffolded, and future-scope labels. ## What this proves @@ -74,7 +74,7 @@ npx prettier --check design/20260319_agent-terminal-v1/11-week-5-plan.md - `../../.github/workflows/ci.yml` - `../../README.md` -- `../../design/20260319_agent-terminal-v1.md` -- `../../design/20260319_agent-terminal-v1/12-week-5-status.md` -- `../../design/20260319_agent-terminal-v1/11-week-5-plan.md` -- `../../WEEK2-GAPS.md` +- `../../design/ARCHITECTURE.md` +- `../../design/archive/12-week-5-status.md` +- `../../design/archive/11-week-5-plan.md` +- `../../ROADMAP.md` diff --git a/dogfood/20260330-docs-navigation/01-doctor.json b/dogfood/20260330-docs-navigation/01-doctor.json new file mode 100644 index 0000000..1f4fc60 --- /dev/null +++ b/dogfood/20260330-docs-navigation/01-doctor.json @@ -0,0 +1,130 @@ +{ + "ok": true, + "command": "doctor", + "timestamp": "2026-03-30T13:22:40.224Z", + "result": { + "ok": true, + "checks": { + "environment": [ + { + "name": "node-runtime", + "status": "pass", + "message": "Node 24.14.0 ok", + "durationMs": 0 + }, + { + "name": "cwd-access", + "status": "pass", + "message": "cwd read/write: /home/coder/.mux/src/agent-terminal/docs-8zn6", + "durationMs": 1 + }, + { + "name": "temp-dir", + "status": "pass", + "message": "temp dir ok: /tmp", + "durationMs": 1 + }, + { + "name": "home_isolation", + "status": "pass", + "message": "Agent-terminal home is isolated from system home: /tmp/tmp.lxl2CttaJZ", + "durationMs": 0 + }, + { + "name": "home-writable", + "status": "pass", + "message": "home writable: /tmp/tmp.lxl2CttaJZ", + "durationMs": 1 + }, + { + "name": "pty-spawn", + "status": "pass", + "message": "spawned /home/coder/.local/share/mise/installs/node/24.14.0/bin/node", + "durationMs": 37 + }, + { + "name": "socket-viable", + "status": "pass", + "message": "socket ok: /tmp/tmp.lxl2CttaJZ/sessions/doctor-3156979-mnd7wz18-2/host.sock", + "durationMs": 3 + }, + { + "name": "artifact-atomicity", + "status": "pass", + "message": "atomic rename ok: /tmp/tmp.lxl2CttaJZ/sessions/doctor-3156979-mnd7wz1a-3/artifacts", + "durationMs": 3 + }, + { + "name": "event-log-writable", + "status": "pass", + "message": "append ok: /tmp/tmp.lxl2CttaJZ/sessions/doctor-3156979-mnd7wz1d-5/events.jsonl", + "durationMs": 1 + } + ], + "renderer": [ + { + "name": "playwright_available", + "status": "pass", + "message": "available", + "durationMs": 0 + }, + { + "name": "browser_cache_accessible", + "status": "pass", + "message": "browser cache accessible: /home/coder/.cache/ms-playwright", + "durationMs": 1 + }, + { + "name": "browser_launch", + "status": "pass", + "message": "chromium launches", + "durationMs": 104 + }, + { + "name": "ghostty_web_available", + "status": "pass", + "message": "WASM available", + "durationMs": 120 + }, + { + "name": "screenshot_viable", + "status": "pass", + "message": "viable", + "durationMs": 156 + } + ] + }, + "capabilities": [ + { + "name": "snapshot", + "status": "available", + "reason": "built-in capability", + "detail": "available without external renderer dependencies" + }, + { + "name": "wait", + "status": "available", + "reason": "built-in capability", + "detail": "available without external renderer dependencies" + }, + { + "name": "screenshot", + "status": "available", + "reason": "renderer smoke checks passed", + "detail": "playwright_available: available; browser_launch: chromium launches; ghostty_web_available: WASM available; screenshot_viable: viable" + }, + { + "name": "record-export-asciicast", + "status": "available", + "reason": "built-in capability", + "detail": "available without external renderer dependencies" + }, + { + "name": "record-export-webm", + "status": "available", + "reason": "browser-backed export dependencies available", + "detail": "playwright_available: available; browser_launch: chromium launches; ghostty_web_available: WASM available" + } + ] + } +} diff --git a/dogfood/20260330-docs-navigation/02-create.json b/dogfood/20260330-docs-navigation/02-create.json new file mode 100644 index 0000000..bbb8a17 --- /dev/null +++ b/dogfood/20260330-docs-navigation/02-create.json @@ -0,0 +1,12 @@ +{ + "ok": true, + "command": "create", + "timestamp": "2026-03-30T13:22:42.106Z", + "result": { + "sessionId": "01KMZEJAG1DHH4G66SQH4FEH5T", + "createdAt": "2026-03-30T13:22:41.283Z", + "cols": 80, + "rows": 24, + "shell": "/bin/bash" + } +} diff --git a/dogfood/20260330-docs-navigation/03-run-root.json b/dogfood/20260330-docs-navigation/03-run-root.json new file mode 100644 index 0000000..4ee09cc --- /dev/null +++ b/dogfood/20260330-docs-navigation/03-run-root.json @@ -0,0 +1,13 @@ +{ + "ok": true, + "command": "run", + "timestamp": "2026-03-30T13:22:44.163Z", + "result": { + "accepted": true, + "completed": true, + "timedOut": false, + "seq": 2, + "durationMs": 909, + "marker": "__AT_MARKER_562a3865ce1443efaad29cfc6b20c439__" + } +} diff --git a/dogfood/20260330-docs-navigation/04-wait-root.json b/dogfood/20260330-docs-navigation/04-wait-root.json new file mode 100644 index 0000000..90dfd63 --- /dev/null +++ b/dogfood/20260330-docs-navigation/04-wait-root.json @@ -0,0 +1,12 @@ +{ + "ok": true, + "command": "wait", + "timestamp": "2026-03-30T13:22:46.237Z", + "result": { + "matched": true, + "timedOut": false, + "cursorRow": 23, + "cursorCol": 15, + "capturedAtSeq": 17 + } +} diff --git a/dogfood/20260330-docs-navigation/05-root-docs.png b/dogfood/20260330-docs-navigation/05-root-docs.png new file mode 100644 index 0000000..2ee8b30 Binary files /dev/null and b/dogfood/20260330-docs-navigation/05-root-docs.png differ diff --git a/dogfood/20260330-docs-navigation/05-screenshot-root.json b/dogfood/20260330-docs-navigation/05-screenshot-root.json new file mode 100644 index 0000000..2b6c909 --- /dev/null +++ b/dogfood/20260330-docs-navigation/05-screenshot-root.json @@ -0,0 +1,20 @@ +{ + "ok": true, + "command": "screenshot", + "timestamp": "2026-03-30T13:22:47.451Z", + "result": { + "sessionId": "01KMZEJAG1DHH4G66SQH4FEH5T", + "capturedAtSeq": 17, + "profileName": "reference-dark", + "cols": 80, + "rows": 24, + "artifactPath": "/tmp/tmp.lxl2CttaJZ/sessions/01KMZEJAG1DHH4G66SQH4FEH5T/artifacts/screenshot-17-reference-dark.png", + "pngSizeBytes": 45376, + "cursorVisible": false, + "rendererBackend": "ghostty-web", + "pixelWidth": 640, + "pixelHeight": 384, + "sha256": "f90e1009e2ecee2ae0a0991c90d9c7fa06d3ed96b07ac18b7583b306a5071dfb", + "renderProfileHash": "8ffed6af301ec7c0e6b69599c3be0d1d12096f9fcdfc59d0bbb4cc474d64c53d" + } +} diff --git a/dogfood/20260330-docs-navigation/06-run-design.json b/dogfood/20260330-docs-navigation/06-run-design.json new file mode 100644 index 0000000..c58c31d --- /dev/null +++ b/dogfood/20260330-docs-navigation/06-run-design.json @@ -0,0 +1,13 @@ +{ + "ok": true, + "command": "run", + "timestamp": "2026-03-30T13:22:48.835Z", + "result": { + "accepted": true, + "completed": true, + "timedOut": false, + "seq": 18, + "durationMs": 363, + "marker": "__AT_MARKER_cfc80340ad7c4d6b8baea69655eb5bbb__" + } +} diff --git a/dogfood/20260330-docs-navigation/07-wait-design.json b/dogfood/20260330-docs-navigation/07-wait-design.json new file mode 100644 index 0000000..aa085ac --- /dev/null +++ b/dogfood/20260330-docs-navigation/07-wait-design.json @@ -0,0 +1,12 @@ +{ + "ok": true, + "command": "wait", + "timestamp": "2026-03-30T13:22:50.951Z", + "result": { + "matched": true, + "timedOut": false, + "cursorRow": 23, + "cursorCol": 15, + "capturedAtSeq": 28 + } +} diff --git a/dogfood/20260330-docs-navigation/08-design-docs.png b/dogfood/20260330-docs-navigation/08-design-docs.png new file mode 100644 index 0000000..a46aebb Binary files /dev/null and b/dogfood/20260330-docs-navigation/08-design-docs.png differ diff --git a/dogfood/20260330-docs-navigation/08-screenshot-design.json b/dogfood/20260330-docs-navigation/08-screenshot-design.json new file mode 100644 index 0000000..7c908f3 --- /dev/null +++ b/dogfood/20260330-docs-navigation/08-screenshot-design.json @@ -0,0 +1,20 @@ +{ + "ok": true, + "command": "screenshot", + "timestamp": "2026-03-30T13:22:52.163Z", + "result": { + "sessionId": "01KMZEJAG1DHH4G66SQH4FEH5T", + "capturedAtSeq": 28, + "profileName": "reference-dark", + "cols": 80, + "rows": 24, + "artifactPath": "/tmp/tmp.lxl2CttaJZ/sessions/01KMZEJAG1DHH4G66SQH4FEH5T/artifacts/screenshot-28-reference-dark.png", + "pngSizeBytes": 52235, + "cursorVisible": false, + "rendererBackend": "ghostty-web", + "pixelWidth": 640, + "pixelHeight": 384, + "sha256": "11ef11c81850500e6b62250eeb173dd8cd26566cd09233d598f102f728a10e8a", + "renderProfileHash": "8ffed6af301ec7c0e6b69599c3be0d1d12096f9fcdfc59d0bbb4cc474d64c53d" + } +} diff --git a/dogfood/20260330-docs-navigation/09-run-dogfood.json b/dogfood/20260330-docs-navigation/09-run-dogfood.json new file mode 100644 index 0000000..c60c456 --- /dev/null +++ b/dogfood/20260330-docs-navigation/09-run-dogfood.json @@ -0,0 +1,13 @@ +{ + "ok": true, + "command": "run", + "timestamp": "2026-03-30T13:22:53.692Z", + "result": { + "accepted": true, + "completed": true, + "timedOut": false, + "seq": 29, + "durationMs": 392, + "marker": "__AT_MARKER_228534db2b2d4e6b88ea40d4e87f71fa__" + } +} diff --git a/dogfood/20260330-docs-navigation/10-wait-dogfood.json b/dogfood/20260330-docs-navigation/10-wait-dogfood.json new file mode 100644 index 0000000..d0ad264 --- /dev/null +++ b/dogfood/20260330-docs-navigation/10-wait-dogfood.json @@ -0,0 +1,12 @@ +{ + "ok": true, + "command": "wait", + "timestamp": "2026-03-30T13:22:55.816Z", + "result": { + "matched": true, + "timedOut": false, + "cursorRow": 23, + "cursorCol": 15, + "capturedAtSeq": 41 + } +} diff --git a/dogfood/20260330-docs-navigation/11-dogfood-docs.png b/dogfood/20260330-docs-navigation/11-dogfood-docs.png new file mode 100644 index 0000000..04a072e Binary files /dev/null and b/dogfood/20260330-docs-navigation/11-dogfood-docs.png differ diff --git a/dogfood/20260330-docs-navigation/11-screenshot-dogfood.json b/dogfood/20260330-docs-navigation/11-screenshot-dogfood.json new file mode 100644 index 0000000..853d60b --- /dev/null +++ b/dogfood/20260330-docs-navigation/11-screenshot-dogfood.json @@ -0,0 +1,20 @@ +{ + "ok": true, + "command": "screenshot", + "timestamp": "2026-03-30T13:22:57.011Z", + "result": { + "sessionId": "01KMZEJAG1DHH4G66SQH4FEH5T", + "capturedAtSeq": 41, + "profileName": "reference-dark", + "cols": 80, + "rows": 24, + "artifactPath": "/tmp/tmp.lxl2CttaJZ/sessions/01KMZEJAG1DHH4G66SQH4FEH5T/artifacts/screenshot-41-reference-dark.png", + "pngSizeBytes": 48629, + "cursorVisible": false, + "rendererBackend": "ghostty-web", + "pixelWidth": 640, + "pixelHeight": 384, + "sha256": "055fa40b1ef868ace6d2ddd1c7a97f5662c20293df3558215e188b7c5bc058fd", + "renderProfileHash": "8ffed6af301ec7c0e6b69599c3be0d1d12096f9fcdfc59d0bbb4cc474d64c53d" + } +} diff --git a/dogfood/20260330-docs-navigation/12-run-contributor.json b/dogfood/20260330-docs-navigation/12-run-contributor.json new file mode 100644 index 0000000..8f0d9ee --- /dev/null +++ b/dogfood/20260330-docs-navigation/12-run-contributor.json @@ -0,0 +1,13 @@ +{ + "ok": true, + "command": "run", + "timestamp": "2026-03-30T13:22:58.630Z", + "result": { + "accepted": true, + "completed": true, + "timedOut": false, + "seq": 42, + "durationMs": 496, + "marker": "__AT_MARKER_70894693e08b423690a5ea0e930d387b__" + } +} diff --git a/dogfood/20260330-docs-navigation/13-wait-contributor.json b/dogfood/20260330-docs-navigation/13-wait-contributor.json new file mode 100644 index 0000000..0f56534 --- /dev/null +++ b/dogfood/20260330-docs-navigation/13-wait-contributor.json @@ -0,0 +1,12 @@ +{ + "ok": true, + "command": "wait", + "timestamp": "2026-03-30T13:23:00.711Z", + "result": { + "matched": true, + "timedOut": false, + "cursorRow": 23, + "cursorCol": 15, + "capturedAtSeq": 56 + } +} diff --git a/dogfood/20260330-docs-navigation/14-contributor-docs.png b/dogfood/20260330-docs-navigation/14-contributor-docs.png new file mode 100644 index 0000000..71e0390 Binary files /dev/null and b/dogfood/20260330-docs-navigation/14-contributor-docs.png differ diff --git a/dogfood/20260330-docs-navigation/14-screenshot-contributor.json b/dogfood/20260330-docs-navigation/14-screenshot-contributor.json new file mode 100644 index 0000000..48ca166 --- /dev/null +++ b/dogfood/20260330-docs-navigation/14-screenshot-contributor.json @@ -0,0 +1,20 @@ +{ + "ok": true, + "command": "screenshot", + "timestamp": "2026-03-30T13:23:01.883Z", + "result": { + "sessionId": "01KMZEJAG1DHH4G66SQH4FEH5T", + "capturedAtSeq": 56, + "profileName": "reference-dark", + "cols": 80, + "rows": 24, + "artifactPath": "/tmp/tmp.lxl2CttaJZ/sessions/01KMZEJAG1DHH4G66SQH4FEH5T/artifacts/screenshot-56-reference-dark.png", + "pngSizeBytes": 37461, + "cursorVisible": false, + "rendererBackend": "ghostty-web", + "pixelWidth": 640, + "pixelHeight": 384, + "sha256": "c2cce610a90cd8ac3dc5ee3a17b6e57dc70fc9bd3c022cbfa8b05d8f5295d51b", + "renderProfileHash": "8ffed6af301ec7c0e6b69599c3be0d1d12096f9fcdfc59d0bbb4cc474d64c53d" + } +} diff --git a/dogfood/20260330-docs-navigation/15-docs-navigation.webm b/dogfood/20260330-docs-navigation/15-docs-navigation.webm new file mode 100644 index 0000000..df2d4de Binary files /dev/null and b/dogfood/20260330-docs-navigation/15-docs-navigation.webm differ diff --git a/dogfood/20260330-docs-navigation/15-record-webm.json b/dogfood/20260330-docs-navigation/15-record-webm.json new file mode 100644 index 0000000..7f458c2 --- /dev/null +++ b/dogfood/20260330-docs-navigation/15-record-webm.json @@ -0,0 +1,23 @@ +{ + "ok": true, + "command": "record export", + "timestamp": "2026-03-30T13:23:07.277Z", + "result": { + "sessionId": "01KMZEJAG1DHH4G66SQH4FEH5T", + "format": "webm", + "artifactPath": "/tmp/tmp.lxl2CttaJZ/sessions/01KMZEJAG1DHH4G66SQH4FEH5T/artifacts/recording-56-webm.webm", + "bytes": 532014, + "sha256": "f23cdc95e1b66a348a937cbd72b276019074208ae240840351c023e14b0c13fc", + "capturedAtSeq": 56, + "durationMs": 16234, + "metadata": { + "width": 80, + "height": 24, + "profileName": "reference-dark", + "renderProfileHash": "8ffed6af301ec7c0e6b69599c3be0d1d12096f9fcdfc59d0bbb4cc474d64c53d", + "timingMode": "accelerated", + "outputEventCount": 53, + "resizeEventCount": 0 + } + } +} diff --git a/dogfood/20260330-docs-navigation/16-docs-navigation.cast b/dogfood/20260330-docs-navigation/16-docs-navigation.cast new file mode 100644 index 0000000..b61584a --- /dev/null +++ b/dogfood/20260330-docs-navigation/16-docs-navigation.cast @@ -0,0 +1,54 @@ +{"version":2,"width":80,"height":24,"timestamp":1774876962,"title":"01KMZEJAG1DHH4G66SQH4FEH5T","sessionId":"01KMZEJAG1DHH4G66SQH4FEH5T","env":{"TERM":"xterm-256color"},"toolVersion":"0.1.0"} +[0,"o","bash: /home/linuxbrew/.linuxbrew/bin/brew: No such file or directory\r\n"] +[0.171,"o","\u001b[?2004h\u001b[1;33mcoder\u001b[0m in \u001b[1;2;32m🌐 aaaaaaa\u001b[0m in \u001b[1;36mdocs-8zn6\u001b[0m on \u001b[1;35m docs-8zn6:main\u001b[0m \u001b[1;31m[»!?]\u001b[0m is \u001b[1;38;5;208m📦 v0.1.0\u001b[0m via \u001b[1;32m v24.14.0 \u001b[0mon \u001b[1;34m☁️ \u001b[0m \r\n\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m "] +[0.965,"o","\u001b[7mprintf '\\033c'\u001b[27m\r\n\r\u001b[7mprintf 'README.md\\n=========\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,54p' README.md\u001b[27m\r\n\r\u001b[7mprintf '\\nRELEASE.md\\n==========\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,38p' RELEASE.md\u001b[27m\r\n\r\u001b[7mprintf '\\nROADMAP.md\\n==========\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,39p' ROADMAP.md\u001b[27m\r\n\r\n\r\u001b[7mprintf '%s%s\\n' '__AT_MARKER_562a3865ce1' '443efaad29cfc6b20c439__'\u001b[27m\r\n\r\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\r\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m printf '\\033c'\r\n\rprintf 'README.md\\n=========\\n'\r\n\rsed -n '1,54p' README.md\r\n\rprintf '\\nRELEASE.md\\n==========\\n'\r\n\rsed -n '1,38p' RELEASE.md\r\n\rprintf '\\nROADMAP.md\\n==========\\n'\r\n\rsed -n '1,39p' ROADMAP.md\r\n\r\n\rprintf '%s%s\\n' '__AT_MARKER_562a3865ce1' '443efaad29cfc6b20c439__'\r\n\r\u001b[A\r\n\u001b[?2004l\r"] +[0.993,"o","\u001bc"] +[1.02,"o","README.md\r\n=========\r\n"] +[1.054,"o","# agent-terminal\r\n\r\n`agent-terminal` is a Node/TypeScript CLI for launching, controlling, inspecting, and exporting reviewable terminal sessions.\r\nIt is built for agent workflows that need both semantic state and visual artifacts from live or exited TUIs.\r\n\r\n## Installation\r\n\r\n### Global installation\r\n\r\n```bash\r\nnpm install -g agent-terminal\r\nagent-terminal version --json\r\n```\r\n\r\n### Project installation\r\n\r\n```bash\r\n"] +[1.054,"o","npm install agent-terminal\r\n./node_modules/.bin/agent-terminal version --json\r\n```\r\n\r\n## Quick start\r\n\r\n```bash\r\nAGENT_HOME=\"$(mktemp -d)\"\r\nagent-terminal --home \"$AGENT_HOME\" doctor --json\r\nSESSION_ID=$(agent-terminal --home \"$AGENT_HOME\" create --json --name demo -- /bin/bash | jq -r '.result.sessionId')\r\nagent-terminal --home \"$AGENT_HOME\" run \"$SESSION_ID\" 'echo hello from agent-terminal' --json\r\nagent-terminal --home \"$AGENT_HOME\" snapshot \"$SESSION_ID\" --format text --json\r\nagent-terminal --home \"$AGENT_HOME\" destroy \"$SESSION_ID\" --json\r\n```\r\n\r\n## Documentation map\r\n\r\n- [`RELEASE.md`](./RELEASE.md) — the current `0.1.0` release contract.\r\n- [`ROADMAP.md`](./ROADMAP.md) — intentionally deferred work and post-release direction.\r\n- [`design/README.md`](./design/README.md) — architecture references plus archived week-by-week planning.\r\n- [`dogfood/CATALOG.md`](./dogfood/CATALOG.md) — curated proof bundles and recommended review paths.\r\n- [`docs/README.md`](./docs/README.md) — contributor and maintainer navigation.\r\n\r\n## Feature highlights\r\n\r\n- Full session lifecycle management: create, inspect, list, wait, destroy, and garbage-collect.\r\n- Semantic snapshots for structured or text inspection, including optional scrollback capture.\r\n- Renderer-backed screenshots and replay exports for reviewable visual evidence.\r\n- Recording export to asciicast (`.cast`) or WebM for artifact bundles.\r\n- Failure recovery via reconciliation, stale-session cleanup, and retained manifests/artifacts.\r\n\r\n## 0.1.0 release focus\r\n\r\n`agent-terminal` `0.1.0` is the first release aimed at reliable, isolated, reviewable TUI automation.\r\nFor the explicit shipping contract, see [`RELEASE.md`](./RELEASE.md). For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md).\r\nReviewer-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/`.\r\n\r\n"] +[1.079,"o","\r\nRELEASE.md\r\n==========\r\n"] +[1.108,"o","# agent-terminal 0.1.0 release contract\r\n\r\n`agent-terminal` `0.1.0` is the first release that explicitly targets isolated, reviewable terminal automation for real TUI workflows.\r\nThe contract below is the bar for what maintainers should feel comfortable supporting at release time.\r\nIf a workflow depends on behavior outside this document, treat it as future-scope or best-effort rather than a guaranteed `0.1.0` capability.\r\nFor intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md). For reviewer-facing proof bundles, start with [`dogfood/CATALOG.md`](./dogfood/CATALOG.md).\r\n\r\n## What 0.1.0 delivers\r\n\r\n- Reliable isolated session lifecycle management: `create`, `inspect`, `destroy`, and `gc` all work against isolated agent-terminal homes.\r\n- Renderer-backed screenshots, semantic snapshots, and WebM export for reviewer-visible proof artifacts.\r\n- The `run` command for robust in-session command execution without having to simulate long shell setup scripts as manual keystrokes.\r\n- `doctor --json` with isolation-aware diagnostics for home resolution, renderer prerequisites, and screenshot viability.\r\n"] +[1.108,"o","- An append-only event log that remains the canonical replay/export source of truth.\r\n- Schema-locked JSON envelopes across the public CLI surface.\r\n\r\n## What 0.1.0 explicitly does not deliver\r\n\r\n- Native renderer backends such as Ghostty native or kitty.\r\n- Mouse input support.\r\n- Remote or networked sessions.\r\n- An MCP wrapper.\r\n- Full semantic TUI automation.\r\n- Cross-terminal pixel parity.\r\n- Output capture or exit-code detection from `run`.\r\n\r\n## Known limitations\r\n\r\n- The renderer is the `ghostty-web` reference backend, not a native-terminal parity guarantee.\r\n- `run` completion detection relies on shell-visible echo of an injected boundary marker.\r\n- Screenshots and WebM export require Playwright/Chromium to be installed and discoverable.\r\n- The reviewed LazyVim workflow currently assumes Neovim `>= 0.11.2` plus its usual prerequisites; older Neovim builds are out of contract for that scenario.\r\n\r\n## Validation\r\n\r\n- Current release bar: 595 tests across 56 test files.\r\n- 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/`.\r\n- Run `npm run verify` for the full validation bar.\r\n"] +[1.135,"o","\r\nROADMAP.md\r\n==========\r\n"] +[1.167,"o","# agent-terminal roadmap\r\n\r\n`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.\r\n"] +[1.167,"o","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).\r\n\r\n## Near-term refinements\r\n\r\n- Broader reviewer-oriented introspection in `inspect --json`, especially around live renderer/session state when that adds clear operational value.\r\n- Stronger proof-bundle conventions and automation so canonical `dogfood/` bundles stay easy to review and harder to let drift.\r\n- Continued hardening around renderer/bootstrap ergonomics in isolated environments.\r\n\r\n## Renderer and platform expansion\r\n\r\n- Native renderer adapters beyond the current `ghostty-web` reference backend.\r\n- Broader native-platform parity work, especially where Windows or native terminals diverge from the reference renderer.\r\n- Follow-on renderer hardening such as tighter CSP or sandbox assumptions if the backend model evolves.\r\n\r\n## Input and automation expansion\r\n\r\n- Mouse input support.\r\n- Richer semantic TUI automation beyond the current shell-oriented lifecycle, wait, snapshot, screenshot, and export flows.\r\n- Additional higher-level workflows only after they fit the event-log-as-truth model and do not undermine the stable CLI surface.\r\n\r\n## System integration\r\n\r\n- Remote or networked session control.\r\n- An MCP wrapper or other external control layers built on top of the CLI contract.\r\n\r\n## Data-model redesigns\r\n\r\n- Broader failure-taxonomy work beyond the current shipped termination/reporting categories.\r\n"] +[1.167,"o","- Event-log redesign only if the current append-only model proves too limiting for replay or recovery needs.\r\n- Snapshot-schema expansion where the existing structured surface is not sufficient for review or automation use cases.\r\n\r\n## Prioritization notes\r\n\r\n1. Preserve the current release contract before widening scope.\r\n2. Prefer incremental additions that reuse the existing CLI, storage, replay, and artifact model.\r\n3. Archive historical planning/status detail instead of mixing it back into the roadmap.\r\n"] +[1.2,"o","__AT_MARKER_562a3865ce1443efaad29cfc6b20c439__\r\n"] +[1.319,"o","\u001b[?2004h\u001b[1;33mcoder\u001b[0m in \u001b[1;2;32m🌐 aaaaaaa\u001b[0m in \u001b[1;36mdocs-8zn6\u001b[0m on \u001b[1;35m docs-8zn6:main\u001b[0m \u001b[1;31m[»!?]\u001b[0m is \u001b[1;38;5;208m📦 v0.1.0\u001b[0m via \u001b[1;32m v24.14.0 \u001b[0mon \u001b[1;34m☁️ \u001b[0m \r\n"] +[1.319,"o","\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m \u001b[K"] +[6.186,"o","\u001b[7mprintf '\\033c'\u001b[27m\r\n\r\u001b[7mprintf 'design/README.md\\n================\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,35p' design/README.md\u001b[27m\r\n\r\u001b[7mprintf '\\ndesign/ARCHITECTURE.md\\n======================\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,45p' design/ARCHITECTURE.md\u001b[27m\r\n\r\n\r\u001b[7mprintf '%s%s\\n' '__AT_MARKER_cfc80340ad7' 'c4d6b8baea69655eb5bbb__'\u001b[27m\r\n"] +[6.187,"o","\r\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\r\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m printf '\\033c'\r\n\rprintf 'design/README.md\\n================\\n'\r\n\rsed -n '1,35p' design/README.md\r\n\rprintf '\\ndesign/ARCHITECTURE.md\\n======================\\n'\r\n\rsed -n '1,45p' design/ARCHITECTURE.md\r\n\r\n\rprintf '%s%s\\n' '__AT_MARKER_cfc80340ad7' 'c4d6b8baea69655eb5bbb__'\r\n\r\u001b[A\r\n\u001b[?2004l\r"] +[6.218,"o","\u001bc"] +[6.245,"o","design/README.md\r\n================\r\n"] +[6.272,"o","# Design documentation\r\n\r\nUse this directory as the navigation hub for architecture and design material.\r\nThe active reference set stays separate from the week-by-week project history so newcomers can find the stable docs first.\r\n\r\n## Start here\r\n\r\n1. [`ARCHITECTURE.md`](./ARCHITECTURE.md) — stable product and architecture overview.\r\n2. [`20260319_agent-terminal-v1/02-cli-contract.md`](./20260319_agent-terminal-v1/02-cli-contract.md) — CLI contract details.\r\n3. [`20260319_agent-terminal-v1/03-rendering-and-artifacts.md`](./20260319_agent-terminal-v1/03-rendering-and-artifacts.md) — replay, screenshot, and export model.\r\n4. [`20260319_agent-terminal-v1/05-dogfooding-and-validation.md`](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md) — proof-bundle expectations.\r\n\r\n## Active reference set\r\n\r\nThe original v1 design review produced a focused reference set that is still useful as evergreen technical documentation:\r\n\r\n- [`20260319_agent-terminal-v1/01-architecture.md`](./20260319_agent-terminal-v1/01-architecture.md)\r\n- [`20260319_agent-terminal-v1/02-cli-contract.md`](./20260319_agent-terminal-v1/02-cli-contract.md)\r\n- [`20260319_agent-terminal-v1/03-rendering-and-artifacts.md`](./20260319_agent-terminal-v1/03-rendering-and-artifacts.md)\r\n- [`20260319_agent-terminal-v1/04-implementation-plan.md`](./20260319_agent-terminal-v1/04-implementation-plan.md)\r\n- [`20260319_agent-terminal-v1/05-dogfooding-and-validation.md`](./20260319_agent-terminal-v1/05-dogfooding-and-validation.md)\r\n\r\n## Historical archive\r\n\r\nWeek-by-week plans and status reports now live under [`archive/`](./archive/). They remain part of the repository because they explain how the current surface evolved, but they are historical context rather than the primary discovery path.\r\n\r\n- [`archive/README.md`](./archive/README.md)\r\n- [`archive/06-roadmap-and-week-1-plan.md`](./archive/06-roadmap-and-week-1-plan.md)\r\n- [`archive/17-week-9-plan.md`](./archive/17-week-9-plan.md)\r\n\r\n## Related docs\r\n\r\n- [`../RELEASE.md`](../RELEASE.md) — current shipping contract.\r\n- [`../ROADMAP.md`](../ROADMAP.md) — deferred work and post-release direction.\r\n- [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) — curated proof bundles.\r\n"] +[6.306,"o","\r\ndesign/ARCHITECTURE.md\r\n======================\r\n"] +[6.335,"o","---\r\nauthor: \"@mux\"\r\ndate: 2026-03-19\r\n---\r\n\r\n# agent-terminal architecture overview\r\n\r\n`agent-terminal` is a CLI-first terminal automation system for AI agents and humans.\r\n\r\nIt is designed to let an agent:\r\n\r\n- create and manage long-lived terminal sessions,\r\n- send text, paste payloads, key chords, resize events, and signals,\r\n- wait for TUI state changes,\r\n- inspect semantic terminal state,\r\n"] +[6.336,"o","- capture deterministic screenshots,\r\n- export replay artifacts that reviewers can inspect,\r\n- and later swap the reference renderer for native terminal backends.\r\n\r\nThis design intentionally describes a **general product**, not a Mux-specific implementation. A future Mux integration should consume `agent-terminal` as an external CLI/runtime rather than baking Mux-specific assumptions into the design.\r\n\r\n## Current shipped status (2026-03-26)\r\n\r\nUpdate (2026-03-26): Week 9 is now complete as the pre-`0.1.0` release-readiness milestone. The shipped surface now includes the new `run` command for robust in-session command execution, renderer/browser-path handling that respects isolated-home workflows, and isolation-aware `doctor --json` diagnostics on top of the earlier lifecycle, snapshot, screenshot, and export work. With the explicit release contract captured in [`../RELEASE.md`](../RELEASE.md), the repository is ready for `0.1.0` once maintainers are satisfied with the documented proof bundles and release checklist; larger asks such as native renderers, mouse input, remote/network sessions, MCP wrapping, and broader semantic TUI automation remain intentionally deferred.\r\n\r\nThe repository now ships the first three milestones of this design plus Weeks 4–7 of CLI/artifact/lifecycle hardening, config/rendering/platform closeout, contract/introspection reconciliation, and Week 7 contract/doc ratification:\r\n\r\n- long-lived session hosts,\r\n- PTY control and append-only event logs,\r\n- renderer-backed `snapshot` and `wait`,\r\n- deterministic `screenshot`,\r\n- `record export --format asciicast`,\r\n- `record export --format webm`,\r\n- artifact manifests and `gc`,\r\n- shared global CLI context and differentiated exit codes,\r\n- end-to-end CLI/config wiring for `--log-level`, `--profile`, `--idle-timeout-ms`, and `--append-newline`,\r\n- replay timing modes, bundled fonts, and optional per-cell snapshots,\r\n- richer `inspect --json` artifact-health and termination reporting,\r\n- golden-envelope coverage for the most important shipped public surfaces,\r\n- macOS CI validation,\r\n- and proof bundles under `dogfood/`.\r\n\r\nWeek 7 closed the design-synchronization pass for the shipped v1 surface. Week 8 then completed runtime capability discovery, richer renderer/session introspection, the remaining lower-priority public-envelope locks, and proof-bundle normalization/validation. Week 9 then closed the pre-`0.1.0` release-readiness milestone: isolated-environment renderer reliability is now part of the shipped contract, the higher-level in-session `run` primitive is documented and shipped, TUI-focused diagnostics/docs are in place, and the remaining large asks are intentionally deferred future-scope work rather than release blockers.\r\n\r\nThe stable contract and deferred work now have dedicated homes: use [`../RELEASE.md`](../RELEASE.md) for the shipping bar, [`../ROADMAP.md`](../ROADMAP.md) for future scope, [`./README.md`](./README.md) for the design index, and [`./archive/`](./archive/) for the historical week-by-week planning/status trail.\r\n"] +[6.362,"o","__AT_MARKER_cfc80340ad7c4d6b8baea69655eb5bbb__\r\n"] +[6.479,"o","\u001b[?2004h\u001b[1;33mcoder\u001b[0m in \u001b[1;2;32m🌐 aaaaaaa\u001b[0m in \u001b[1;36mdocs-8zn6\u001b[0m on \u001b[1;35m docs-8zn6:main\u001b[0m \u001b[1;31m[»!?]\u001b[0m is \u001b[1;38;5;208m📦 v0.1.0\u001b[0m via \u001b[1;32m v24.14.0 \u001b[0mon \u001b[1;34m☁️ \u001b[0m \r\n\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m \u001b[K"] +[11.013,"o","\u001b[7mprintf '\\033c'\u001b[27m\r\n\r\u001b[7mprintf 'dogfood/README.md\\n=================\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,29p' dogfood/README.md\u001b[27m\r\n\r\u001b[7mprintf '\\ndogfood/CATALOG.md\\n==================\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,55p' dogfood/CATALOG.md\u001b[27m\r\n\r\n"] +[11.013,"o","\r\u001b[7mprintf '%s%s\\n' '__AT_MARKER_228534db2b2' 'd4e6b88ea40d4e87f71fa__'\u001b[27m\r\n\r\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\r\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m printf '\\033c'\r\n\rprintf 'dogfood/README.md\\n=================\\n'\r\n\rsed -n '1,29p' dogfood/README.md\r\n\rprintf '\\ndogfood/CATALOG.md\\n==================\\n'\r\n\rsed -n '1,55p' dogfood/CATALOG.md\r\n\r\n\rprintf '%s%s\\n' '__AT_MARKER_228534db2b2' 'd4e6b88ea40d4e87f71fa__'\r\n\r\u001b[A\r\n\u001b[?2004l\r"] +[11.043,"o","\u001bc"] +[11.071,"o","dogfood/README.md\r\n=================\r\n"] +[11.099,"o","# Dogfood proof bundles\r\n\r\nThis directory contains reviewer-facing proof bundles for `agent-terminal`.\r\nSome bundles are evergreen workflow scenarios, some are release/contract validation bundles, and many older date-stamped bundles are historical evidence from the v1 build-out.\r\n\r\n"] +[11.1,"o","## Start here\r\n\r\n1. Read [`CATALOG.md`](./CATALOG.md) for the curated bundle map.\r\n2. For the current release-signoff view, start with `dogfood/20260326-week9-release-readiness/`.\r\n3. For evergreen workflows, start with bundles such as `dogfood/run-command/`, `dogfood/20260322-dogfood-hello-prompt/`, and `dogfood/20260322-lazyvim-scenario/`.\r\n4. For recovery and hardening behavior, use the recovery section in the catalog.\r\n\r\n## How to treat the directory\r\n\r\n- **Canonical scenarios** demonstrate workflows reviewers should expect to keep using.\r\n- **Validation bundles** lock specific release or contract claims.\r\n- **Recovery bundles** document crash/replay/reconciliation behavior.\r\n- **Historical bundles** remain valuable context, but they are not all equally important for a new reviewer.\r\n\r\n## Retention policy\r\n\r\n- Prefer stable, named bundles when a scenario is evergreen and should stay discoverable.\r\n- Keep release-signoff bundles date-stamped so the evidence trail remains explicit.\r\n- Update [`CATALOG.md`](./CATALOG.md) whenever a bundle becomes a reviewer-facing reference point.\r\n- Leave one-off historical bundles in place unless they are superseded and no longer referenced.\r\n\r\n## Legacy helper scripts\r\n\r\n`generate-week3-bundles.sh` is kept as a historical helper for the earlier week-3 proof set. It is not the main starting point for new reviewers.\r\n"] +[11.131,"o","\r\ndogfood/CATALOG.md\r\n==================\r\n"] +[11.158,"o","# Dogfood catalog\r\n\r\nUse this catalog to find the most useful proof bundles without having to understand the entire historical `dogfood/` tree.\r\nPaths below are relative to the repository root.\r\n\r\n## Canonical scenarios\r\n\r\n| Scenario | What it demonstrates | Bundle |\r\n| ---------------- | -------------------------------------------------------------------------------- | ---------------------------------------- |\r\n| Hello prompt | Basic lifecycle, wait, screenshot, and recording flow | `dogfood/20260322-dogfood-hello-prompt/` |\r\n"] +[11.158,"o","| Run command | The higher-level `run` workflow for shell setup and command injection | `dogfood/run-command/` |\r\n| Color rendering | ANSI color capture and screenshot review | `dogfood/20260322-dogfood-color/` |\r\n| Alternate screen | Entering and leaving an alt-screen TUI while preserving the main screen | `dogfood/20260322-dogfood-alt-screen/` |\r\n| Resize | PTY resizing and stable-screen verification | `dogfood/20260322-dogfood-resize/` |\r\n| Scrollback | Scrollback-aware snapshots, screenshots, and recording export | `dogfood/20260322-dogfood-scrollback/` |\r\n| Unicode | Unicode rendering plus snapshot/export review | `dogfood/20260322-dogfood-unicode/` |\r\n| LazyVim | A real TUI scenario that exercises editor startup and reviewer-visible artifacts | `dogfood/20260322-lazyvim-scenario/` |\r\n| Public skill | The shipped `skills/agent-terminal/` workflow and documentation surface | `dogfood/20260327-public-skill/` |\r\n| Config parity | Configuration/profile behavior checks that remain useful as a standing scenario | `dogfood/week5-config-parity/` |\r\n\r\n## Validation and release gates\r\n\r\n| Bundle | Why it matters |\r\n| ---------------------------------------------- | -------------------------------------------------------------------------- |\r\n| `dogfood/20260326-week9-release-readiness/` | Current release-signoff bundle for the `0.1.0` bar. |\r\n| `dogfood/20260325-week8-contract-locks/` | Contract-lock and reporting review evidence. |\r\n| `dogfood/20260325-week8-bundle-validation/` | Validation of proof-bundle conventions. |\r\n| `dogfood/20260325-week8-capability-inventory/` | Runtime capability inventory/reporting evidence. |\r\n| `dogfood/20260325-week8-inspect-runtime/` | `inspect --json` runtime reporting review. |\r\n| `dogfood/20260323-week5-platform-closure/` | Platform/documentation closeout evidence from the earlier hardening phase. |\r\n\r\n## Recovery and hardening\r\n\r\n| Bundle | Focus |\r\n| ------------------------------------------- | ---------------------------------------------------------- |\r\n| `dogfood/20260322-dogfood-crash/` | Crash handling, retained artifacts, and post-crash review. |\r\n| `dogfood/20260322-week4-failure-recovery/` | Earlier failure-recovery flow review. |\r\n| `dogfood/20260323-week5-recovery-host/` | Host-death and reconciliation behavior. |\r\n| `dogfood/20260323-week5-recovery-renderer/` | Renderer failure and recovery behavior. |\r\n| `dogfood/20260323-week5-recovery-replay/` | Replay/offline recovery behavior. |\r\n| `dogfood/20260321-week3-crash-retention/` | Historical crash-retention proof for the week-3 milestone. |\r\n| `dogfood/20260321-post-hardening-smoke/` | Smoke validation after hardening work. |\r\n| `dogfood/20260323-bugfix-resize/` | Resize regression repro/fix evidence. |\r\n| `dogfood/20260323-bugfix-scrollback/` | Scrollback regression repro/fix evidence. |\r\n\r\n## Historical bundles\r\n\r\nThese bundles remain useful context, but they are mostly project-history artifacts rather than the first places a new reviewer should start:\r\n\r\n- Early lifecycle and renderer milestone bundles: `dogfood/20260319-*`, `dogfood/20260320-*`, `dogfood/20260321-*`.\r\n- Week-4 historical review bundles: `dogfood/20260322-dogfood-week4-features/`, `dogfood/20260322-global-cli-context/`, `dogfood/20260322-week4-cli-parity/`, `dogfoo"] +[11.159,"o","d/20260322-week4-scrollback-review/`, `dogfood/20260322-week4-unicode-review/`.\r\n- Week-5 historical workstreams: `dogfood/20260323-week5-*` that are not listed above as canonical or recovery references.\r\n- Week-6 and Week-7 phased rollout bundles: `dogfood/20260325-week6-*` and `dogfood/20260325-week7-*`.\r\n- Font fallback investigations: `dogfood/20260326-lazyvim-nerd-font-check/`, `dogfood/20260326-lazyvim-nerd-font-check-2/`, and `dogfood/20260326-nerd-font-fallback/`.\r\n\r\n"] +[11.185,"o","__AT_MARKER_228534db2b2d4e6b88ea40d4e87f71fa__\r\n"] +[11.303,"o","\u001b[?2004h\u001b[1;33mcoder\u001b[0m in \u001b[1;2;32m🌐 aaaaaaa\u001b[0m in \u001b[1;36mdocs-8zn6\u001b[0m on \u001b[1;35m docs-8zn6:main\u001b[0m \u001b[1;31m[»!?]\u001b[0m is \u001b[1;38;5;208m📦 v0.1.0\u001b[0m via \u001b[1;32m v24.14.0 \u001b[0mon \u001b[1;34m☁️ \u001b[0m \r\n\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m \u001b[K"] +[15.847,"o","\u001b[7mprintf '\\033c'\u001b[27m\r\n\r\u001b[7mprintf 'docs/README.md\\n==============\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,20p' docs/README.md\u001b[27m\r\n\r\u001b[7mprintf '\\ndocs/CONTRIBUTING.md\\n====================\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,55p' docs/CONTRIBUTING.md\u001b[27m\r\n\r\u001b[7mprintf '\\ndocs/RELEASE-PROCESS.md\\n=======================\\n'\u001b[27m\r\n\r\u001b[7msed -n '1,31p' docs/RELEASE-PROCESS.md\u001b[27m\r\n\r\n\r\u001b[7mprintf '%s%s\\n' '__AT_MARKER_70894693e08' 'b423690a5ea0e930d387b__'\u001b[27m\r\n\r"] +[15.847,"o","\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\u001b[A\r\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m printf '\\033c'\r\n\rprintf 'docs/README.md\\n==============\\n'\r\n\rsed -n '1,20p' docs/README.md\r\n\rprintf '\\ndocs/CONTRIBUTING.md\\n====================\\n'\r\n\rsed -n '1,55p' docs/CONTRIBUTING.md\r\n\rprintf '\\ndocs/RELEASE-PROCESS.md\\n=======================\\n'\r\n\rsed -n '1,31p' docs/RELEASE-PROCESS.md\r\n\r\n\rprintf '%s%s\\n' '__AT_MARKER_70894693e08' 'b423690a5ea0e930d387b__'\r\n\r\u001b[A\r\n\u001b[?2004l\r"] +[15.88,"o","\u001bc"] +[15.921,"o","docs/README.md\r\n==============\r\n"] +[15.963,"o","# Contributor and maintainer docs\r\n\r\nUse this directory when you need project workflow guidance rather than product-facing documentation.\r\n\r\n- [`../README.md`](../README.md) — product overview and quick start.\r\n"] +[15.963,"o","- [`../RELEASE.md`](../RELEASE.md) — current shipping contract.\r\n- [`../ROADMAP.md`](../ROADMAP.md) — deferred work and post-release direction.\r\n- [`../design/README.md`](../design/README.md) — architecture and design references.\r\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — setup, validation, and day-to-day contribution flow.\r\n- [`RELEASE-PROCESS.md`](./RELEASE-PROCESS.md) — maintainer release checklist and proof expectations.\r\n- [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) — curated proof bundles for review.\r\n"] +[15.994,"o","\r\ndocs/CONTRIBUTING.md\r\n====================\r\n"] +[16.024,"o","# Contributing\r\n\r\n## Setup\r\n\r\nPreferred setup uses `mise`:\r\n\r\n```bash\r\nmise install\r\nmise run bootstrap\r\n```\r\n\r\n"] +[16.024,"o","Fallback setup if `mise` is unavailable:\r\n\r\n```bash\r\nnpm ci\r\nnpx playwright install chromium\r\n```\r\n\r\n## Day-to-day workflow\r\n\r\n- Use `npx tsx src/cli/main.ts ...` while developing from the source tree.\r\n- Prefer `--json` when a workflow needs machine-readable output.\r\n- Use an isolated absolute `AGENT_TERMINAL_HOME` for tests and manual dogfooding.\r\n- Keep storage writes, manifests, and protocol updates inside the existing validated helpers and schemas.\r\n\r\n## Validation\r\n\r\nRun the smallest meaningful checks while iterating, then finish with the full repo bar when the change warrants it:\r\n\r\n```bash\r\nnpm run format:check\r\nnpm run lint\r\nnpm run typecheck\r\nnpm run test\r\nnpm run build\r\n```\r\n\r\nOr use the combined entry point:\r\n\r\n```bash\r\nnpm run verify\r\n```\r\n\r\nIf you touch the public skill, also run:\r\n\r\n```bash\r\nnpm run intent:validate\r\n```\r\n\r\n## Documentation and proof expectations\r\n\r\n- Keep the root docs split clear: `README.md` for overview, `RELEASE.md` for current scope, `ROADMAP.md` for future scope.\r\n- Update [`design/README.md`](../design/README.md) when the active vs archived design split changes.\r\n- Update [`dogfood/CATALOG.md`](../dogfood/CATALOG.md) when you add or promote a reviewer-facing proof bundle.\r\n- Prefer public `agent-terminal ...` invocations in shipped skill/docs examples; do not commit repo-local `npx tsx src/cli/main.ts ...` substitutions into public-facing examples.\r\n"] +[16.051,"o","\r\ndocs/RELEASE-PROCESS.md\r\n=======================\r\n"] +[16.08,"o","# Release process\r\n\r\n`RELEASE.md` defines the shipping contract. This document describes how maintainers should validate and present that contract.\r\n\r\n## Before cutting a release\r\n\r\n1. Re-read [`../RELEASE.md`](../RELEASE.md) and confirm it still matches the shipped surface.\r\n2. Re-read [`../ROADMAP.md`](../ROADMAP.md) and confirm deferred work is not mixed back into the release contract.\r\n3. Verify the primary docs route correctly from [`../README.md`](../README.md) to release, roadmap, design, and dogfood materials.\r\n4. Review [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) and make sure the release-signoff bundle is current and easy to find.\r\n\r\n## Validation bar\r\n\r\nRun the full repo validation command:\r\n\r\n"] +[16.081,"o","```bash\r\nnpm run verify\r\n```\r\n\r\nIf the public skill changed, also run:\r\n\r\n```bash\r\nnpm run intent:validate\r\n```\r\n\r\n## Proof expectations\r\n\r\n- Keep at least one current release-readiness bundle under `dogfood/`.\r\n- Keep evergreen scenario bundles easy to discover from the dogfood catalog.\r\n- When a change affects renderer, screenshot, wait, export, or review UX, include screenshots and recordings in the relevant proof bundle when feasible.\r\n"] +[16.107,"o","__AT_MARKER_70894693e08b423690a5ea0e930d387b__\r\n"] +[16.234,"o","\u001b[?2004h\u001b[1;33mcoder\u001b[0m in \u001b[1;2;32m🌐 aaaaaaa\u001b[0m in \u001b[1;36mdocs-8zn6\u001b[0m on \u001b[1;35m docs-8zn6:main\u001b[0m \u001b[1;31m[»!?]\u001b[0m is \u001b[1;38;5;208m📦 v0.1.0\u001b[0m via \u001b[1;32m v24.14.0 \u001b[0mon \u001b[1;34m☁️ \u001b[0m \r\n\u001b[1;2;31m⬢ [Docker]\u001b[0m \u001b[1;32mXY\u001b[0m \u001b[K"] diff --git a/dogfood/20260330-docs-navigation/16-record-cast.json b/dogfood/20260330-docs-navigation/16-record-cast.json new file mode 100644 index 0000000..2faad03 --- /dev/null +++ b/dogfood/20260330-docs-navigation/16-record-cast.json @@ -0,0 +1,23 @@ +{ + "ok": true, + "command": "record export", + "timestamp": "2026-03-30T13:23:08.405Z", + "result": { + "sessionId": "01KMZEJAG1DHH4G66SQH4FEH5T", + "format": "asciicast", + "artifactPath": "/tmp/tmp.lxl2CttaJZ/sessions/01KMZEJAG1DHH4G66SQH4FEH5T/artifacts/recording-56-asciicast.cast", + "bytes": 31282, + "sha256": "25836b6a41c591a5a11e2a175c4cfed8067163dcd45ea8eabdea401dafcd139b", + "capturedAtSeq": 56, + "durationMs": 16234, + "metadata": { + "width": 80, + "height": 24, + "title": "01KMZEJAG1DHH4G66SQH4FEH5T", + "timestamp": 1774876962, + "outputEventCount": 53, + "resizeEventCount": 0, + "markerCount": 0 + } + } +} diff --git a/dogfood/20260330-docs-navigation/17-destroy.json b/dogfood/20260330-docs-navigation/17-destroy.json new file mode 100644 index 0000000..989177c --- /dev/null +++ b/dogfood/20260330-docs-navigation/17-destroy.json @@ -0,0 +1,9 @@ +{ + "ok": true, + "command": "destroy", + "timestamp": "2026-03-30T13:23:09.571Z", + "result": { + "sessionId": "01KMZEJAG1DHH4G66SQH4FEH5T", + "destroyed": true + } +} diff --git a/dogfood/20260330-docs-navigation/agent-terminal-home.txt b/dogfood/20260330-docs-navigation/agent-terminal-home.txt new file mode 100644 index 0000000..9d48a2b --- /dev/null +++ b/dogfood/20260330-docs-navigation/agent-terminal-home.txt @@ -0,0 +1 @@ +/tmp/tmp.lxl2CttaJZ diff --git a/dogfood/20260330-docs-navigation/commands.sh b/dogfood/20260330-docs-navigation/commands.sh new file mode 100755 index 0000000..26eb79e --- /dev/null +++ b/dogfood/20260330-docs-navigation/commands.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +set -euo pipefail +BUNDLE="dogfood/20260330-docs-navigation" +HOME_DIR="$(mktemp -d)" +CLI=(npx tsx src/cli/main.ts --home "$HOME_DIR") +# See notes.md for the exact proof artifacts copied from the generated session. diff --git a/dogfood/20260330-docs-navigation/contributor-docs.sh b/dogfood/20260330-docs-navigation/contributor-docs.sh new file mode 100644 index 0000000..2a2ff58 --- /dev/null +++ b/dogfood/20260330-docs-navigation/contributor-docs.sh @@ -0,0 +1,7 @@ +printf '\033c' +printf 'docs/README.md\n==============\n' +sed -n '1,20p' docs/README.md +printf '\ndocs/CONTRIBUTING.md\n====================\n' +sed -n '1,55p' docs/CONTRIBUTING.md +printf '\ndocs/RELEASE-PROCESS.md\n=======================\n' +sed -n '1,31p' docs/RELEASE-PROCESS.md diff --git a/dogfood/20260330-docs-navigation/design-docs.sh b/dogfood/20260330-docs-navigation/design-docs.sh new file mode 100644 index 0000000..7de601f --- /dev/null +++ b/dogfood/20260330-docs-navigation/design-docs.sh @@ -0,0 +1,5 @@ +printf '\033c' +printf 'design/README.md\n================\n' +sed -n '1,35p' design/README.md +printf '\ndesign/ARCHITECTURE.md\n======================\n' +sed -n '1,45p' design/ARCHITECTURE.md diff --git a/dogfood/20260330-docs-navigation/dogfood-docs.sh b/dogfood/20260330-docs-navigation/dogfood-docs.sh new file mode 100644 index 0000000..3460791 --- /dev/null +++ b/dogfood/20260330-docs-navigation/dogfood-docs.sh @@ -0,0 +1,5 @@ +printf '\033c' +printf 'dogfood/README.md\n=================\n' +sed -n '1,29p' dogfood/README.md +printf '\ndogfood/CATALOG.md\n==================\n' +sed -n '1,55p' dogfood/CATALOG.md diff --git a/dogfood/20260330-docs-navigation/notes.md b/dogfood/20260330-docs-navigation/notes.md new file mode 100644 index 0000000..4da5f0f --- /dev/null +++ b/dogfood/20260330-docs-navigation/notes.md @@ -0,0 +1,25 @@ +# Docs navigation proof bundle + +This bundle captures the updated repository documentation surface after the docs cleanup. + +## Review path covered + +1. Root docs (`README.md`, `RELEASE.md`, `ROADMAP.md`) +2. Design index and stable architecture overview +3. Dogfood landing docs (`dogfood/README.md`, `dogfood/CATALOG.md`) +4. Contributor/maintainer docs (`docs/README.md`, `docs/CONTRIBUTING.md`, `docs/RELEASE-PROCESS.md`) + +## Captured artifacts + +- `05-root-docs.png` +- `08-design-docs.png` +- `11-dogfood-docs.png` +- `14-contributor-docs.png` +- `15-docs-navigation.webm` +- `16-docs-navigation.cast` + +## Validation context + +- `01-doctor.json` records renderer/screenshot viability for the proof run. +- `15-record-webm.json` and `16-record-cast.json` record the exported reviewer-facing artifacts. +- `17-destroy.json` confirms the proof session was cleaned up. diff --git a/dogfood/20260330-docs-navigation/root-docs.sh b/dogfood/20260330-docs-navigation/root-docs.sh new file mode 100644 index 0000000..5f2498f --- /dev/null +++ b/dogfood/20260330-docs-navigation/root-docs.sh @@ -0,0 +1,7 @@ +printf '\033c' +printf 'README.md\n=========\n' +sed -n '1,54p' README.md +printf '\nRELEASE.md\n==========\n' +sed -n '1,38p' RELEASE.md +printf '\nROADMAP.md\n==========\n' +sed -n '1,39p' ROADMAP.md diff --git a/dogfood/20260330-docs-navigation/session-id.txt b/dogfood/20260330-docs-navigation/session-id.txt new file mode 100644 index 0000000..cfe2754 --- /dev/null +++ b/dogfood/20260330-docs-navigation/session-id.txt @@ -0,0 +1 @@ +01KMZEJAG1DHH4G66SQH4FEH5T diff --git a/dogfood/CATALOG.md b/dogfood/CATALOG.md new file mode 100644 index 0000000..e8f45bc --- /dev/null +++ b/dogfood/CATALOG.md @@ -0,0 +1,62 @@ +# Dogfood catalog + +Use this catalog to find the most useful proof bundles without having to understand the entire historical `dogfood/` tree. +Paths below are relative to the repository root. + +## Canonical scenarios + +| Scenario | What it demonstrates | Bundle | +| ---------------- | -------------------------------------------------------------------------------- | ---------------------------------------- | +| Hello prompt | Basic lifecycle, wait, screenshot, and recording flow | `dogfood/20260322-dogfood-hello-prompt/` | +| Run command | The higher-level `run` workflow for shell setup and command injection | `dogfood/run-command/` | +| Color rendering | ANSI color capture and screenshot review | `dogfood/20260322-dogfood-color/` | +| Alternate screen | Entering and leaving an alt-screen TUI while preserving the main screen | `dogfood/20260322-dogfood-alt-screen/` | +| Resize | PTY resizing and stable-screen verification | `dogfood/20260322-dogfood-resize/` | +| Scrollback | Scrollback-aware snapshots, screenshots, and recording export | `dogfood/20260322-dogfood-scrollback/` | +| Unicode | Unicode rendering plus snapshot/export review | `dogfood/20260322-dogfood-unicode/` | +| LazyVim | A real TUI scenario that exercises editor startup and reviewer-visible artifacts | `dogfood/20260322-lazyvim-scenario/` | +| Public skill | The shipped `skills/agent-terminal/` workflow and documentation surface | `dogfood/20260327-public-skill/` | +| Config parity | Configuration/profile behavior checks that remain useful as a standing scenario | `dogfood/week5-config-parity/` | + +## Validation and release gates + +| Bundle | Why it matters | +| ---------------------------------------------- | -------------------------------------------------------------------------- | +| `dogfood/20260326-week9-release-readiness/` | Current release-signoff bundle for the `0.1.0` bar. | +| `dogfood/20260325-week8-contract-locks/` | Contract-lock and reporting review evidence. | +| `dogfood/20260325-week8-bundle-validation/` | Validation of proof-bundle conventions. | +| `dogfood/20260325-week8-capability-inventory/` | Runtime capability inventory/reporting evidence. | +| `dogfood/20260325-week8-inspect-runtime/` | `inspect --json` runtime reporting review. | +| `dogfood/20260323-week5-platform-closure/` | Platform/documentation closeout evidence from the earlier hardening phase. | + +| `dogfood/20260330-docs-navigation/` | Repository docs walkthrough with screenshots and a WebM recording of the new navigation path. | + +## Recovery and hardening + +| Bundle | Focus | +| ------------------------------------------- | ---------------------------------------------------------- | +| `dogfood/20260322-dogfood-crash/` | Crash handling, retained artifacts, and post-crash review. | +| `dogfood/20260322-week4-failure-recovery/` | Earlier failure-recovery flow review. | +| `dogfood/20260323-week5-recovery-host/` | Host-death and reconciliation behavior. | +| `dogfood/20260323-week5-recovery-renderer/` | Renderer failure and recovery behavior. | +| `dogfood/20260323-week5-recovery-replay/` | Replay/offline recovery behavior. | +| `dogfood/20260321-week3-crash-retention/` | Historical crash-retention proof for the week-3 milestone. | +| `dogfood/20260321-post-hardening-smoke/` | Smoke validation after hardening work. | +| `dogfood/20260323-bugfix-resize/` | Resize regression repro/fix evidence. | +| `dogfood/20260323-bugfix-scrollback/` | Scrollback regression repro/fix evidence. | + +## Historical bundles + +These bundles remain useful context, but they are mostly project-history artifacts rather than the first places a new reviewer should start: + +- Early lifecycle and renderer milestone bundles: `dogfood/20260319-*`, `dogfood/20260320-*`, `dogfood/20260321-*`. +- Week-4 historical review bundles: `dogfood/20260322-dogfood-week4-features/`, `dogfood/20260322-global-cli-context/`, `dogfood/20260322-week4-cli-parity/`, `dogfood/20260322-week4-scrollback-review/`, `dogfood/20260322-week4-unicode-review/`. +- Week-5 historical workstreams: `dogfood/20260323-week5-*` that are not listed above as canonical or recovery references. +- Week-6 and Week-7 phased rollout bundles: `dogfood/20260325-week6-*` and `dogfood/20260325-week7-*`. +- Font fallback investigations: `dogfood/20260326-lazyvim-nerd-font-check/`, `dogfood/20260326-lazyvim-nerd-font-check-2/`, and `dogfood/20260326-nerd-font-fallback/`. + +## Catalog maintenance rules + +- Add a bundle to this file when reviewers should be able to find it quickly without browsing the whole directory. +- Prefer stable, descriptive scenario names over weekly status labels when promoting evergreen workflows. +- Keep one-off or superseded investigations out of the canonical sections unless they remain the best proof for a still-important behavior. diff --git a/dogfood/README.md b/dogfood/README.md new file mode 100644 index 0000000..7ef11e8 --- /dev/null +++ b/dogfood/README.md @@ -0,0 +1,29 @@ +# Dogfood proof bundles + +This directory contains reviewer-facing proof bundles for `agent-terminal`. +Some bundles are evergreen workflow scenarios, some are release/contract validation bundles, and many older date-stamped bundles are historical evidence from the v1 build-out. + +## Start here + +1. Read [`CATALOG.md`](./CATALOG.md) for the curated bundle map. +2. For the current release-signoff view, start with `dogfood/20260326-week9-release-readiness/`. +3. For evergreen workflows, start with bundles such as `dogfood/run-command/`, `dogfood/20260322-dogfood-hello-prompt/`, and `dogfood/20260322-lazyvim-scenario/`. +4. For recovery and hardening behavior, use the recovery section in the catalog. + +## How to treat the directory + +- **Canonical scenarios** demonstrate workflows reviewers should expect to keep using. +- **Validation bundles** lock specific release or contract claims. +- **Recovery bundles** document crash/replay/reconciliation behavior. +- **Historical bundles** remain valuable context, but they are not all equally important for a new reviewer. + +## Retention policy + +- Prefer stable, named bundles when a scenario is evergreen and should stay discoverable. +- Keep release-signoff bundles date-stamped so the evidence trail remains explicit. +- Update [`CATALOG.md`](./CATALOG.md) whenever a bundle becomes a reviewer-facing reference point. +- Leave one-off historical bundles in place unless they are superseded and no longer referenced. + +## Legacy helper scripts + +`generate-week3-bundles.sh` is kept as a historical helper for the earlier week-3 proof set. It is not the main starting point for new reviewers.