savepoint 1.0.0

package/.savepoint/releases/v1/epics/_archived/E10-docs-and-packaging/Design.md

@@ -0,0 +1,68 @@
+---
+type: epic-design
+status: active
+---
+
+# Epic E10: docs-and-packaging
+
+## Purpose
+
+Prepare Savepoint as a public npm package with clear user-facing documentation, correct package metadata, and validated publish contents.
+
+## What this epic adds
+
+- Public README suitable for npm and GitHub.
+- MIT license finalized.
+- Package metadata review for repository, keywords, files, bin, engines, and exports.
+- `npm pack` validation.
+- Local install smoke tests from the packed tarball.
+- Documentation for install, init, board, audit, doctor, and the audit loop.
+- Release checklist draft for `0.1.0`.
+
+## Components and files
+
+Expected files introduced or extended by this epic:
+
+| Path                             | Purpose                                            |
+| -------------------------------- | -------------------------------------------------- |
+| `README.md`                      | Public product and usage documentation.            |
+| `LICENSE`                        | Final MIT license text.                            |
+| `package.json`                   | Publish metadata and package allowlist.            |
+| `.npmignore` or `files` field    | Publish contents control.                          |
+| `docs/*.md`                      | Optional focused docs if README becomes too large. |
+| `scripts/*.ts` or `scripts/*.js` | Optional pack/install smoke helpers.               |
+| `test/packaging/**/*.test.ts`    | Packaging validation tests if scriptable.          |
+
+## Architectural delta
+
+Before this epic, the package can function locally. After this epic, the package is shaped for public consumption and can be validated as a packed npm artifact.
+
+This epic does not publish the package; it makes publishing boring and inspectable.
+
+## Boundaries
+
+In scope:
+
+- Public docs and package metadata.
+- Packed artifact validation.
+- Local install smoke tests.
+- Ensure generated `dist/cli.js` is the published binary.
+
+Out of scope:
+
+- Actual npm publish.
+- Manual agent matrix.
+- Broad marketing site work.
+- Major feature changes discovered during docs writing unless they block package correctness.
+
+## Quality gates
+
+- `npm pack --dry-run` or equivalent should show only intended files.
+- Packed install smoke should verify `savepoint --help` and `savepoint --version`.
+- README examples should match implemented command behavior.
+
+## Design constraints
+
+- Keep docs plain and practical for vibe coders.
+- Do not over-document deferred features.
+- Treat package contents as a release contract.

package/.savepoint/releases/v1/epics/_archived/E11-release-validation/Design.md

@@ -0,0 +1,68 @@
+---
+type: epic-design
+status: active
+---
+
+# Epic E11: release-validation
+
+## Purpose
+
+Run the final validation matrix for `0.1.0`, resolve release-blocking issues, and prepare the public release cut.
+
+## What this epic adds
+
+- Manual e2e test matrix across Claude, Cursor, Gemini, and Aider where available.
+- Cross-platform checks for macOS, Linux, and Windows Terminal where available.
+- Fresh-project `npx savepoint init` validation.
+- Full command walkthrough: init, board, audit, and doctor.
+- Final version check for `0.1.0`.
+- Release notes.
+- Publish-readiness checklist.
+
+## Components and files
+
+Expected files introduced or extended by this epic:
+
+| Path                        | Purpose                                           |
+| --------------------------- | ------------------------------------------------- |
+| `docs/release-checklist.md` | Final release checklist and results.              |
+| `docs/e2e-matrix.md`        | Manual agent/platform matrix results.             |
+| `CHANGELOG.md`              | Initial release notes.                            |
+| `package.json`              | Final version metadata if needed.                 |
+| `.savepoint/audit-log.md`   | Audit history if audits were skipped or recorded. |
+
+## Architectural delta
+
+Before this epic, the package should be feature-complete for v0.1.0. After this epic, the release has documented validation evidence and can be published with known residual risks.
+
+This epic should prefer fixing release blockers in the smallest responsible place over broad refactors.
+
+## Boundaries
+
+In scope:
+
+- Manual matrix execution and recording.
+- Cross-platform smoke validation.
+- Final bug fixes required to pass release criteria.
+- Release notes and version confirmation.
+
+Out of scope:
+
+- New features.
+- v0.2.0 semantic review.
+- File watching.
+- Search.
+- MCP server work.
+
+## Quality gates
+
+- All automated tests pass.
+- Packed install smoke passes.
+- Manual e2e matrix passes against at least three of four target agents.
+- Known limitations are documented.
+
+## Design constraints
+
+- Keep late fixes narrow and auditable.
+- Do not relax quality gates to ship.
+- Record evidence, not vibes.

