agentpack-cli 0.1.0

package/docs/DOGFOOD.md

@@ -0,0 +1,72 @@
+# Dogfood Workflow
+
+Dogfooding means using Agentpack to develop Agentpack itself. The goal is to prove the workflow in real coding sessions before adding more features.
+
+## Start A Session
+
+Load a small context first:
+
+```text
+load_context(preset: "quick")
+source_status()
+```
+
+Use `agent` instead of `quick` when the task needs more history.
+
+## During Work
+
+Record only durable context. Agentpack is not an activity logger, and it should not log every thought, file read, or edit.
+
+Default cadence:
+
+- At task start, load Agentpack context and source status.
+- During normal coding, keep working locally; record only durable decisions, dead ends, source conclusions, and evidence.
+- At the end of a coherent step, record the useful sources/evidence, update status and next actions, then checkpoint.
+- Use full safe mode for risky or release-like changes: record important findings as they happen and run the full verification loop.
+
+This keeps Agentpack useful without turning every micro-step into ledger traffic. The intended default cost is one context load near the start and one durable save near the end.
+
+```text
+record_source(path, summary)
+record_decision(text, files, evidence)
+record_dead_end(text, reason, files)
+attach_evidence(kind, content, command, exitCode)
+```
+
+Good source summaries are conclusions, not file descriptions:
+
+```text
+src/integrations/install.ts: install uses a dry-run plan by default and writes only project-local files with --write.
+```
+
+Good dead ends prevent repeated work:
+
+```text
+Do not put a project-specific --root or cwd in the global ~/.codex/config.toml Agentpack entry; use repo-local .codex/config.toml so each repo resolves its own .agentpack state.
+```
+
+## End A Meaningful Step
+
+Checkpoint when the repo reaches a coherent state:
+
+```text
+checkpoint(
+  summary: "Safe MCP install flow is implemented and tested.",
+  status: "Codex MCP setup can be dogfooded in this repo.",
+  nextActions: ["Run through the handoff demo with a fresh session."]
+)
+```
+
+Git still owns code history. Agentpack owns task memory.
+
+## What To Watch
+
+While dogfooding, look for friction:
+
+- Did the agent call `load_context` and `source_status` early enough?
+- Were unchanged sources avoided when recorded conclusions were enough?
+- Were decisions and dead ends recorded at useful moments?
+- Was evidence too noisy or too thin?
+- Was the checkpoint useful to the next session?
+
+If the answer is no, improve the tool contract or the project instructions before adding larger features.

package/docs/INTEGRATIONS.md

