dig-burrow 1.2.0

package/.claude/burrow/workflows/burrow.md

@@ -0,0 +1,184 @@
+# Burrow Workflow
+
+Burrow is an infinitely nestable card tool. You interpret natural language, call CLI operations, and present results.
+
+CLI path: `node .claude/burrow/burrow-tools.cjs`
+
+## Invariants (NEVER violate)
+
+1. **Never remove without confirmation** -- Always ask "Remove 'X' and its N children?" before running remove.
+2. **Never modify data without explicit user request** -- Read operations are safe; write operations require clear user intent.
+3. **Always clarify ambiguous card references** -- If a title matches multiple cards, list them and ask which one.
+4. **Never repeat tool output** -- The Bash tool output is already visible to the user. NEVER echo, repeat, or reformat it as text. After a read-only CLI call, say nothing.
+5. **Never show raw JSON unless the user asks for it** -- The Read tool is used for internal data loading. Never output JSON to the user.
+
+## The 3-Step Flow
+
+Every `/burrow` invocation follows this sequence. No exceptions.
+
+### Step 1: LOAD (silent)
+
+Read `cards.json` directly using the Read tool to load the tree into agent memory. The Read tool output is invisible to the user, making this truly silent.
+
+- **Skip if already loaded**: If the agent has already read `cards.json` in this conversation and no mutation has occurred since, skip this step.
+- **Read on first use or after mutation**: `.planning/burrow/cards.json` using the Read tool (NOT the CLI).
+- **Card ID detection**: An 8-character hex string at the start of user arguments (e.g., `a1b2c3d4`).
+- **NEVER use Bash/CLI for loading.** Bash output is visible to the user. The Read tool is not.
+- **JSON structure**: The file contains an array of card objects. Each card has `id`, `title`, `children` (nested array), and optional `body`, `createdAt`, `archived`.
+
+### Step 2: THINK
+
+Using the loaded tree, interpret the user's request.
+
+- **No request** (`/burrow` or `/burrow <id>`): Intent is "show this view."
+- **Natural language request**: Resolve card references by matching titles against the in-memory tree.
+- **Ambiguous references**: List matches with IDs and parent context, ask which one.
+- **Missing card references**: Offer to create it.
+- **Questions/analysis** (counting, filtering, searching): Answer directly from the in-memory tree. No CLI call needed — the agent already has the data.
+
+### Step 3: EXECUTE
+
+Perform the action.
+
+- **For views**: Run `read [id]` (pretty-print). Say nothing after — the output is the presentation.
+- **For mutations** (add, edit, remove, move, archive, unarchive): Run the CLI command, then one-line confirmation. After mutation, re-LOAD by reading `cards.json` with the Read tool to sync agent memory.
+- **For questions/analysis**: Respond with the answer directly. No CLI call needed.
+- **For multi-step operations**: Run all mutations in a single Bash call by chaining with `&&`, summarize changes in plain English, then run one `read` to show end state.
+- **For bulk operations**: Confirm before executing. Example: "This will archive 5 cards under 'bugs'. Proceed?"
+
+## Command Reference
+
+All commands invoked as: `node .claude/burrow/burrow-tools.cjs <command> [args]`
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| read | `read [id] [--depth N] [--full] [--include-archived] [--archived-only]` | View a card. Default depth 1. |
+| add | `add --title "..." [--parent <id>] [--body "..."] [--at N]` | Create a card. --at N places at 0-based position. |
+| edit | `edit <id> [--title "..."] [--body "..."]` | Modify a card. |
+| remove | `remove <id>` | Remove card and all descendants. Requires confirmation. |
+| move | `move <id> --to <parent-id> [--at N]` | Move card. --at N places at 0-based position. Omit --to to reorder within current parent. |
+| archive | `archive <id>` | Archive card and descendants. |
+| unarchive | `unarchive <id>` | Restore card and descendants. |
+| find | `find <query>` | Fuzzy search cards by title. Returns IDs and paths. |
+| dump | `dump` | Alias for `read --depth 0` (full tree). |
+| path | `path <id>` | Show ancestry from root to card. |
+
+## Position Translation
+
+The --at flag uses 0-based indexing. When users reference positions in natural language,
+translate to 0-based index before constructing the CLI command.
+
+| User says | --at value | Rule |
+|-----------|------------|------|
+| "first", "top", "beginning" | --at 0 | Always 0 |
+| "second" | --at 1 | Ordinal minus 1 |
+| "third" | --at 2 | Ordinal minus 1 |
+| "position N" / "slot N" | --at (N-1) | Human position minus 1 |
+| "last", "end", "bottom" | omit --at | Default append behavior |
+| "before card X" | --at (index of X) | Look up X's current index |
+| "after card X" | --at (index of X + 1) | Look up X's current index, add 1 |
+
+The agent resolves positions during THINK (Step 2) by inspecting the in-memory tree
+to find the target container's children array and computing the correct index.
+
+## Rendering Rules
+
+- The Bash tool output is already visible to the user. NEVER repeat or re-output CLI results as text. The tool call IS the presentation.
+- After a CLI call, say nothing unless there's something the user needs to act on. Do not echo, summarize, or reformat the output.
+- For read-only operations (read, dump, path): run the CLI command and stop. No text output after.
+- For mutations (add, edit, remove, move, archive, unarchive): run the CLI command, then optionally add a one-line confirmation like "Added 'X' under Y." — but NEVER repeat the tree output.
+- For multi-step operations: write a plain English summary of changes, then run one `read` command to show the end state.
+- Default depth is 1 (card + direct children).
+
+## Transparency
+
+When showing what command will be run, use the format: "Running: `burrow <command> <args>`"
+
+## Tone and Style
+
+Functional and terse. No personality, no burrow metaphors, no excessive commentary.
+
+- Good: "Added 'OAuth bug' under Bugs."
+- Bad: "I've successfully created a new card titled 'OAuth bug' and placed it under the Bugs section for you!"
+
+## Worked Examples
+
+### Example 1: Simple view (no args)
+
+**User:** `/burrow`
+
+**Agent behavior:**
+1. LOAD: Read `.planning/burrow/cards.json` using the Read tool (silent).
+2. THINK: No request — intent is "show root view."
+3. EXECUTE: Run `node .claude/burrow/burrow-tools.cjs read`. Stop.
+
+### Example 2: Scoped view
+
+**User:** `/burrow a1b2c3d4`
+
+**Agent behavior:**
+1. LOAD: Read `.planning/burrow/cards.json` using the Read tool (silent).
+2. THINK: No request — intent is "show this card."
+3. EXECUTE: Run `node .claude/burrow/burrow-tools.cjs read a1b2c3d4`. Stop.
+
+### Example 3: Question answered from memory
+
+**User:** `/burrow how many cards have the letter K in the title?`
+
+**Agent behavior:**
+1. LOAD: Read `.planning/burrow/cards.json` using the Read tool (silent).
+2. THINK: Scan in-memory tree for titles containing "K" or "k". Count: 7.
+3. EXECUTE: Respond with the answer directly. No CLI call needed.
+
+### Example 4: Scoped question
+
+**User:** `/burrow a1b2c3d4 how many children does this have?`
+
+**Agent behavior:**
+1. LOAD: Read `.planning/burrow/cards.json` using the Read tool (silent).
+2. THINK: Count children in the loaded subtree.
+3. EXECUTE: Respond with the answer directly.
+
+### Example 5: Card creation
+
+**User:** `/burrow add a card called OAuth bug under bugs`
+
+**Agent behavior:**
+1. LOAD: Read `.planning/burrow/cards.json` using the Read tool (silent).
+2. THINK: Match "bugs" → `a1b2c3d4` "Bugs".
+3. EXECUTE: Run `node .claude/burrow/burrow-tools.cjs add --title "OAuth bug" --parent a1b2c3d4`. Then re-LOAD by reading `cards.json` with the Read tool.
+
+### Example 6: Multi-step operation
+
+**User:** `/burrow move all the auth cards under security`
+
+**Agent behavior:**
+1. LOAD: Read `.planning/burrow/cards.json` using the Read tool (silent).
+2. THINK: Match "auth" — finds 3 cards. Match "security" → `f1f2f3f4`.
+3. Confirm: "This will move 3 cards (Login flow, OAuth integration, Session handling) under Security. Proceed?"
+4. User confirms.
+5. EXECUTE: Run each move command. Summarize: "Moved 3 cards under Security."
+6. Re-LOAD by reading `cards.json` with the Read tool. Run `read f1f2f3f4 --depth 2` to show end state.
+
+### Example 7: Ambiguity resolution
+
+**User:** `/burrow archive the login card`
+
+**Agent behavior:**
+1. LOAD: Read `.planning/burrow/cards.json` using the Read tool (silent).
+2. THINK: Match "login" — multiple matches:
+   - `a1a1a1a1` Login page (Frontend)
+   - `b2b2b2b2` Login bug (Bugs)
+   - `c3c3c3c3` Login flow (Auth)
+3. Ask: "Multiple cards match 'login'. Which one?" (list with IDs and parents)
+4. User selects "Login bug".
+5. EXECUTE: Run `node .claude/burrow/burrow-tools.cjs archive b2b2b2b2`. Stop.
+
+### Example 8: Position-based insertion
+
+**User:** `/burrow add "Urgent fix" under bugs, make it first`
+
+**Agent behavior:**
+1. LOAD: Read `.planning/burrow/cards.json` using the Read tool (silent).
+2. THINK: Match "bugs" -> `a1b2c3d4` "Bugs". "First" -> --at 0.
+3. EXECUTE: Run `node .claude/burrow/burrow-tools.cjs add --title "Urgent fix" --parent a1b2c3d4 --at 0`. Then re-LOAD.