package/.savepoint/releases/v1.1/epics/E01-tui-optimisation/Design.md

@@ -0,0 +1,26 @@
+---
+type: epic-design
+status: planned
+---
+
+# Epic E01: TUI Optimisation
+
+## Purpose
+
+Performance, layout robustness, and structural improvements for the board TUI. Focused on fixing rendering edge-cases (resize clipping, wasted space) and improving the codebase's architectural hygiene around file watching and data refresh.
+
+## Definition of Done
+
+- Right-border clipping is eliminated at all terminal widths ≥ 40
+- Resize handling is robust — no corruption, no artifacts when growing/shrinking
+- The board auto-refreshes when task files change on disk via fsnotify
+
+## Components and files
+
+| Path | Purpose |
+|------|---------|
+| `internal/board/layout.go` | Layout arithmetic and resize guards |
+| `internal/board/view.go` | Minimum width clamping |
+| `internal/board/watch.go` | File watcher and reload commands |
+| `internal/board/model.go` | Watcher lifecycle |
+| `internal/board/update.go` | Reload message handling |

package/.savepoint/releases/v1.1/epics/E01-tui-optimisation/tasks/T001-border-resize-fix.md

@@ -0,0 +1,35 @@
+---
+id: E01-tui-optimisation/T001-border-resize-fix
+status: planned
+objective: "Fix right-border clipping and ensure clean rendering on terminal resize"
+depends_on: []
+---
+
+# T001: Fix Right-Border Clipping and Resize Robustness
+
+## Acceptance Criteria
+
+- The board frame right border (`│` or rounded corner) is always visible at any terminal width ≥ 40 chars
+- Reducing terminal width below a breakpoint (120→119, 80→79) does not leave stray pixels or broken border artifacts
+- Reducing to very narrow widths (< 50) degrades gracefully (no visual corruption)
+- Expanding terminal width back renders cleanly with no leftover characters from previous dimensions
+- All existing layout breakpoints (120/80) still function correctly
+
+## Implementation Plan
+
+- [ ] Edit `internal/board/layout.go` — audit width arithmetic to ensure total content width exactly fills `width - boardFrameOverhead` at every breakpoint; use `totalWidth := cw*colCount + colOverhead*colCount` and pad any remainder so it matches `inner` exactly.
+- [ ] Edit `internal/board/view.go` — add minimum terminal width clamping (e.g., floor to 40) in `View()` to prevent degenerate states.
+- [ ] Edit `internal/board/layout.go` — add a `minBoardWidth` const and guard `CalculateLayout` inputs below it.
+- [ ] Run `make build && make test` to verify no regressions.
+
+## Context Log
+
+Files read:
+- `internal/board/layout.go`
+- `internal/board/view.go`
+- `internal/board/update.go`
+
+Estimated input tokens: 600
+
+Notes:
+- Moved from `E06-atari-noir-layout/T006-border-resize-fix` (release v1) to `E01-tui-optimisation` (release v1.1).

package/.savepoint/router.md