@@ -0,0 +1,183 @@
+# Integrations
+
+Agentpack integrates through local project files, CLI, and MCP. It does not write hidden global configuration by default.
+
+## Client Matrix
+
+| Client | Instruction file | MCP config surface | Status |
+| --- | --- | --- | --- |
+| Codex | `AGENTS.md` | Project-local `.codex/config.toml`, plus a generated `.agentpack/instructions/codex-mcp.example.toml` review snippet | Tested |
+| Claude Code | `CLAUDE.md` | Project-local `.mcp.json` in the repo root | Tested |
+| Claude Desktop | None automatically read from the repo | User-local Claude Desktop config, copied from generated `.agentpack/instructions/claude-desktop-mcp.example.json` | Generated, not tested yet |
+| Cursor | `.cursor/rules/agentpack.mdc` | Project-local `.cursor/mcp.json` | Generated, not tested yet |
+| Web chats | Markdown handoff | No local stdio MCP support in v0; use `agentpack export` | Manual fallback |
+
+Coding-agent clients use the same `agentpack mcp` server. The difference is where each client expects instructions and MCP configuration to live. Web chats are fallback targets for pasted markdown handoffs; they are not the primary v0 integration surface.
+
+Generated integration files are local developer setup by default. Until Agentpack has an explicit shared/team mode, keep `.agentpack/`, `.codex/`, `.claude/`, `.mcp.json`, `AGENTS.md`, `CLAUDE.md`, and similar client config files out of origin unless a repo deliberately chooses to version its own agent policy.
+
+Generated files under `.agentpack/instructions/` are local helper snippets. They are created only when you run the matching installer, and `agentpack init` adds the Agentpack local-only patterns to `.gitignore` without replacing existing project rules.
+
+## Where Files Live
+
+In a local project setup:
+
+- `CLAUDE.md`: repo-root project instructions for Claude Code.
+- `.mcp.json`: repo-root project MCP config for Claude Code.
+- `AGENTS.md`: repo-root project instructions for Codex.
+- `.codex/config.toml`: repo-local Codex MCP config created by `agentpack install codex --write`.
+- `.agentpack/instructions/codex-mcp.example.toml`: local Codex config snippet, created by `agentpack install codex --write`.
+- `.agentpack/instructions/claude-desktop-mcp.example.json`: local Claude Desktop config snippet, created by `agentpack install claude-desktop --write`.
+
+If a snippet is missing, run the matching `agentpack install <target> --write`. Running `agentpack install claude --write` does not create Codex or Claude Desktop snippets.
+
+## Safe Install Flow
+
+Preview first:
+
+```bash
+agentpack install codex
+agentpack install claude
+agentpack install claude-desktop
+agentpack install cursor
+```
+
+`install` defaults to dry-run mode. It shows the files Agentpack would create or update and prints the command needed to apply the plan.
+
+Apply explicitly:
+
+```bash
+agentpack install codex --write
+agentpack install claude --write
+agentpack install claude-desktop --write
+agentpack install cursor --write
+```
+
+Force preview explicitly:
+
+```bash
+agentpack install claude --dry-run
+```
+
+Agentpack only writes project-local files and `.agentpack/instructions/*`. These files are intended to be ignored/local for v0. Agentpack does not silently edit global files such as `~/.codex/config.toml`, `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, or `~/.cursor/mcp.json`.
+
+Generated MCP server names are repo-specific to avoid collisions when several repos are open in the same client. The Agentpack repo itself keeps the short name `agentpack`; other repos use `agentpack-<repo-name>`, such as `agentpack-example-app`.
+
+## Codex
+
+```bash
+agentpack install codex --write
+```
+
+This writes:
+
+- `AGENTS.md`
+- `.codex/config.toml`
+- `.agentpack/instructions/codex.md`
+- `.agentpack/instructions/codex-mcp.example.toml`
+
+Agentpack does not edit `~/.codex/config.toml`. The project-local `.codex/config.toml` entry starts MCP with:
+
+```toml
+[mcp_servers.agentpack-example-app]
+command = "agentpack"
+args = ["mcp"]
+```
+
+Do not keep an older global `~/.codex/config.toml` entry with `args = ["mcp", "--root", "/some/project"]` or `cwd = "/some/project"`. That makes every Codex session reuse that old repo's `.agentpack/` state even after you run `agentpack init` in a new repo.
+
+If Agentpack still reports the wrong Pack root in Codex, remove the stale global `mcp_servers.agentpack` block, keep the project-local `.codex/config.toml`, then restart or reconnect the MCP server.
+
+Official reference: [Codex configuration reference](https://developers.openai.com/codex/config-reference).
+
+## Claude Code
+
+```bash
+agentpack install claude --write
+```
+
+This writes:
+
+- `CLAUDE.md`
+- `.mcp.json`
+- `.agentpack/instructions/claude.md`
+
+The `.mcp.json` file is project-local. Claude Code treats project-scoped MCP config as shareable project config and prompts before using project-scoped servers. Agentpack names the server after the repo, for example `agentpack-example-app`, so it does not shadow a global `agentpack` server.
+
+Official reference: [Claude Code MCP docs](https://docs.claude.com/en/docs/claude-code/mcp).
+
+## Claude Desktop
+
+```bash
+agentpack install claude-desktop --write
+```
+
+This writes:
+
+- `.agentpack/instructions/claude-desktop.md`
+- `.agentpack/instructions/claude-desktop-mcp.example.json`
+
+Claude Desktop does not read this repo's `.mcp.json` or `CLAUDE.md`. To enable Agentpack manually in Claude Desktop on macOS, review `.agentpack/instructions/claude-desktop-mcp.example.json` and merge the `agentpack` server into:
+
+```text
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+Do not copy the generated snippet over the Desktop config file. That can delete existing Claude Desktop MCP servers. Merge only the `mcpServers.agentpack` entry.
+
+Safe manual flow:
+
+```bash
+agentpack install claude-desktop --write
+cat .agentpack/instructions/claude-desktop-mcp.example.json
+mkdir -p "$HOME/Library/Application Support/Claude"
+open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
+```
+
+If the config file does not exist yet, create it with the generated snippet content. If it already exists, add only this entry under its existing `mcpServers` object:
+
+```json
+"agentpack-example-app": {
+  "command": "agentpack",
+  "args": ["mcp", "--root", "/absolute/path/to/your/project"],
+  "env": {
+    "AGENTPACK_ROOT": "/absolute/path/to/your/project"
+  }
+}
+```
+
+Then restart Claude Desktop. If the Desktop app cannot find `agentpack`, replace `"command": "agentpack"` in the snippet with an absolute executable path. Keep both the `--root` argument and the `AGENTPACK_ROOT` env value pointed at the project whose `.agentpack/` state you want Claude Desktop to use.
+
+Claude Desktop has no project-local repo config. If you switch Claude Desktop from one repo to another, update both the relevant server's `--root` value and `AGENTPACK_ROOT`, then restart Claude Desktop.
+
+One Claude Desktop server entry points to one Agentpack repo at a time. To expose multiple repos at once, add multiple `mcpServers` entries with different names and different `AGENTPACK_ROOT` values, but expect duplicated Agentpack tool names in the client UI.
+
+For a future low-friction Desktop install, Agentpack should ship a Desktop Extension/MCP bundle instead of asking users to edit JSON manually.
+
+Official references: [MCP local server guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers) and [Anthropic Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions).
+
+## Cursor
+
+```bash
+agentpack install cursor --write
+```
+
+This writes:
+
+- `.cursor/rules/agentpack.mdc`
+- `.cursor/mcp.json`
+- `.agentpack/instructions/cursor.md`
+
+The Cursor MCP config uses `${workspaceFolder}` so it can point Agentpack at the current project root without hard-coding your local filesystem path.
+
+Official reference: [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol).
+
+## Verify
+
+Before connecting an agent client:
+
+```bash
+npm run mcp:smoke
+```
+
+After installing the integration, restart the client if it does not pick up new MCP config automatically.