package/.claude/commands/burrow/add.md

@@ -0,0 +1,12 @@
+---
+name: burrow:add
+description: Add a new card to burrow
+argument-hint: "--title \"card title\" [--parent <id>] [--body \"content\"]"
+allowed-tools:
+  - Bash
+---
+Add a card to burrow with the given flags.
+
+Run: `node .claude/burrow/burrow-tools.cjs add $ARGUMENTS`
+
+Do not repeat the CLI output — it is already visible to the user. Say nothing after read-only commands.

package/.claude/commands/burrow/archive.md

@@ -0,0 +1,12 @@
+---
+name: burrow:archive
+description: Archive a card and its descendants
+argument-hint: "<id>"
+allowed-tools:
+  - Bash
+---
+Archive a burrow card.
+
+Run: `node .claude/burrow/burrow-tools.cjs archive $ARGUMENTS`
+
+Do not repeat the CLI output — it is already visible to the user. Say nothing after read-only commands.

package/.claude/commands/burrow/dump.md

@@ -0,0 +1,12 @@
+---
+name: burrow:dump
+description: Show full tree at all depths
+argument-hint: ""
+allowed-tools:
+  - Bash
+---
+Dump the entire burrow tree.
+
+Run: `node .claude/burrow/burrow-tools.cjs dump`
+
+Do not repeat the CLI output — it is already visible to the user. Say nothing after read-only commands.

