savepoint 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(npx prettier *)",
+      "Bash(npm test *)",
+      "Bash(npm install *)",
+      "Bash(npx vitest *)",
+      "Bash(echo \"lint exit: $?\")",
+      "Bash(echo \"format exit: $?\")",
+      "Bash(npx tsc *)",
+      "Bash(node --require ./scripts/vitest-preload.cjs ./node_modules/vitest/vitest.mjs run --configLoader runner --config vitest.config.js --reporter=verbose test/tui/components/Board.test.tsx)",
+      "Bash(node --require ./scripts/vitest-preload.cjs ./node_modules/vitest/vitest.mjs run --configLoader runner --config vitest.config.js --reporter=verbose test/tui/components/Board.test.tsx test/tui/components/App.test.tsx test/tui/components/DetailPane.test.tsx)",
+      "Bash(node --require ./scripts/vitest-preload.cjs ./node_modules/vitest/vitest.mjs run --configLoader runner --config vitest.config.js)",
+      "Bash(go test *)",
+      "Bash(go build *)",
+      "Bash(go vet *)"
+    ]
+  }
+}

package/.prettierignore

@@ -0,0 +1,4 @@
+dist/
+coverage/
+node_modules/
+.claude/

package/.savepoint/Design.md

@@ -0,0 +1,196 @@
+---
+type: project-design
+status: active
+last_audited: E02-data-readers (2026-05-01)
+---
+
+# Savepoint — System Architecture
+
+> Project-level architecture. Audit-kept fresh: every epic's audit step merges its delta into this document.
+>
+> **Visual identity** lives separately in `.savepoint/visual-identity.md` and is loaded only for TUI/theme/visual tasks.
+
+## 1. Architecture model
+
+- **File-only.** No MCP server in v1. Agents read and edit Markdown + YAML files directly using their native file tools.
+- **Agent routing:** AGENTS.md → `.savepoint/router.md` → template prompts. See AGENTS.md Workflow section.
+- **Bundled Agent Skills:** Savepoint ships with custom skills (`draft-prd`, `system-design`, `create-plan`, `create-task`, `build-task`, `audit`) to enforce each phase of the state machine.
+- **Token-efficiency principle.**
+  - Cold session bootstrap: ~5–7K tokens (one-time per conversation).
+  - Per-task incremental: <2KB.
+  - Audit: 5–15KB.
+  - Anything that breaks these bounds violates the wedge.
+- **Go data-reader boundary:** established in epic `E02-data-readers` (2026-05-01). `internal/data` owns Savepoint file parsing and discovery for the Go implementation: task frontmatter models, markdown YAML extraction, router state parsing, config theme defaults, release/epic/task directory listing, and boundary error sentinels.
+- **Template assets** live under `templates/` with helpers in `src/templates/` (epic E04).
+- **Init command** (`savepoint init`) validates, scaffolds, prints prompt, clipboard, optional install (epic E05).
+- **Board command** (`savepoint board`) reads project, non-TTY fallback, Ink TUI, transition gates, mtime writes, audit signaling (epic E06).
+- **Audit pipeline** (`savepoint audit`) resolves epic, skips, quality gates, snapshots, router transition, proposal review (epic E07).
+
+## 2. Directory layout
+
+```
+<project-root>/
+├── AGENTS.md                       ← agent entry point
+└── .savepoint/
+    ├── PRD.md                      ← project vision (rare changes)
+    ├── Design.md                   ← project architecture (this file)
+    ├── visual-identity.md          ← design system; loaded conditionally for TUI work
+    ├── router.md                   ← state-machine routing
+    ├── config.yml                  ← theme, quality_gates, verify_strict
+    ├── audit/
+    │   └── {E##-epic}/
+    │       ├── snapshot.md
+    │       └── proposals/
+    │           └── proposals.md
+    └── releases/
+        └── v1/
+            ├── PRD.md              ← release-scoped PRD
+            └── epics/
+                └── E##-{epic-name}/
+                    ├── Design.md   ← epic delta
+                    └── tasks/
+                        └── T001-slug.md
+```
+
+AGENTS.md at root (uppercase, cross-vendor spec). Design.md in `.savepoint/` (working doc, not public-facing). visual-identity.md conditional — only loaded for TUI/theme/visual tasks. Subtasks are inline checklists inside task `.md` — never separate files. Epic folders and task files use `E##`/`T##` prefix. Scaffold assets live under `templates/`; generated projects receive rendered copies, not hardcoded strings.
+
+## 3. Hierarchy semantics
+
+| Level        | Definition                                                                             |
+| ------------ | -------------------------------------------------------------------------------------- |
+| **Release**  | The thing being built. One PRD per release. v1 = MVP.                                  |
+| **Epic**     | A major feature within a release. Has its own Design.md (delta from project Design).   |
+| **Task**     | Independently buildable. Objective-led. **Requires implementation plan before build.** |
+| **Sub-task** | Inline checklist item — _evidence of the implementation plan_, not standalone work.    |
+
+## 4. Status model & gates
+
+Three statuses, with explicit gates:
+
+| Status        | Meaning                    | Entry gate                                                      |
+| ------------- | -------------------------- | --------------------------------------------------------------- |
+| `planned`     | Ready to build             | plan section non-empty                                          |
+| `in_progress` | AI building                | all `depends_on` are `done`                                     |
+| `done`        | Complete for current scope | all implementation items checked; verification per project mode |
+
+- `blocked` is a **flag**, not a status — `in_progress` + `blocked: "reason"` is valid.
+- `done -> in_progress` is allowed so completed work can be reopened when follow-up work is required.
+- Verification mode: see `config.yml`.
+
+## 5. Dependencies
+
+- Declared in YAML frontmatter: `depends_on: [E##-epic/T###-task-id, ...]` (repo-relative IDs).
+- `src/validation/dependencies.ts` detects duplicate task IDs, missing dependencies, and dependency cycles.
+- Cross-epic deps allowed but warned (signal that epic boundaries may be wrong).
+
+## 6. CLI surface (4 commands, no extras)
+
+| Command                | Purpose                                                                           |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `savepoint init`       | Scaffold `.savepoint/`, print magic prompt to stdout + clipboard                  |
+| `savepoint board`      | Launch TUI; auto-falls-back to plain table on non-TTY                             |
+| `savepoint audit`      | Run audit pipeline (`--skip --reason`, `--epic`)                                  |
+| `savepoint doctor`     | Integrity check + ad-hoc quality-gate run + Layer-2 prompt for AI semantic review |
+| `--version` / `--help` | Standard global flags                                                             |
+
+- Bare `savepoint` prints help.
+- Source modules: see AGENTS.md Codebase Map.
+- **Explicitly rejected:** `task new`, `epic new`, `release new`, `plan`, `next`, `status`, `task done`. All are file edits or TUI actions.
+
+**Names:** npm package `savepoint`; binary `savepoint`. No `vk` alias.
+## 7. Audit pipeline (6 steps)
+
+```
+0. Quality Gates  — CLI runs configured commands. Halts on failure if block_on_failure: true.
+1. Snapshot       — CLI writes file tree (gitignore-respecting) + changed-files list. NO code contents.
+2. Diff Brief     — State flips to audit_pending: {E##-epic}. Magic prompt printed to user.
+3. Reconcile      — Agent reads epic Design + snapshot + scoped code. Writes one proposal bundle to
+                    .savepoint/audit/{E##-epic}/proposals.md.
+4. Review         — TUI shows side-by-side per-proposal diff. Approve / reject / edit each.
+5. Commit         — Approved proposals overwrite live files. Epic gets status: audited. Next epic unlocks.
+```
+
+- `audit_pending` is a **hard gate**: next epic's tasks cannot enter `in_progress` until prior epic is `audited`.
+- **High-divergence guard:** if a proposal changes >50% of the live file, TUI requires extra confirmation (threshold tunable in `config.yml`).
+- **Skip allowed** via `savepoint audit --skip --reason "..."`. Logged to `.savepoint/audit-log.md`. Permanent `⚠ skipped` badge in TUI.
+- **Proposal bundles** use delta-shaped edits: `Insert After`, `Replace`, or `Delete` blocks anchored to exact text.
+- **Quality review** is a section inside the proposal bundle.
+- **Snapshot availability is an audit precondition.** The router should enter `audit-pending` only after `.savepoint/audit/{E##-epic}/snapshot.md` exists.
+
+Three layers:
+
+- **Layer 1 (mechanical):** user's chosen linter. Recommended: eslint+dependency-cruiser (TS), radon+pylint (Python), gocyclo+staticcheck (Go). Cross-language fallback: `lizard`. Quality gate config: see `.savepoint/config.yml`.
+- **Layer 2 (AI semantic review):** baked into the audit reconcile prompt. Outputs a quality-review section in the proposal bundle. **Advisory, not blocking.**
+- **Layer 3:** `savepoint doctor` runs Layer 1 + prints Layer 2 prompt for ad-hoc use.
+
+## 8. TUI
+
+**Theming:** Atari-Noir is the default theme. **For full design tokens, palette, and rendering rules, see `.savepoint/visual-identity.md`** (loaded conditionally for TUI tasks). Live values in `config.yml` `theme:` section.
+
+Acknowledged terminal limits: fonts, scanlines, glows, letter-spacing, mouse-driven motion don't translate. Lean on color discipline + box-drawing geometry + uppercase headings.
+
+**Render fallbacks:** 256-color → 16-color hard-coded → `NO_COLOR=1` monochrome with glyphs → non-TTY plain table.
+
+**Layout:** single screen with a 5-column Kanban board and detail pane. Non-TTY output uses `src/tui/render/plain-table.ts`.
+
+**Implementation modules:** see AGENTS.md Codebase Map (E06 and E07 epic rows).
+
+**Keybindings:** arrow/vim navigation, enter advances, backspace retreats, r/R refreshes, a/A exits toward audit review when proposals exist, q quits.
+
+## 9. Concurrency
+
+- **mtime-based optimistic concurrency.** TUI status writes compare the expected task-file mtime before parsing and again immediately before a no-op or write; conflicts are reported as non-destructive messages that require manual refresh before retry.
+- Agents edit freely; the TUI defers.
+- **No lockfile.**
+
+## 10. Release versioning (PRDs)
+
+- Sequential integer (`v1`, `v2`). Optional `name` in YAML.
+- `savepoint doctor` warns when creating `v2` while `v1` has un-audited epics.
+
+## 11. Failure modes
+
+All failure modes are diagnosed by `savepoint doctor`. Doctor diagnoses and proposes; never auto-destructive.
+
+| Failure                                      | Behavior                                                    |
+| -------------------------------------------- | ----------------------------------------------------------- |
+| Corrupt YAML                                 | Doctor flags file:line. TUI marks `⚠ corrupt`, refuses ops. |
+| Missing dep                                  | Doctor flags. TUI shows `⚠ broken dep`.                     |
+| Dependency cycle                             | Doctor refuses to start either side; prints cycle path.     |
+| Duplicate task ID                            | Doctor flags.                                               |
+| Audit proposals without `audit_pending` flag | Doctor offers cleanup or restore.                           |
+| Task in nonexistent epic                     | Doctor moves to `.savepoint/orphans/`.                      |
+| Missing `config.yml`                         | All commands except `init` refuse.                          |
+| Unknown CLI flag                             | Show help, exit 1.                                          |
+
+## 12. Distribution & build
+
+> Audit note: the live repository is transitioning from the documented TypeScript/Node implementation to a Go module (`github.com/opencode/savepoint`). The architecture document still contains substantial TypeScript-era implementation detail and should be reconciled as Go epics are audited.
+
+- **License:** MIT.
+- **Install:** primary `npx savepoint init`, persistent `npm i -g savepoint` → `savepoint`.
+- **Runtime:** Node 20.10+ LTS, ESM-only, no native deps. macOS / Linux / Windows-Terminal.
+- **Repo:** single package. TypeScript strict. `tsup` build → `dist/`. Bin `dist/cli.js` shebanged.
+- **No telemetry.** Ever.
+
+## 13. Testing
+
+| Layer                                                    | Tool                             | Coverage                                                               |
+| -------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------- |
+| Unit: file ops, YAML, frontmatter, snapshot gen          | `vitest`                         | High                                                                   |
+| Unit: state transitions, dep resolution, cycle detection | `vitest`                         | High                                                                   |
+| Integration: CLI commands in temp dirs                   | `vitest` + `tmp`                 | Medium                                                                 |
+| TUI reducers (state, isolated from rendering)            | `vitest` + `ink-testing-library` | Medium                                                                 |
+| TUI rendering (snapshot tests)                           | —                                | **None.** Brittle.                                                     |
+| End-to-end with real AI agents                           | Manual matrix                    | Pre-release: `[Claude, Cursor, Gemini, Aider]` × `[init, plan, audit]` |
+
+~70% line coverage target; behavior coverage prioritized.
+
+## 14. Package versioning
+
+- `0.1.0` — first public release: scaffolding, status model, CLI, basic TUI, audit (no AI semantic review).
+- `0.2.0` — AI semantic review + broader quality-gate language presets.
+- `0.3.0` — file watching, search.
+- `1.0.0` — MCP server + production stability.
+
+Strict semver. Pre-1.0 minors may break.