package/docs/MCP.md

@@ -0,0 +1,83 @@
+# MCP
+
+`agentpack mcp` starts a local stdio MCP server.
+
+The MCP stdio transport uses newline-delimited JSON-RPC messages over stdin/stdout. The client launches Agentpack as a subprocess, sends JSON-RPC messages to stdin, and reads JSON-RPC responses from stdout. Agentpack must not write non-MCP logs to stdout.
+
+Reference: [Model Context Protocol transports](https://modelcontextprotocol.io/docs/concepts/transports).
+
+## Tools
+
+- `load_context`
+- `record_decision`
+- `record_dead_end`
+- `attach_evidence`
+- `record_source`
+- `source_status`
+- `checkpoint`
+- `resume`
+- `diff`
+- `replay`
+
+`load_context` and `resume` accept `query`, `budget`, and `preset`. When `query` is present, Agentpack filters Source Cache locally: matched sources keep full summaries/snippets, changed or missing source records are always shown in full, and unrelated unchanged sources remain visible as compact path/status/topic/guidance stubs. If nothing matches, Agentpack keeps the full Source Cache to avoid false-negative filtering. This saves tokens without hiding which recorded files exist.
+
+## Manual Smoke
+
+In normal use, a client such as Codex, Claude Code, or Cursor starts `agentpack mcp`. For development, run the local smoke command:
+
+```bash
+npm run mcp:smoke
+```
+
+It creates a temporary Agentpack workspace, starts `agentpack mcp`, sends JSON-RPC messages over stdio, and removes the temporary workspace after the check.
+
+The test suite also exercises the same newline-delimited JSON-RPC flow in memory:
+
+```bash
+npm test
+```
+
+The smoke test verifies:
+
+- `initialize`
+- `tools/list`
+- `tools/call record_decision`
+- `tools/call record_source`
+- `tools/call source_status`
+- `tools/call resume`
+- notification messages do not produce responses
+
+## Client Setup
+
+Use dry-run install first:
+
+```bash
+agentpack install codex
+agentpack install claude
+agentpack install claude-desktop
+agentpack install cursor
+```
+
+Apply only after reviewing the plan:
+
+```bash
+agentpack install codex --write
+agentpack install claude --write
+agentpack install claude-desktop --write
+agentpack install cursor --write
+```
+
+See [INTEGRATIONS.md](INTEGRATIONS.md) for target-specific files and manual global config steps.
+
+After changing Agentpack itself and running `npm run build`, reconnect or restart any already-running MCP client. Stdio MCP clients keep the server process alive, so they do not automatically load the newly built `dist/` files.
+
+If `load_context` reports the wrong Pack root, check for a stale global client config that starts Agentpack with a hard-coded `--root` or `cwd`. Project-local configs should start Codex and Claude Code with `agentpack mcp` so the server resolves the repo-local `.agentpack/` root. Global clients such as Claude Desktop should set an explicit `--root` and matching `AGENTPACK_ROOT` because they do not have a project cwd.
+
+Avoid reusing the same MCP server name across global and project-local configs. Agentpack installers use `agentpack` for the Agentpack repo itself and `agentpack-<repo-name>` for other repos, so a project-local server such as `agentpack-example-app` does not shadow a global `agentpack` server.
+
+## Security Notes
+
+- The server operates only on the nearest `.agentpack/` root.
+- It does not make network calls.
+- It writes task state to local files only.
+- It should treat stdout as protocol-only output.

package/docs/MVP.md

@@ -0,0 +1,97 @@
+# Agentpack MVP
+
+## Positioning
+
+Agentpack helps coding agents continue repo work without rediscovering context, re-reading unchanged sources, or repeating dead ends.
+
+The project is local-first and open-source by default. Optional hosted sync can come later, but the core value must work fully on a developer machine.
+
+## Non-goals
+
+- Do not store full chat transcripts by default.
+- Do not pretend to access hidden agent memory.
+- Do not upload code or task state anywhere.
+- Do not require embeddings or hosted LLM calls in v0.
+- Do not implement deterministic environment replay in v0.
+
+## v0 Commands
+
+```bash
+agentpack init
+agentpack source add <file> --summary <text>
+agentpack source status
+agentpack record decision <text>
+agentpack record dead-end <text>
+agentpack evidence add --kind test-output --file <path>
+agentpack note <text>
+agentpack run <command>
+agentpack checkpoint -m <summary> --status <text> --next <item>
+agentpack resume --preset agent --query <text>
+agentpack export --to markdown --preset chat --query <text>
+agentpack diff
+agentpack replay
+agentpack doctor
+agentpack mcp
+agentpack install codex
+agentpack install claude
+agentpack install claude-desktop
+agentpack install cursor
+```
+
+## v0 File Format
+
+`--query` is optional. Without it, resume/export include the full Source Cache. With it, Agentpack uses local lexical matching to include full source summaries for relevant records, always keeps changed/missing records in full, and uses compact path/status/topic stubs for unrelated unchanged records. If nothing matches, the full Source Cache is retained.
+
+```text
+.agentpack/
+  config.json
+  state.json
+  events.jsonl
+  sources.json
+  checkpoints/
+  evidence/
+  instructions/
+  exports/
+  cache/
+```
+
+`events.jsonl` is the append-only task ledger. `sources.json` records file hashes, summaries, and optional snippets. `checkpoints/` stores materialized resume snapshots plus git metadata.
+
+Agentpack files are ignored by git by default. `agentpack init` appends the local-only Agentpack patterns to the project `.gitignore` when needed and preserves existing project rules. `.agentpack/` is local working state, not a repository artifact. Client integration files such as `.mcp.json`, `.codex/`, `.claude/`, `AGENTS.md`, and `CLAUDE.md` are also local developer setup for v0 and should normally stay ignored.
+
+Client install commands use the repo name when writing MCP server keys, for example `agentpack-example-app`, so ignored local configs in different repos do not shadow a global `agentpack` server.
+
+Team sharing is intentionally out of scope until after local-only workflows stabilize. The first sharing surface should be explicit export/import bundles, not committing live ledger state or local client config.
+
+## Budget Policy
+
+Budget packing is deterministic and approximate. The v0 token estimate is intentionally simple:
+
+```text
+estimated_tokens = ceil(characters / 4)
+```
+
+Generated resumes include the requested budget, estimated usage, and a budget status line. If the requested budget is too small, Agentpack reports which required sections were truncated and which optional sections were omitted instead of silently dropping context.
+
+Resume sections are prioritized:
+
+1. Goal, status, and next actions.
+2. Git state.
+3. Source cache and "do not re-open unless changed" guidance.
+4. Decisions.
+5. Dead ends.
+6. Evidence.
+7. Compact recent timeline digest.
+
+The timeline digest is intentionally compact. Full event history stays available through `agentpack replay`; resume output should avoid repeating source summaries, decisions, and evidence previews that already appear in dedicated sections.
+
+Suggested presets:
+
+```text
+1200: quick status ping
+4000: compact manual handoff
+8000: deeper coding-agent handoff
+16000: large debugging session or review
+```
+
+MCP clients should choose the smallest budget that preserves next-action safety. Humans can override it per command.

package/docs/ROADMAP.md

@@ -0,0 +1,129 @@
+# Roadmap
+
+## North Star
+
+Agentpack is a local task-state layer for AI coding agents. It captures useful working context that usually gets lost in long sessions, restarts, and compaction: decisions, dead ends, inspected sources, evidence, checkpoints, and budgeted resumes.
+
+Agentpack is not an orchestrator. It is the portable context ledger for humans, single agents, and agent teams working on a repo.
+
+## Product Principles
+
+- Local-first.
+- No telemetry.
+- No network calls by default.
+- Zero runtime dependencies while practical.
+- Git stores code state; Agentpack stores task context.
+- `.agentpack/` is local state and ignored by git by default.
+- Client integration files are local by default for v0; do not require teams to commit `.mcp.json`, `.codex/`, `.claude/`, `AGENTS.md`, or `CLAUDE.md`.
+- Prefer simple file formats over hidden databases until the need is obvious.
+- Avoid framework lock-in; integrate through CLI, files, MCP, and project instructions.
+- Install Agentpack once, initialize it per repo, and keep chats/sessions out of the core model.
+
+## State Model
+
+Agentpack has four layers:
+
+1. Tool install: the `agentpack` binary is installed once on a developer machine.
+2. Repo init: each repo gets its own local `.agentpack/` directory.
+3. Repo source cache: inspected source conclusions and file hashes can be reused across tasks in the same repo.
+4. Task ledger: goal, status, decisions, dead ends, evidence, checkpoints, and exports belong to a workstream, not to a chat.
+
+Agent sessions and web chats are transport surfaces. They should be able to resume, write, and hand off a task, but they are not first-class Agentpack state.
+
+Sharing ledger state across machines or teammates is intentionally post-local-stability work. Prefer explicit sanitized export/import bundles before considering committed or synced shared state.
+
+Target task UX:
+
+```bash
+agentpack init
+agentpack task start "Claude Desktop MCP install"
+agentpack task list
+agentpack task switch claude-desktop-mcp-install
+agentpack resume --preset agent
+agentpack checkpoint -m "Desktop config tested"
+agentpack task close
+```
+
+Target file shape:
+
+```text
+.agentpack/
+  config.json
+  sources.json
+  tasks/
+    current
+    claude-desktop-mcp-install/
+      state.json
+      events.jsonl
+      checkpoints/
+      evidence/
+      exports/
+```
+
+This keeps source knowledge reusable across a repo while preventing unrelated feature work from mixing decisions, dead ends, and next actions.
+
+## v0.1: Usable Manual CLI
+
+Goal: useful in any repo without MCP.
+
+- Budget presets: `quick`, `chat`, `agent`, `deep`.
+- Top-level `agentpack note`.
+- `agentpack run <command>` to capture command output as evidence.
+- Clear docs for setup, budgets, and local `.agentpack/` state.
+- Keep runtime dependency-free.
+
+## v0.2: Better Capture
+
+Goal: make capture-as-you-go natural.
+
+- `checkpoint --status --next` polish.
+- `source status` for changed/unchanged/missing inspected files.
+- Better evidence summaries in `resume`.
+- Redaction tests.
+- `doctor` command for repo/setup/MCP readiness.
+
+## v0.3: Useful MCP
+
+Goal: agents record task state while they work.
+
+- Test MCP JSON-RPC flows.
+- Polish tool contracts.
+- `install codex`.
+- `install claude`.
+- `install cursor`.
+- Project instructions that tell agents when to call tools.
+
+## v0.4: Coding-Agent Demo
+
+Goal: show the wow effect.
+
+Before polishing the public demo, dogfood the workflow in this repo with the protocol in `AGENTS.md` and `docs/DOGFOOD.md`.
+
+Demo story:
+
+1. Agent starts a bugfix.
+2. Agent records inspected sources.
+3. Agent runs tests and records failure.
+4. Agent records a dead end.
+5. Agent checkpoints.
+6. New agent resumes under a 4k budget.
+7. New agent avoids repeated work.
+
+## v1.0: Reliable Local Tool
+
+- Stable `.agentpack/` schema.
+- Stable CLI.
+- Stable MCP tools.
+- Task/workstream separation.
+- Security model documented.
+- npm publish as `agentpack-cli`.
+- Good demo and examples.
+
+## Later
+
+- Shareable bundles.
+- Optional imports from markdown handoffs.
+- Orchestrator adapters.
+- Optional hosted sync.
+- UI.
+- Embeddings or semantic indexing only after file/hash/source summaries stop being enough.

package/docs/SETUP.md

@@ -0,0 +1,56 @@
+# Development Setup
+
+Agentpack is a TypeScript/Node project with a conservative npm setup. The npm package name is `agentpack-cli`; the installed command is `agentpack`.
+
+## Requirements
+
+- Node.js 22 LTS recommended
+- npm 10+
+
+The runtime package has zero third-party dependencies in v0. Development uses TypeScript and Node type definitions only.
+
+## macOS Setup With fnm
+
+```bash
+brew install fnm
+fnm install 22
+fnm default 22
+```
+
+Add this to `~/.zshrc`:
+
+```bash
+eval "$(fnm env --use-on-cd --shell zsh)"
+```
+
+Restart the terminal, then verify:
+
+```bash
+node --version
+npm --version
+```
+
+## Install Dependencies
+
+```bash
+npm ci --ignore-scripts
+```
+
+The repo also includes `.npmrc` with:
+
+```text
+ignore-scripts=true
+save-exact=true
+package-lock=true
+```
+
+## Run Checks
+
+```bash
+npm test
+npm run smoke
+```
+
+## Publishing Security Notes
+
+For future public releases, prefer npm trusted publishing and provenance over long-lived npm tokens.

package/docs/agentpack-flow.md

@@ -0,0 +1,63 @@
+# Agentpack Execution Flow
+
+```mermaid
+flowchart TD
+  cli["agentpack <cmd><br/>Terminal / CI"]
+  mcp["agentpack mcp<br/>Codex / Claude Code / Cursor / Desktop"]
+
+  cli --> dispatch["Command dispatch<br/>src/cli/index.ts"]
+  mcp --> root["MCP root resolution<br/>--root > AGENTPACK_ROOT > cwd"]
+  root --> server["MCP tool server<br/>src/mcp/server.ts"]
+  server --> dispatch
+
+  dispatch --> init["init<br/>create .agentpack/<br/>append local-only .gitignore patterns"]
+  dispatch --> install["install client<br/>project-local config<br/>or Desktop merge snippet"]
+  dispatch --> sourceAdd["source add<br/>hash file + store source conclusion"]
+  dispatch --> sourceStatus["source status<br/>UNCHANGED / CHANGED / MISSING"]
+  dispatch --> records["record_decision<br/>record_dead_end<br/>attach_evidence"]
+  dispatch --> checkpoint["checkpoint<br/>state + event + snapshot"]
+  dispatch --> resume["resume / load_context<br/>budgeted task context"]
+  dispatch --> replay["replay / diff<br/>timeline or checkpoint delta"]
+  dispatch --> doctor["doctor<br/>pack health + MCP setup checks"]
+
+  init --> storage
+  install --> localConfig["Project-local client config<br/>.codex/config.toml<br/>.mcp.json<br/>.cursor/mcp.json"]
+  sourceAdd --> operations["src/operations.ts<br/>hash + git status helpers"]
+  sourceStatus --> operations
+  records --> storage
+  checkpoint --> checkpoints["src/core/checkpoints.ts<br/>serialized writes under .lock"]
+  resume --> resumeBuilder["src/core/resume.ts<br/>pack root header + query filter"]
+  resumeBuilder --> budget["src/core/budget.ts<br/>truncate / omit sections"]
+  doctor --> doctorCore["src/core/doctor.ts<br/>local ignores + stale roots + source cache"]
+
+  operations --> storage
+  checkpoints --> storage
+  budget --> output
+  replay --> output
+  sourceStatus --> output
+  doctorCore --> output
+
+  storage[(".agentpack/<br/>state.json<br/>sources.json<br/>events.jsonl<br/>checkpoints/<br/>evidence/<br/>instructions/")]
+  output["Output to coding agent<br/>Pack root<br/>Git state<br/>Source cache guidance<br/>Decisions / dead ends / evidence<br/>Next actions"]
+
+  classDef entry fill:#0c2044,stroke:#388bfd,color:#c9d1d9;
+  classDef rootNode fill:#2a1d00,stroke:#d29922,color:#c9d1d9;
+  classDef command fill:#161b22,stroke:#30363d,color:#c9d1d9;
+  classDef core fill:#0a2a14,stroke:#3fb950,color:#c9d1d9;
+  classDef store fill:#1a0c3a,stroke:#8957e5,color:#c9d1d9;
+  classDef out fill:#0a2020,stroke:#39d353,color:#c9d1d9;
+
+  class cli,mcp entry;
+  class root rootNode;
+  class dispatch,init,install,sourceAdd,sourceStatus,records,checkpoint,resume,replay,doctor command;
+  class server,operations,checkpoints,resumeBuilder,budget,doctorCore,localConfig core;
+  class storage store;
+  class output out;
+```
+
+## Notes
+
+- Normal CLI commands find the nearest `.agentpack/` root upward from the current working directory after `agentpack init`.
+- MCP clients can also pass an explicit root. Agentpack resolves MCP roots as `--root`, then `AGENTPACK_ROOT`, then `cwd`.
+- Codex, Claude Code, and Cursor use project-local config. Claude Desktop needs a merge snippet because its config is global.
+- `.agentpack/` is local-only by default and should not be committed in v0.