package/.claude/commands/burrow/edit.md

@@ -0,0 +1,12 @@
+---
+name: burrow:edit
+description: Edit a card's title or body
+argument-hint: "<id> [--title \"new title\"] [--body \"new body\"]"
+allowed-tools:
+  - Bash
+---
+Edit a burrow card with the given flags.
+
+Run: `node .claude/burrow/burrow-tools.cjs edit $ARGUMENTS`
+
+Do not repeat the CLI output — it is already visible to the user. Say nothing after read-only commands.

package/.claude/commands/burrow/help.md

@@ -0,0 +1,29 @@
+---
+name: burrow:help
+description: Show burrow command reference
+argument-hint: ""
+allowed-tools: []
+---
+Output the following command reference:
+
+## Burrow Commands
+
+| Command | Description |
+|---------|-------------|
+| `/burrow [request]` | Natural language -- describe what you want |
+| `/burrow:read [id] [--depth N]` | View cards (root at depth 1 if no args) |
+| `/burrow:add --title "..." [--parent id] [--body "..."]` | Add a card |
+| `/burrow:edit id [--title "..."] [--body "..."]` | Edit a card |
+| `/burrow:move id --to parent-id` | Move a card |
+| `/burrow:remove id` | Remove a card (with confirmation) |
+| `/burrow:archive id` | Archive a card |
+| `/burrow:unarchive id` | Restore an archived card |
+| `/burrow:dump` | Full tree view (all depths) |
+| `/burrow:help` | This reference |
+
+### Examples
+
+- `/burrow show me my bugs` -- natural language via `/burrow`
+- `/burrow:add --title "fix login" --parent a1b2c3d4` -- add under a specific card
+- `/burrow:read a1b2c3d4 --depth 2` -- view card with 2 levels of children
+- `/burrow:dump` -- see everything