@@ -0,0 +1,136 @@
+# Agent State Machine
+
+This file routes the agent based on the project's current state. Read this whenever you start a session.
+
+## Read order on every session
+
+1. This file (you are here)
+2. The current state below to know what to do next
+3. The active epic Design
+4. The active task file, when a task is selected
+
+Read `.savepoint/PRD.md` only for project vision changes. Read `.savepoint/Design.md` only for architecture changes or audit closeout. Read `.savepoint/releases/v1/PRD.md` only for release planning or epic-order questions.
+
+**Conditional read (token discipline):** if your active task touches **TUI rendering, theme, or visual design**, also read `.savepoint/visual-identity.md` after Design.md. Otherwise skip it — it's ~1.8K tokens you don't need.
+
+## Current state
+
+```yaml
+state: task-building
+release: v1.1
+epic: E01-tui-optimisation
+task: E01-tui-optimisation/T001-border-resize-fix
+next_action: Execute T001 — Fix right-border clipping and resize robustness.
+```
+
+## State → next action
+
+<!-- AGENT: Read the state above. Find the matching block below. Follow it. -->
+
+### `state: pre-implementation`
+
+The project has its PRD and Design locked but no epics defined yet.
+
+**Next action:**
+
+1. Read `.savepoint/releases/v1/PRD.md` — the v1 release scope (epic list lives there).
+2. Help the user define the epics list and confirm priority.
+3. For each epic in order, create the directory `.savepoint/releases/v1/epics/E##-{epic-name}/` with a `Design.md` stub.
+4. When epic E01 (scaffolding) is created, transition to `state: epic-design` for that epic.
+
+**Do not** start writing code. We are still in planning.
+
+### `state: epic-design`
+
+An epic exists but its `Design.md` is empty or a stub.
+
+**Next action:** Walk the user through filling out the epic's `Design.md`:
+
+- What is this epic adding to the system?
+- What components / files does it touch?
+- What's the architectural delta vs the current state?
+
+When complete, transition to `state: epic-task-breakdown` for this epic.
+
+### `state: epic-task-breakdown`
+
+Epic Design exists but tasks are missing or not fully planned.
+
+**Next action:**
+
+1. Re-read the epic Design.
+2. Create or update the full epic task list — each task **independently buildable**, **objective-led**, with declared `depends_on`.
+3. Each task file lives at `.savepoint/releases/v1/epics/{E##-epic}/tasks/TNNN-slug.md` with frontmatter:
+   ```yaml
+   ---
+   id: {E##-epic}/TNNN-slug
+   status: planned
+   objective: "<one sentence>"
+   depends_on: []
+   ---
+   ```
+4. In the same pass, write each task's `## Implementation Plan` as inline `- [ ]` checkboxes.
+5. When every task is planned, transition to `state: task-building` for the first unblocked task.
+
+### `state: task-planning`
+
+Reserved for repair or late-added tasks. Normal epic planning happens during `state: epic-task-breakdown`.
+
+**Next action:** Read the task's `objective`. Write the implementation plan as inline `- [ ]` checkboxes under a `## Implementation Plan` heading. Set `status: planned`. Stop.
+
+### `state: task-building`
+
+Task is `in_progress`. All `depends_on` are `done`.
+
+**Next action:** Execute the plan. Tick checkboxes as you complete them. Edit code per the **Code Style** rules in `AGENTS.md`. When all checkboxes tick, set `status: review` and stop.
+
+### `state: audit-pending`
+
+The last task in an epic is `done`. Audit must run before the next epic starts.
+
+**Next action:** Confirm `.savepoint/audit/{E##-epic}/snapshot.md` exists. If it is missing while the audit CLI is still unavailable, create one manual snapshot from the known epic scope once; do not search broadly for replacement inputs. Then read the snapshot, read the epic's `Design.md`, and read only the files listed as changed. Write one patch-shaped proposal bundle to `.savepoint/audit/{E##-epic}/proposals.md`:
+
+- `Design.md` section — merge only the epic delta into project architecture.
+- `AGENTS.md` section — refresh Codebase Map entries from changed-module metadata; preserve existing rows.
+- `epic-Design.md` section — add "implemented as:" notes and deltas from the original plan.
+- `Quality Review` section — semantic-review findings against the 10 Code Style rules (advisory only).
+
+Prefer delta-only edits (`Insert After`, `Replace`, `Delete`) anchored to exact text. Do not quote and replace entire large sections unless the whole section genuinely changed.
+
+Proposal format:
+
+```md
+## Target File
+
+`path/to/file.md`
+
+## Replace
+
+<exact old heading, marker, or section>
+
+## With
+
+<new content>
+```
+
+Quality review section format:
+
+```md
+## Must Fix Before Close
+
+## Carry Forward
+
+## Already Fixed
+```
+
+After proposals are approved, apply approved proposals to live files, mark the epic `Design.md` as `status: audited`, update project `Design.md` `last_audited`, refresh `AGENTS.md` Codebase Map, and advance this router to the next epic state.
+
+Stop. The user reviews proposals in the TUI before commit actions.
+
+## Capability check
+
+If you are not Claude Opus / Gemini 2.5 Pro / GPT-5.5 / equivalent, surface a warning to the user:
+
+> _"Heads up — I'm running on a lighter model. Savepoint's planning steps work best with top-tier models because the embedded prompts are detailed. I'll do my best, but consider switching the model for PRD/Design/Task-breakdown steps."_
+
+Then proceed.

package/.savepoint/visual-identity.md