package/.savepoint/PRD.md

@@ -0,0 +1,58 @@
+---
+type: project-prd
+status: active
+---
+
+# Savepoint — Product Vision
+
+## What it is
+
+A public OSS CLI + Ink-based TUI that scaffolds an opinionated AI-driven development workflow. The user runs `npx savepoint init` in an empty directory, points any AI agent (Claude / Cursor / Cline / Gemini / Aider / Codex) at the project, and the embedded prompt templates carry the agent through:
+
+> **PRD → Design → Epics → Tasks → Build → Audit**
+
+…with hard gates at each transition.
+
+run dev npm run build && node dist/cli.js board to test
+
+## Why
+
+Three failure modes plague AI-driven development today:
+
+1. **Inconsistency.** No repeatable process from high-level intent to working MVP.
+2. **Token bloat.** Monolithic backlogs and MCP overhead burn context for everyone, but especially users on minimal AI plans.
+3. **Documentation drift.** `Design.md` and agent instructions go stale after the first iteration; nobody updates them.
+
+Savepoint addresses all three with a single mechanism: **a file-based state machine that any agent can follow, where every epic completion forces a documentation audit before the next epic can start.**
+
+## Target user
+
+**Vibe coders** — builders with minimal-to-moderate development experience, on minimal AI plans, who want AI agents to drive most of the implementation while a structured workflow keeps the project coherent.
+
+Not: experienced engineers who already have their own systems. (They can still use it; they're not the audience.)
+
+## Headline differentiator
+
+**The Audit Loop.** When the last task in an epic moves to `done`, the next epic cannot start until `Design.md`, `AGENTS.md`, and the epic's own design have been reconciled with the actual code that was built. No existing markdown-first task tool has this gate.
+
+Token-efficient hierarchy and markdown-first storage are table stakes. The audit loop is the marketing-first feature.
+
+## Success metrics
+
+- **Token usage:** AI agents complete tasks reading <2KB of context per task. Audit budget bounded to ~5–15KB.
+- **Documentation accuracy:** zero drift — `AGENTS.md` always correctly maps the current codebase, enforced by gate.
+- **Agent reach:** works with any agent that can read markdown and edit files (no MCP required, no per-agent adapters).
+- **Time-to-first-PR:** a vibe coder can go from `npx savepoint init` to a merged epic in one weekend.
+
+## Constraints
+
+- File-only architecture for v1. No MCP server.
+- Agent-agnostic via the [Router Pattern](Design.md). No per-agent forks.
+- Recommended planning model is top-tier (Opus / Gemini Pro / GPT-5.5 equivalent). Lighter models work for execution but planning fidelity drops.
+
+## Out of scope (forever or for now)
+
+- Telemetry. Ever.
+- Multi-user collaboration / cloud sync.
+- Mouse / drag-and-drop in the TUI.
+- Per-language adapter code (we recommend tools, don't ship them).

package/.savepoint/audit/E01-go-setup/proposals.md

@@ -0,0 +1,166 @@
+# E01-go-setup Audit Proposals
+
+## Target File
+
+`.savepoint/Design.md`
+
+## Replace
+
+```md
+## 12. Distribution & build
+
+- **License:** MIT.
+- **Install:** primary `npx savepoint init`, persistent `npm i -g savepoint` → `savepoint`.
+- **Runtime:** Node 20.10+ LTS, ESM-only, no native deps. macOS / Linux / Windows-Terminal.
+- **Repo:** single package. TypeScript strict. `tsup` build → `dist/`. Bin `dist/cli.js` shebanged.
+- **No telemetry.** Ever.
+- **Baseline scaffold:** established in epic `E01-scaffolding` (2026-04-27). Package name `savepoint`, version `0.1.0`. Build, typecheck, lint, format, and test gates all pass.
+```
+
+## With
+
+```md
+## 12. Distribution & build
+
+- **License:** MIT.
+- **Install:** local Go build during the rewrite; public install channel remains release work.
+- **Runtime:** Go 1.23+ target, single native binary. macOS / Linux / Windows-Terminal.
+- **Repo:** Go module `github.com/opencode/savepoint`. Build with `go build`; test with `go test ./...`.
+- **No telemetry.** Ever.
+- **Go baseline scaffold:** established in epic `E01-go-setup` (2026-05-01). The project now has `go.mod`, `go.sum`, `main.go`, `internal/board`, and Makefile shortcuts for build/test/run/clean.
+```
+
+## Target File
+
+`.savepoint/Design.md`
+
+## Insert After
+
+```md
+## 8. TUI
+```
+
+## With
+
+```md
+
+**Go rewrite baseline:** E01 creates a minimal Bubble Tea shell in `internal/board`. The root `main.go` delegates process startup to `board.Run()`, which owns the Bubble Tea program lifecycle. Later board epics should move richer rendering, input state, and styling into focused packages rather than expanding `main.go`.
+```
+
+## Target File
+
+`AGENTS.md`
+
+## Replace
+
+~~~~md
+## Build / Test / Run
+
+```bash
+npm run build        # compile src/ → dist/cli.js via tsup (ESM, node20)
+npm run typecheck    # tsc --noEmit strict check (NodeNext)
+npm run lint         # eslint flat config — rejects any in TypeScript
+npm run format:check # prettier check across src, test, config, markdown
+npm test             # vitest smoke suite
+```
+~~~~
+
+## With
+
+````md
+## Build / Test / Run
+
+```bash
+go build ./...       # compile all Go packages
+go test ./...        # run Go test suite
+make build           # shortcut: go build -o savepoint main.go
+make test            # shortcut: go test ./...
+make run             # shortcut: go run main.go
+```
+````
+
+## Target File
+
+`AGENTS.md`
+
+## Replace
+
+```md
+<!-- AUTO-GENERATED BY savepoint audit. Do not edit manually. -->
+```
+
+## With
+
+```md
+<!-- AUTO-GENERATED BY savepoint audit. Do not edit manually. -->
+
+| Module                    | Epic                                                                    | Purpose                                                         |
+| ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `go.mod`                  | [E01-go-setup](.savepoint/releases/v1/epics/E01-go-setup/Design.md)     | Go module definition for the Savepoint CLI rewrite              |
+| `go.sum`                  | [E01-go-setup](.savepoint/releases/v1/epics/E01-go-setup/Design.md)     | Dependency checksums for Bubble Tea, Lip Gloss, YAML, and deps  |
+| `main.go`                 | [E01-go-setup](.savepoint/releases/v1/epics/E01-go-setup/Design.md)     | Process entrypoint; delegates Bubble Tea startup to board.Run   |
+| `Makefile`                | [E01-go-setup](.savepoint/releases/v1/epics/E01-go-setup/Design.md)     | Local build, test, run, and clean shortcuts                     |
+| `internal/board/board.go` | [E01-go-setup](.savepoint/releases/v1/epics/E01-go-setup/Design.md)     | Minimal Bubble Tea model, quit handling, and program lifecycle  |
+```
+
+## Target File
+
+`.savepoint/releases/v1/epics/E01-go-setup/Design.md`
+
+## Replace
+
+```md
+status: planned
+```
+
+## With
+
+```md
+status: audited
+```
+
+## Target File
+
+`.savepoint/releases/v1/epics/E01-go-setup/Design.md`
+
+## Insert After
+
+```md
+## Components and files
+```
+
+## With
+
+```md
+
+## Implemented as
+
+- `go.mod` uses module path `github.com/opencode/savepoint` and Go `1.26.2` in the current local toolchain.
+- `main.go` is intentionally thin and delegates to `internal/board.Run()`.
+- `internal/board/board.go` contains the first Bubble Tea model, `q`/`ctrl+c` quit handling, and the program runner.
+- `Makefile` provides build/test/run/clean shortcuts, but `make` is not available in the audited Windows environment.
+- `cmd/` and `internal/styles/` currently exist as empty directories. Add placeholder files if those directories must survive git checkout before later epics add code.
+```
+
+## Quality Review
+
+## Must Fix Before Close
+
+- `internal/data/discover_test.go` fails `go test ./...` because imports `os` and `path/filepath` are unused. This is active E02 work, not E01 code, but it blocks the repo-level quality gate.
+
+## Must Fix Before Next Epic
+
+- `AGENTS.md` and `.savepoint/Design.md` still describe the old TypeScript/npm architecture and quality gates in several sections. Apply or refine the proposal sections above so future agents do not follow stale commands.
+- `cmd/` and `internal/styles/` are empty directories. Git will not preserve them unless later code lands there or placeholders are added.
+
+## Carry Forward
+
+- `internal/board/board.go` currently writes errors to stderr inside `Run()` and `main.go` panics on the returned error. Before the CLI grows real command handling, centralize boundary error presentation so failures do not double-report or emit stack-like panic output.
+- `Makefile` uses `rm -f savepoint`, which is fine under POSIX shells but is not enough for native Windows cleanup of `savepoint.exe`. Consider making clean cross-platform or documenting the expected shell.
+
+## Already Fixed
+
+- `go build ./...` passes outside the sandbox.
+- The root TypeScript scaffold files are removed from the working tree as required by the E01 definition of done.
+- `main.go` delegates to `internal/board`, and `q`/`ctrl+c` quit handling is implemented.
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T001-init-module.md` now has checked implementation items and a `## Context Log`.

package/.savepoint/audit/E01-go-setup/snapshot.md

@@ -0,0 +1,71 @@
+---
+type: audit-snapshot
+epic: E01-go-setup
+created: 2026-05-01
+mode: manual
+---
+
+# E01-go-setup Audit Snapshot
+
+Manual snapshot created because the router was already on E02 and the audit CLI is not the source of truth for this Go rewrite state.
+
+## Epic Scope
+
+- Initialize Go module `github.com/opencode/savepoint`.
+- Add Bubble Tea, Lip Gloss, and YAML dependencies.
+- Add root `main.go` entrypoint.
+- Add `internal/board` Bubble Tea shell.
+- Add `cmd/`, `internal/data/`, and `internal/styles/` directories.
+- Add `Makefile` targets for build, test, run, and clean.
+- Remove the old TypeScript/npm root scaffold.
+
+## Files Read
+
+- `.savepoint/router.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/Design.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T001-init-module.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T002-entrypoint.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T003-directory-structure.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T004-makefile.md`
+- `agent-skills/ink-tui-design/SKILL.md`
+- `.savepoint/visual-identity.md`
+- `.savepoint/Design.md`
+- `AGENTS.md`
+- `go.mod`
+- `go.sum`
+- `main.go`
+- `internal/board/board.go`
+- `Makefile`
+
+## Changed Files in Epic Scope
+
+- `go.mod`
+- `go.sum`
+- `main.go`
+- `internal/board/board.go`
+- `Makefile`
+- `.savepoint/releases/v1/epics/E01-go-setup/Design.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T001-init-module.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T002-entrypoint.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T003-directory-structure.md`
+- `.savepoint/releases/v1/epics/E01-go-setup/tasks/T004-makefile.md`
+
+## Directory Checks
+
+- `cmd/` exists.
+- `internal/board/` exists and contains `board.go`.
+- `internal/data/` exists but currently contains E02 data-reader work, outside E01 scope.
+- `internal/styles/` exists but is empty.
+
+## Verification
+
+- `go env GOVERSION`: `go1.26.2`
+- `go build ./...`: pass when run outside the sandbox.
+- `go test ./...`: fail. Failure is in `internal/data/discover_test.go` from active E02 work: unused imports `os` and `path/filepath`.
+- `make test`: not runnable in this Windows environment because `make` is not installed.
+
+## Notes
+
+- The router currently points to `E02-data-readers/T001-task-struct`, so this audit is an explicit manual override for E01.
+- The working tree contains a broad TypeScript-to-Go rewrite. Deleted TypeScript files are not treated as E01 regressions because the E01 design explicitly requires removing the TypeScript root scaffold.
+- Empty directories such as `cmd/` and `internal/styles/` are not represented by `git ls-files` unless placeholder files are added.

package/.savepoint/audit/E01-scaffolding/proposals/AGENTS.md

@@ -0,0 +1,66 @@
+# Agents Guide
+
+Welcome, AI agent. This project (`savepoint`) uses its own conventions to manage its own build. You are about to dogfood the workflow.
+
+## Workflow
+
+Before doing anything, read `.savepoint/router.md`. That file routes you to the next file based on the project's current state.
+
+When you are about to write code, you must first read, in order:
+
+1. `.savepoint/PRD.md` — what we are building and why
+2. `.savepoint/Design.md` — how the system is architected
+3. The release PRD: `.savepoint/releases/v1/PRD.md`
+4. The epic Design: `.savepoint/releases/v1/epics/{epic}/Design.md`
+5. The active task file: `.savepoint/releases/v1/epics/{epic}/tasks/{NNN}-*.md`
+
+**Conditional read:** if the active task touches TUI rendering, theme, or visual design, also read `.savepoint/visual-identity.md`. Otherwise skip it — it's ~1.8K tokens you don't need.
+
+**Do not load files outside the current task scope** unless the task requires it. Token discipline is the wedge of this product; we honor it on ourselves.
+
+## Build / Test / Run
+
+```bash
+npm run build        # compile src/ → dist/cli.js via tsup (ESM, node20)
+npm run typecheck    # tsc --noEmit strict check (NodeNext)
+npm run lint         # eslint flat config — rejects any in TypeScript
+npm run format:check # prettier check across src, test, config, markdown
+npm test             # vitest smoke suite
+```
+
+> **Windows note:** `npm test` uses a custom preload script (`scripts/vitest-preload.cjs`) and `vitest.config.js` (not `.ts`) to work around a Windows-specific child_process/esbuild issue. This is transparent when running through npm scripts.
+
+## Code Style
+
+1. **One job per file.** If a file does two things, split it.
+2. **One-sentence rule.** If you can't describe a function in one sentence, refactor.
+3. **Test what branches.** Logic with if/else/switch gets a test. Pure rendering: skip.
+4. **Types are documentation.** No `any`. Let the compiler help.
+5. **Build, don't speculate.** No code for hypothetical futures.
+6. **Errors at boundaries.** Handle failure where data enters or leaves the system.
+7. **One source of truth.** State lives in one place. No syncing copies.
+8. **Comments explain WHY,** not what. If removing the comment wouldn't confuse a future reader, delete it.
+9. **Content in data files.** Markdown/JSON/YAML, not strings in code.
+10. **Small diffs.** Each task touches as few files as possible.
+
+## Codebase Map
+
+<!-- AUTO-GENERATED BY savepoint audit. Do not edit manually. -->
+
+| Module               | Epic                                                                      | Purpose                                              |
+| -------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `src/cli.ts`         | [E01-scaffolding](.savepoint/releases/v1/epics/E01-scaffolding/Design.md) | CLI entrypoint; placeholder help/version output      |
+| `src/version.ts`     | [E01-scaffolding](.savepoint/releases/v1/epics/E01-scaffolding/Design.md) | Single source for package version string             |
+| `test/smoke.test.ts` | [E01-scaffolding](.savepoint/releases/v1/epics/E01-scaffolding/Design.md) | Baseline Vitest smoke test proving test runner works |
+
+<!-- END AUTO-GENERATED -->
+
+## CLI rules for agents
+
+**Never run `savepoint` commands.** The CLI is for the human. Edit files directly.
+
+(For this repo specifically: `savepoint` doesn't exist yet — we're building it. Even once it exists, this rule stands.)
+
+## Recommended planning models
+
+For PRD/Design/Task planning, this workflow assumes a top-tier model: Claude Opus, Gemini 2.5 Pro, GPT-5.5, or equivalent. Lighter models may not follow embedded prompt instructions reliably. If you are not one of those, advise the user before proceeding with planning steps.