package/.claude/commands/burrow/move.md

@@ -0,0 +1,12 @@
+---
+name: burrow:move
+description: Move a card to a different parent
+argument-hint: "<id> --to <parent-id> [--at N]"
+allowed-tools:
+  - Bash
+---
+Move a burrow card to a new parent.
+
+Run: `node .claude/burrow/burrow-tools.cjs move $ARGUMENTS`
+
+Do not repeat the CLI output — it is already visible to the user. Say nothing after read-only commands.

package/.claude/commands/burrow/read.md

@@ -0,0 +1,12 @@
+---
+name: burrow:read
+description: View cards in burrow
+argument-hint: "[<id>] [--depth N] [--full] [--include-archived] [--archived-only]"
+allowed-tools:
+  - Bash
+---
+Show burrow cards. With no arguments, shows root at depth 1.
+
+Run: `node .claude/burrow/burrow-tools.cjs read $ARGUMENTS`
+
+Do not repeat the CLI output — it is already visible to the user. Say nothing after read-only commands.

package/.claude/commands/burrow/remove.md

@@ -0,0 +1,12 @@
+---
+name: burrow:remove
+description: Delete a card and its descendants
+argument-hint: "<id>"
+allowed-tools:
+  - Bash
+---
+Ask the user to confirm before running the remove command. Show what will be removed by running `node .claude/burrow/burrow-tools.cjs read <id>` first.
+
+After confirmation, run: `node .claude/burrow/burrow-tools.cjs remove $ARGUMENTS`
+
+Do not repeat the CLI output — it is already visible to the user. Say nothing after read-only commands.

package/.claude/commands/burrow/unarchive.md

@@ -0,0 +1,12 @@
+---
+name: burrow:unarchive
+description: Restore an archived card and its descendants
+argument-hint: "<id>"
+allowed-tools:
+  - Bash
+---
+Unarchive a burrow card.
+
+Run: `node .claude/burrow/burrow-tools.cjs unarchive $ARGUMENTS`
+
+Do not repeat the CLI output — it is already visible to the user. Say nothing after read-only commands.

package/.claude/commands/burrow/update.md

@@ -0,0 +1,15 @@
+---
+name: burrow:update
+description: Update burrow to the latest version
+argument-hint: ""
+allowed-tools:
+  - Bash
+  - Read
+---
+Update burrow to the latest version from npm.
+
+Steps:
+1. Run: `npx create-burrow --yes`
+2. Report the result to the user.
+
+This fetches the latest published version of burrow from npm and runs the installer in non-interactive mode. Your existing cards.json data is always preserved during upgrades.

package/.claude/commands/burrow.md