@@ -0,0 +1,124 @@
+---
+type: visual-identity
+status: active
+last_audited: never
+---
+
+# Visual Identity — Atari-Noir
+
+> The brand identity and visual guardrails for savepoint. **Loaded conditionally** — only when working on TUI rendering, theme, or design-system tasks. Non-visual tasks must skip this file to honor the token budget.
+
+For Ink/TUI implementation mechanics, use `agent-skills/ink-tui-design/SKILL.md`. This file only owns visual and product-design constraints.
+
+## Vibe
+
+A serious digital system that loves old arcade hardware. Dark, cinematic, playful. Crisp, not noisy. Technical, not cold.
+
+**Avoid:** neon cyberpunk chaos, SaaS minimalism, fake terminal gimmicks.
+
+## Palette
+
+| Element       | Hex       | Role                          |
+| ------------- | --------- | ----------------------------- |
+| Background    | `#121212` | Main screen background        |
+| Surface       | `#0D0D0D` | Cards and panels              |
+| Surface 2     | `#0F0F0F` | Secondary panels / title bars |
+| Border        | `#1A1A1A` | Quiet structural edges        |
+| Border Subtle | `#222222` | Slightly stronger separators  |
+| Primary Text  | `#F0E6DA` | Warm off-white terminal text  |
+| Atari Orange  | `#FC6323` | Primary CTA, active highlight |
+| NPP Green     | `#A4C639` | Success, live systems         |
+| Vibe Purple   | `#B1A1DF` | AI, reflection                |
+
+**Color rules:**
+
+- **Intentional accents.** One accent color per major section/type. Use for labels, hover, glows, active text — never giant background fills.
+- **Dark backgrounds.** Keep them dark so accents pop.
+- **Visual encoding.** Color semantically encodes categories or states; reinforce with minimal text.
+
+## Typography
+
+- **System heading font:** `Chakra Petch` (web only — terminal cannot control fonts)
+- **System body/UI font:** `Space Mono` (web only — terminal cannot control fonts)
+- **Accent retro fonts:** `Silkscreen` or `Press Start 2P`, used rarely for score counters or deliberately extreme moments
+
+**Rules:**
+
+- Headings uppercase, with deliberate letter-spacing where the medium allows.
+- Body readable and restrained; abandon monospace for long text if readability suffers.
+- Render magnitude/comparison numbers as proportional visuals (bars, circles), not raw values.
+
+## Spacing rhythm
+
+- Sections breathe. Default spacing feels generous.
+- Cards have enough internal padding to feel like panels, not chips.
+- Whitespace creates hierarchy before borders or color do.
+
+## Signature UI patterns
+
+- **Scanlines** — low-opacity CRT atmosphere; never obscure readability.
+- **Glows** — radiate from perimeter ("lit from within"). Transparent section accent colors; no neon spam.
+- **Panels** — flat, dark, structured with quiet borders. Depth from contrast/glow, not heavy shadows.
+- **Search** — simple, single-line; integrated with section accent color.
+- **MDX prose** — integrated using standard typography, palette, border logic.
+
+## Interaction principles ("The Playable Dashboard")
+
+**Content is the interface.** Avoid traditional UI patterns (dropdowns, accordions) if content can express the information directly.
+
+- **Show, don't explain.** Visuals (scaled circles, markers) before text.
+- **Motion** — authored, not generic. Ease like a system booting up. No bouncy toy motion.
+- **Hover & focus** — internal light (underglow/surface tint), not thick outlines or loud transforms.
+- **Expansion** — breathe open, don't snap. Inline reveals, shared-element transitions.
+
+## Replication brief
+
+If recreating this look-and-feel, preserve:
+
+- dark charcoal background with warm off-white text
+- three-color accent system (one per major section)
+- `Chakra Petch` for headings, `Space Mono` for body/UI (where typography can be controlled)
+- uppercase, tracked headings
+- quiet borders, dark surfaces, selective glow
+- one strong interactive hero element
+- copy that sounds human, competent, intentionally non-corporate
+- **Young Explorer Baseline:** all content and visuals understandable by a 7-year-old. Intuitive visual metaphors, no unexplained jargon, discoverable through play.
+
+**Family resemblance, not exact duplication.** Preserve the underlying feel, hierarchy, restraint.
+
+## Flex & constraints
+
+- **Layout & components:** can adapt to content needs, provided palette discipline and tonal restraint remain.
+- **Fonts:** supporting fonts can vary if heading/body contrast remains.
+- **Hero:** interaction can vary, but requires one strong, ownable interactive element.
+- **Visual-first:** show relationships visually before explaining them in text (gradient bar > numbers). Text reinforces; visuals carry comprehension.
+- **Cognitive accessibility:** anchor complex concepts to physical/visual analogies a 7-year-old can grasp.
+
+## What survives in the terminal
+
+| Web rule                            | Terminal feasibility | Adaptation                                                       |
+| ----------------------------------- | -------------------- | ---------------------------------------------------------------- |
+| Dark bg + warm off-white text       | ✓                    | 24-bit color with 256/16-color fallbacks                         |
+| 3-color accent system               | ✓                    | per status, per epic, per section                                |
+| `Chakra Petch` / `Space Mono` fonts | ✗                    | terminal owns the font; README discloses                         |
+| Uppercase tracked headings          | ⚠                    | uppercase yes; letter-spacing no (fixed-width cells)             |
+| Scanlines                           | ✗                    | flicker/ugly in text — skip                                      |
+| Glows / underglow                   | ⚠                    | substitute with subtle bg tint on focused row + accent border    |
+| Quiet borders, dark surfaces        | ✓                    | box-drawing chars (`─ │ ┌ ┐`) in border-subtle gray              |
+| Inline reveal cards                 | ✓                    | Ink state-driven expand/collapse                                 |
+| Visual encoding before text         | ✓                    | colored glyphs (`▣ ◇ ◆ ✓`) with text reinforcement               |
+| "System booting up" motion          | ⚠                    | 200ms init sequence on launch acceptable; running animation skip |
+
+## Terminal UI guardrails
+
+- Keep UI state explicit and local to the smallest useful surface.
+- Use project data files as the source of truth; do not invent hidden UI state.
+- Keep layout compact and readable on narrow terminals first.
+- Treat accidental line wrapping as a bug.
+- Make selection, focus, and status changes obvious without relying on color alone.
+- Make every keyboard action predictable and idempotent.
+- Test branching input handling, navigation, state transitions, render output, and non-TTY fallbacks.
+
+## When `savepoint init` ships
+
+This file is the canonical default that `savepoint init` writes into a user's `.savepoint/visual-identity.md`. Users replace it with their own design system. The file's existence (not its contents) is what `savepoint` cares about.

package/AGENTS.md

@@ -0,0 +1,141 @@
+# 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.
+
+**Available Custom Skills:**
+Savepoint ships with skills that define your role at each stage.
+- `draft-prd`: Acts as a strict Product Manager to interrogate the user and write the PRD.
+- `system-design`: Acts as a Staff Engineer mapping the architecture.
+- `create-plan` / `create-task`: Acts as a Technical PM breaking work into Epics and ACs.
+- `build-task`: Acts as the disciplined execution engine writing code and logging drift.
+- `audit`: Acts as the QA Lead reconciling code with documentation.
+
+**Skill Activation (CRITICAL):**
+When you read `.savepoint/router.md`, you MUST activate the corresponding agent skill for the current state before taking any action. Use the `activate_skill` tool (or equivalent) for the appropriate phase:
+- `state: draft-prd` -> Activate the `draft-prd` skill.
+- `state: design` -> Activate the `system-design` skill.
+- `state: planning` -> Activate the `create-plan` skill.
+- `state: task-breakdown` -> Activate the `create-task` skill.
+- `state: in-progress` -> Activate the `build-task` skill.
+- `state: audit-pending` -> Activate the `audit` skill.
+
+When you are about to write code, you must first read, in order:
+
+1. `.savepoint/router.md` — current state and next action
+2. The active epic Design: `.savepoint/releases/v1/epics/{E##-epic}/Design.md`
+3. The active task file: `.savepoint/releases/v1/epics/{E##-epic}/tasks/{T###}-*.md`
+4. Directly touched source/test files
+
+Read `.savepoint/PRD.md` only for project vision changes, major scope questions, or when the router explicitly asks for it.
+Read `.savepoint/Design.md` only when the task changes architecture or audit state. Read `.savepoint/releases/v1/PRD.md` only when planning epics, changing release scope, or resolving epic order.
+
+**Conditional read:** if the active task touches TUI implementation, also read `agent-skills/ink-tui-design/SKILL.md` as the execution guide. If it touches TUI rendering, theme, or visual design, also read `.savepoint/visual-identity.md` as the visual guardrails. Otherwise skip the extra files — they are tokens you do not 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.
+
+Planning and implementation are separate handoffs:
+
+- Epic task breakdown and detailed task planning happen together in one pass by one planning agent.
+- Each task file must be independently buildable, objective-led, include explicit `depends_on` IDs, contain `## Acceptance Criteria` (observable outcomes) before `## Implementation Plan` (build checklist), and include a `## Context Log` for files read, estimated input tokens, and notes.
+- Implementation happens one task at a time and may be handed to any agent. Clear context between tasks by default; rehydrate only from the router, active epic Design, active task file, and directly touched source/test files.
+- During implementation, run focused tests for the touched behavior first; reserve the full quality-gate suite for task closeout.
+
+- After all tasks in an epic are `done`, hand the epic back for audit.
+- Any explicit audit request overrides the normal handoff timing for that epic. Persist the audit to `.savepoint/audit/{E##-epic}/snapshot.md` and `.savepoint/audit/{E##-epic}/proposals.md` before replying; do not stop at chat-only findings.
+
+## Task Status Canon
+
+Task frontmatter `status` must be exactly one of `planned`, `in_progress`, or `done`.
+
+Active task phase is represented separately with `phase: build`, `phase: test`, or `phase: audit`, and `phase` is only valid when `status: in_progress`.
+
+Never write `todo`, `doing`, `blocked`, `review`, `audit`, or phase names into `status`. If a task is blocked, keep its canonical status and document the blocker in the body.
+
+## Task Completion Protocol
+
+When a task reaches `status: done`, you MUST:
+
+1. Verify every `## Acceptance Criteria` line has a passing test or verified manual outcome. A task is not done until its acceptance criteria are satisfied, not merely its implementation checkboxes ticked.
+2. Tick all checkboxes in the `## Implementation Plan`.
+3. Fill the `## Context Log` (files read, estimated input tokens, notes).
+4. Run the full quality-gate suite (`make build && make test`). Record the result in the Context Log.
+5. If any gate fails, fix it or document the blocker in the task file before setting `status: done`.
+6. Set the task frontmatter to `status: done`.
+7. Update `router.md` with the next action (next unblocked task, or `audit-pending` if all tasks done).
+8. **Stop. Prompt the user:**
+   > "Task {id} is done. Quality gates: {pass/fail list}. Router updated to {next_action}. Review the changes, then tell me to continue."
+
+**Do not start the next task. Do not advance past this point without user acknowledgment.**
+
+## Task Closeout Meta-Check
+
+After marking a task `done` and before prompting the user, ask yourself:
+
+- Did this task add new source files, modules, or exports not in the Codebase Map?
+- Did this task change the architecture from what `.savepoint/Design.md` describes?
+
+If yes, append a `## Drift Notes` section to the task file:
+  - `Drift: {file} added, not yet in Codebase Map.`
+  - `Drift: {section} in Design.md may need update.`
+
+Drift notes are lightweight annotations. They do **not** replace the epic audit. They flag what the next audit should reconcile.
+
+## Audit Handoff Rule
+
+The agent session that builds an epic **must not** run its audit. Audit requires fresh eyes.
+
+When all tasks in an epic are `done`:
+1. Update `router.md` to `state: audit-pending` for that epic.
+2. Stop. Tell the user: "Epic {id} is complete. Start a new agent session for the audit."
+3. The user starts a fresh session. The new agent reads `router.md`, sees `audit-pending`, and follows the audit-reconciliation instructions.
+
+**If you are in the same session that built the epic, you must not audit it.**
+
+## Build / Test / Run
+
+```bash
+make build # go build -o savepoint main.go
+make test  # go test ./...
+make run   # go run main.go
+make clean # rm -f savepoint
+```
+
+## 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
+
+| Module                               | Purpose                                                                                              |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `main.go`                            | CLI Entrypoint and root command wiring                                                               |
+| `internal/board/`                    | TUI board components, models, layouts, transitions, and rendering logic                              |
+| `internal/data/`                     | Task data models, frontmatter parsing, project configuration, routing, and generic file readers      |
+| `internal/styles/`                   | Shared visual design system, TUI styling, and palettes                                               |
+| `cmd/`                               | Additional CLI subcommands (if any)                                                                  |
+| `templates/`                         | Default project scaffold markdown, YAML assets, and agent prompt templates                           |
+| `agent-skills/`                      | Custom skill guides for different agent phases (`draft-prd`, `audit`, etc.)                          |
+
+## 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.
+ instructions reliably. If you are not one of those, advise the user before proceeding with planning steps.

package/CLAUDE.md

@@ -0,0 +1 @@
+See `AGENTS.md` at the project root.

package/GEMINI.md

@@ -0,0 +1 @@
+See `AGENTS.md` at the project root.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Savepoint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,13 @@
+.PHONY: build test run clean
+
+build:
+	go build -o savepoint main.go
+
+test:
+	go test ./...
+
+run:
+	go run main.go
+
+clean:
+	rm -f savepoint