@@ -0,0 +1,16 @@
+---
+name: burrow
+description: Interact with Burrow using natural language -- add, view, move, archive cards
+argument-hint: "[card-id] [natural language request]"
+allowed-tools:
+  - Bash
+  - Read
+---
+<execution_context>
+@./.claude/burrow/workflows/burrow.md
+</execution_context>
+
+<context>
+User request: $ARGUMENTS
+CLI path: node .claude/burrow/burrow-tools.cjs
+</context>

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrmatos
+
+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/README.md

@@ -0,0 +1,285 @@
+# Burrow
+
+There's a hole in the ground next to your project. Chuck any thought into it — it's stored before you finish the sentence. Need it back? Already there.
+
+Burrow is an infinitely nestable card store for [Claude Code](https://claude.ai/claude-code). Cards contain cards contain cards, as deep as you want. The agent navigates the whole thing so you never have to (unless you want to).
+
+> "throw a note on the OAuth issue — redirect is broken again"
+>
+> "move everything from backlog into sprint"
+>
+> "what's left under bugs? show me the details"
+
+You talk. The agent traverses, renders, and manipulates. One file, one source of truth, zero ceremony.
+
+## How it works
+
+One recursive data structure. That's it.
+
+```
+burrow › Mock
+
+────────────────────────────────────────
+Mock
+────────────────────────────────────────
+id:       2bdb294a
+created:  2026-03-08 (1d ago)
+archived: no
+────────────────────────────────────────
+children: 3 cards (14 total)
+  ├─ [82c35e2c] Backend Services (9)                                    1d ago
+  │   ├─ [8698f27b] Auth API (6) +                                      1d ago
+  │   │   ├─ [7d274551] Token Refresh Flow (3) +                        1d ago
+  │   │   └─ [a91b72bb] Rate Limiter (1)                                1d ago
+  │   └─ [1a763ccd] Data Pipeline (1)                                   1d ago
+  │       └─ [df36b887] ETL Jobs                                        1d ago
+  ├─ [4f42eb4e] Frontend App (6)                                        1d ago
+  │   ├─ [e044cc9f] Dashboard (4)                                       1d ago
+  │   │   ├─ [f7ee4392] Widget Grid +                                   1d ago
+  │   │   └─ [69f7e0d4] Charts (2)                                      1d ago
+  │   └─ [5a9daea7] Settings Page +                                     1d ago
+  └─ [cbe50a76] DevOps (2)                                              1d ago
+      └─ [c5b5131a] CI/CD (1)                                           1d ago
+          └─ [dd4fc5d8] GitHub Actions +
+────────────────────────────────────────
+body:
+  Demo data for showcasing nested tree rendering at various depths.
+────────────────────────────────────────
+```
+
+Every card has a title and a body. The body holds whatever you want — a description, repro steps, a decision rationale, agent instructions, bug details...
+
+But every card can also contain child cards, and every child can contain more children. There are no buckets, tags, categories, or priorities — the structure IS the organization. A "bug tracker" is just a card called "bugs" with children. A "shopping list" is another top-level card. You decide what the tree means.
+
+The agent picks the depth, the focus, and the rendering. You just ask.
+
+## Setup
+
+Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) already installed on your project.
+
+```bash
+git clone https://github.com/mrmatos6837/burrow.git
+node burrow/install.cjs ~/your-project
+```
+
+This copies the source and commands into your project, creates `.planning/burrow/cards.json`, and appends a Burrow section to your `CLAUDE.md` that tells the agent how to use burrow — reading it on session start, storing persistent instructions as cards, and routing all mutations through the CLI.
+
+That's it. Open Claude Code and say `/burrow` to get started.
+
+**What gets installed:**
+
+```
+.claude/burrow/                  # source code (lib/, CLI entry point)
+.claude/commands/burrow.md       # /burrow slash command
+.claude/commands/burrow/         # shortcut commands (/burrow:add, etc.)
+.planning/burrow/cards.json      # your data (commit this)
+CLAUDE.md                        # agent instructions (appended, not overwritten)
+```
+
+**Requirements:** Node.js v19+ — zero npm dependencies.
+
+## Usage
+
+Use `/burrow` with natural language:
+
+```
+/burrow add a login crash bug under auth — "happens after OAuth redirect"
+/burrow move everything from backlog into sprint
+/burrow archive all the v1 stuff, it shipped
+/burrow show me what's left under bugs with full details
+```
+
+Or use the shortcut commands directly:
+
+```
+/burrow:add       /burrow:read      /burrow:dump
+/burrow:edit      /burrow:move      /burrow:archive
+/burrow:remove    /burrow:unarchive /burrow:help
+```
+
+All data lives in a single file: `.planning/burrow/cards.json`. The agent reads it into memory, resolves your references, and calls the CLI. You never touch JSON.
+
+## Agent Memory
+
+Say "remember to always use bun" or "don't forget — the API key comes from vault" and it becomes a card. The agent reads burrow on every session start, so persistent instructions survive context resets. No separate memory system, no markdown files drifting out of sync — just cards.
+
+## CLI Reference
+
+Under the hood, everything goes through `burrow-tools.cjs`. The agent calls it for you, but you can run it directly too:
+
+```bash
+node .claude/burrow/burrow-tools.cjs <command> [options]
+```
+
+### Reading
+
+```bash
+read                          # show top-level cards
+read <id>                     # show a card and its direct children
+read <id> --depth 3           # show 3 levels of nesting
+read <id> --depth 0           # show the entire subtree (no limit)
+read <id> --full              # show full card bodies (no truncation)
+read --include-archived       # include archived cards in output
+read --archived-only          # show only archived cards
+dump                          # show everything: full tree, full bodies
+```
+
+`read` with no ID shows the root. With an ID, it focuses on that card and shows breadcrumb ancestry. The default depth is 1 (direct children only).
+
+`dump` is shorthand for `read --depth 0 --full` — the "show me everything" command.
+
+Bodies longer than 200 characters are truncated unless you pass `--full`.
+
+### Creating
+
+```bash
+add --title "Bug tracker"                    # add to root
+add --title "Login crash" --parent <id>      # add as child
+add --title "First" --body "Details here"    # add with body
+add --title "Urgent" --parent <id> --at 0    # insert at position
+```
+
+`--at` takes a 0-based index. `--at 0` puts the card first, omitting it appends to the end.
+
+### Editing
+
+```bash
+edit <id> --title "New title"
+edit <id> --body "Updated description"
+edit <id> --title "New" --body "Both at once"
+```
+
+Only the fields you pass get changed. Everything else stays the same.
+
+### Moving
+
+```bash
+move <id> --to <parent-id>         # move to a different parent
+move <id> --to root                # move to root level
+move <id> --at 0                   # reorder within current parent (move to first)
+move <id> --to <parent-id> --at 2  # move to parent at specific position
+```
+
+`--to` sets the destination parent. `--at` sets the position (0-based). Use `--at` alone to reorder within the current parent without moving.
+
+The CLI prevents cycles — you can't move a card into its own subtree.
+
+### Archiving
+
+```bash
+archive <id>                  # archive card and all descendants
+unarchive <id>                # restore card and all descendants
+```
+
+Archiving cascades — archiving a parent archives its entire subtree. Unarchiving restores the whole subtree. Archived cards are hidden from `read` by default.
+
+### Deleting
+
+```bash
+remove <id>                   # permanently delete card and all descendants
+```
+
+This is permanent — the card and its entire subtree are gone. But `cards.json` is tracked in git, and every write creates a `.bak` file with the previous state, so recovery is always possible.
+
+### Finding
+
+```bash
+find <query>                  # search card titles (case-insensitive)
+path <id>                     # show ancestry path from root to card
+```
+
+`find` searches all active (non-archived) card titles and returns matches with their full path. `path` shows the breadcrumb trail: `burrow > parent > child [id]`.
+
+### Card Schema
+
+Every card has this shape:
+
+```json
+{
+  "id": "8eaff688",
+  "title": "Card title",
+  "created": "2026-03-07T19:08:41.051Z",
+  "archived": false,
+  "body": "Free-form text, any length",
+  "children": []
+}
+```
+
+IDs are 8-character hex strings, generated automatically. Timestamps are ISO 8601. The body field is free-form — use it for descriptions, notes, agent instructions, whatever you want.
+
+### Tree Output
+
+The pretty-printed tree shows indicators after each card title:
+
+```
+  ├─ [8698f27b] Auth API (6) +                   1d ago
+```
+
+- `(N)` — active descendant count (hidden when 0)
+- `+` — card has a body (read the card to see it)
+- `[archived]` — card is archived (only visible with `--include-archived`)
+- `1d ago` — relative age, right-aligned
+
+## Why
+
+AI agents working on your project need to track state — tasks, decisions, context. But reading scattered files is expensive, so they cache. Caches drift. Markdown summaries go stale. Multiple files representing the same data fall out of sync. I've [measured it](field-reports/agent-state-drift.md): a 29% failure rate keeping two representations of the same data in sync, with silent drift accumulating over 24 hours before anyone notices.
+
+What if you made the source of truth so cheap to read that caching was pointless?
+
+A flat TODO list wasn't enough. A full-blown project tracker was too much. I needed something in between — a place to throw structured thoughts without ceremony, that the agent could read and write as naturally as I could talk to it.
+
+That's Burrow. One file, one read, one truth — it's just JSON. Zero dependencies, near-instant reads. No caches to invalidate. No sync steps to skip. No secondary updates to forget.
+
+Consistent, reliable, fast and infinitely extensible.
+
+## Uninstall
+
+Delete the files and it's gone. No background processes, no global state, nothing to clean up.
+
+```bash
+rm -rf .claude/burrow .claude/commands/burrow.md .claude/commands/burrow .planning/burrow
+```
+
+Then remove the "Burrow — Agent Memory" section from your `CLAUDE.md`.
+
+## Privacy
+
+Burrow data is meant to be committed to git. Anything stored in cards is visible to anyone with repo access. Avoid storing secrets, credentials, or sensitive personal information.
+
+## FAQ
+
+**What's `cards.json.bak`?**
+
+Every time burrow writes, it saves the previous version as `.bak` before touching the real file. The actual write goes to a `.tmp` file first, then gets atomically renamed to `cards.json` — so your data is either the old version or the new version, never half-written. The `.bak` is a bonus rollback if you ever need it. It's in `.gitignore` by default.
+
+**Can I lose data?**
+
+Burrow uses atomic writes (tmp file + rename), which is the safest way to write files on disk. Your data won't corrupt from a crash or killed process. The `.bak` file is there as an extra safety net.
+
+**Can multiple agents use the same burrow?**
+
+There's no file locking yet, so two agents writing at the same time could overwrite each other. If you make sure they don't write simultaneously, it works fine. Use at your own risk.
+
+**How big can the tree get?**
+
+No artificial limits — it's just JSON. The practical ceiling is when the file gets too large for the agent to read in one shot, which is thousands of cards. You'll run out of things to track before you hit it.
+
+**Should I commit cards.json?**
+
+Yes, that's the point. It's your project state, version-controlled like everything else.
+
+**Can I edit cards.json by hand?**
+
+You can, it's just JSON. But the CLI handles IDs, timestamps, and structure for you. If you edit manually, make sure the schema stays valid.
+
+**Does it work with other AI agents?**
+
+Right now it's built for Claude Code. The slash commands and workflow file are Claude-specific. The CLI itself (`burrow-tools.cjs`) is just a Node script — any agent that can run shell commands could use it, but the integration layer would need to be built.
+
+## Contributing
+
+Issues and PRs welcome.
+
+## License
+
+TBD