@roodriigoooo/pi-docket 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+## 0.4.0
+
+- **rename to pi-docket**: product, package, repo title, command, storage paths, worker tools, tmux session, and extension surface now use Docket. Package is `@roodriigoooo/pi-docket`; GitHub repo title should be `pi-docket`; command is `/docket`; extension surface is `globalThis.__docket`; worker tmux session is `docket-workers`.
+- **no compatibility command aliases**: old `/trail` commands are intentionally not retained. Removed public grammar for `/docket checkpoint`, `/docket continue`, `/docket resume`, short aliases (`ckpt`, `r`, `s`, `v`), worker-result aliases (`w<N>`, `result`, `use`), and `inject` alias. The command surface now favors explicit verbs.
+- **evidence bundles replace checkpoint-first UX**: use `/docket save` to save selected evidence as a durable zero-token bundle and label the current Pi tree leaf; use `/docket load` to mount bundle or worker artifacts. Pi's native `/tree`, `/fork`, `/clone`, `/compact`, `/new`, and `/resume` remain responsible for session movement and context topology.
+- **worker protocol renamed**: workers now call `docket_todos`, `docket_wait`, `docket_done`, `docket_fail`, and `docket_spawn_child`. Worker-side `/docket wait|done|fail` remains only a fallback for prompt entry mistakes.
+- **release notes**: see [docs/releases/0.4.0.md](docs/releases/0.4.0.md) for rationale, migration notes, and repository rename checklist.
+
+## 0.3.2
+
+- **bundle-first checkpoints**: a checkpoint is now a frozen artifact bundle (`<id>.artifacts.json`) plus a small deterministic orientation header — git state, files touched, errors, and your note — not a model summary. `continue` and `load` both *mount* the bundle at zero model-context tokens; `continue` injects only the header, and artifacts are chipped on demand. The model summarizer becomes an opt-in `--summarize` layer (`--model` / `--max-output` imply it), off the default path. The four mode flags (`--handoff` / `--compact` / `--debug` / `--review`) and `--raw` are dropped in favour of one default selection that the interactive selector prunes. Checkpoints written by older versions still read and continue (`CheckpointMode` kept for back-compat reads). Rationale in [ADR-0001](docs/adr/0001-bundle-first-checkpoints.md); a new `CONTEXT.md` glossary fixes the "checkpoint = bundle, not summary" ambiguity.
+- **verdict card**: a focused per-worker decision surface. Open it with `ctrl+shift+d` (jumps to the highest-attention decision), `/docket v` / `/docket verdict [w<N>]`, or `enter` on a worker row. It reads only status fields and the deterministic change set — the worker's intent line, its question, or the diffstat (`+/-` with a proportional bar) — never the transcript or artifacts, so it costs zero model-context tokens. `d` opens the full diff in an overlay without injecting it.
+- **worker-proposed decisions**: `docket_wait({ risk?, options?, recommend? })` lets a blocked worker propose discrete branches. The card renders them as the menu (sent back to the worker verbatim), pre-selects the recommended option, and surfaces `risk` as a warning — ADR-0001's human-authored-note lesson applied to the question side.
+- **verdict queue**: opening the card without a target now walks every pending decision in attention order instead of resolving only the top one — the footer counts what's left and `esc` stops the walk. It re-ranks after each resolution so new arrivals and dismissals stay current. Verbs name the outcome: **promote** / **discard** when a change set exists, **acknowledge** / **dismiss** when it doesn't, plus **reject & stop** and **chat**; a cancelled sub-action returns to the verb menu instead of closing the card.
+- **live dock dot**: the frozen `[o  ]` worker chip becomes a breathing dot that animates only while a worker is active; static mascot frames are stripped from one-shot spawn messages.
+- **cross-project worker views**: `/docket workers --all` and `/docket list --all` surface workers from other projects, and the dock breadcrumb summarizes their attention state (`N waiting · N failed · N ready`) instead of a bare count.
+- new tests cover verdict verbs/queue, the change-set card, structured `docket_wait`, bundle-first checkpoint selection + orientation header, and cross-project worker ranking.
+
+## 0.3.1
+
+- **auto-embed ready summary**: when a worker reaches `ready`, docket appends a short summary (outcome + one-line headline + up to five recommended bullets) to the parent pi session via `pi.sendMessage({ triggerTurn: false })`. The parent assistant sees it on its next turn without manual `/docket inject`, and any worker spawned afterwards inherits it through session seeding — so sibling findings cross-pollinate without a dedicated channel. Full artifacts still live on disk; `/docket load w<N>` remains the path for the long-form detail. Gated by `worker.autoEmbedSummary` (default true) for users who prefer the pure-ledger behavior. New pure formatter `formatReadyEmbedMessage` in `extensions/worker-summary-embed.ts` is fully testable without pi.
+- **kind visibility in the UI**: the worker kind now shows in three surfaces that previously only labelled the worker by index. Dock row renders `● w1·scout …` next to the label; the spawn announce chip becomes `w3·patcher[o  ] · starting`; the spawn-detail and the `/docket w<N>` mini-report both gain an explicit `kind:` line. The implicit `default` kind is suppressed everywhere to keep the common case clean. Model badge keeps its existing brackets so kind and model are visually distinct.
+
+## 0.3.0
+
+Included:
+- **worker kinds**: frontmatter MD presets that tune one worker's posture without changing the protocol contract. Bundled `scout` (fast read-only recon) and `patcher` (edits in worktree, can dispatch scout) under `extensions/worker-kinds/`; user overrides in `~/.pi/agent/docket/worker-kinds/*.md` and `<project>/.pi/docket/worker-kinds/*.md`. Fields: `name`, `description`, `model`, `thinking`, `read_only`, `default_worktree`, `parent_seed`, `max_artifacts`, `max_duration_sec`, `can_spawn`, `layout`, `guardrails_append`, plus a markdown body that is *appended* to the universal guardrails (never replaces them).
+- **`/docket spawn --as <kind>`**: pick a kind per spawn. `/docket kinds` lists registered kinds.
+- **fleet + depth caps**: `worker.maxActive` (default 8) rejects spawns past the cap with a clear error rather than queuing. `worker.maxSpawnDepth` (default 2) bounds how deep child spawns can recurse.
+- **cascade delete**: `/docket delete w<N>` now purges children dispatched via `docket_spawn_child` along with the parent.
+- **`docket_spawn_child` tool**: only registered for workers whose kind has a `can_spawn` allowlist and only when current depth is below the cap. Child status carries `parentWorkerId`/`depth`; child outcome surfaces in the parent worker's inbox, not directly to the human user.
+- **stable tmux window id**: `tmuxWindowId` (`@N`) captured at spawn time. kill, send-keys, and pipe-pane target the id first with name fallback, so renamed/recycled windows no longer misroute parent input.
+- **per-kind tmux layout**: `layout: split-events` opens a right pane showing `tail -F events.ndjson` so the user can watch tool activity live without context switching.
+- **optional tmux status-line dock**: `worker.tmuxStatusLine: true` writes a compact `docket ?N ✗N ✓N ●N` summary to the shared session's `status-right` so the dock survives even when you're attached to a pane.
+- **optional terminal capture**: `worker.captureTerminal: true` enables `tmux pipe-pane` to `pane.log` inside each worker dir for post-hoc debug.
+- **`/docket respawn <w<N>|all>`**: relaunch workers whose tmux window died (orphan reconciliation no longer means losing the session dir).
+- **`globalThis.__docket` extension surface**: `registerWorkerKind`, `listWorkerKinds`, `onWorkerEvent`. Other pi extensions can contribute kinds at runtime and subscribe to worker events without coupling to docket internals.
+- **worker event subscription**: `WorkerSnapshotCache.snapshot()` now returns `newEventsByWorker` (events read this tick) alongside the existing sticky `eventsByWorker` ring. The parent dock pipes new events through the extension surface on every refresh.
+- new tests cover worker-kinds parsing + registry, extension surface, grammar (`--as`, `kinds`, `respawn`), cascade purge, and `countActive`.
+- **docs cleanup**: README slimmed (587 → ~400 lines) and points at new `docs/configuration.md` for the full config reference, worker-kind frontmatter table, and worked kind examples. `docs/architecture.md` rewritten as a module map + worker lifecycle + storage + extension surface. `docs/stress-test.md` moved out of `scripts/` and inlined the sampler so it has no external dependency. `docs/design-decisions-tmux-and-events.md` removed; same content now lives in much shorter form in `docs/architecture.md`. `scripts/` removed from the package and gitignored. npm-pack leak of personal stress-test results closed by moving the file to a hidden, gitignored path.
+- **README banner**: npm version badge.
+
+## 0.2.2
+
+Included:
+- shared `docket-workers` tmux session: one server hosts every worker window instead of N servers
+- worker NDJSON event stream at `workers/<id>/events.ndjson` for state, todo, and tool-call events
+- dock sub-line under thinking workers showing the latest non-protocol tool call (file path, command, etc.)
+- `WorkerSnapshotCache` keeps a sticky recent-event buffer so sub-lines survive across refresh ticks
+- `fs.watch`-driven dock refresh in place of the 500 ms polling timer, with mtime-cached status + artifacts reads
+- heartbeat dedup: workers skip `writeArtifacts` when their artifact list signature is unchanged
+- session JSONL seeding (`SessionManager.forkFrom`) so spawned workers resume from the parent's prefix and hit the provider's prompt cache. Opt out with `/docket spawn --fresh`
+- `/docket attach [w<N>]` first-class command that copies the tmux attach incantation, optionally pinned to one worker
+- idle eviction: ended workers auto-hide from the dock after `worker.dockIdleHideMinutes` (default 30) and auto-prune after `worker.pruneAfterHours` (default 24)
+- worker guardrails note that the tmux session is shared; workers must not invoke `tmux` directly
+- README simplified, outdated demo gifs removed
+- stress-test runbook + sampler under `scripts/`
+- architecture doc resynced (storage layout, shared topology, event stream, eviction)
+
+## 0.2.1
+
+Included:
+- README rewrite with a more direct, personal tone
+- note that current GIFs are outdated and need refreshing
+
+## 0.2.0
+
+Included:
+- compact worker dock above the prompt for live worker state without context injection
+- worker protocol tools (`docket_wait`, `docket_done`, `docket_fail`) plus bash fallback interception for accidental `/docket wait|done|fail` calls
+- `/docket tell w<N> [text]` for explicit worker input/follow-up, with modal input when text is omitted
+- simplified Navigator modes: Review, Answers, All
+- hard rename from Memory to Answers and Catalog to All
+- numeric mode keys (`1` Review, `2` Answers, `3` All) and `t` for telling workers
+- `/docket workers` positioned as a debug/power view with clearer labels
+- docs and tests for updated worker/mode UX
+
+## 0.1.4
+
+Included:
+- soft-consume for `--once` checkpoints: marked consumed at session end (not on inject), files retained for `consumedRetentionDays` (default 7) so accidental cancels are recoverable
+- `/docket load [id|last|w<N>] [--include-consumed]` — lazy carryover of checkpoint or worker artifacts into the navigator with **zero** model-context cost; injected only when user creates a chip with `/docket ref` or `/docket inject-full`
+- unified `/docket load` picker for checkpoints and workers, with preview for checkpoints before loading
+- `/docket unload <id|w<N>|all>` — drop loaded checkpoint/worker artifacts from the session and cancel pending checkpoint consume contracts
+- tmux-backed `/docket spawn <task>` workers, plus `/docket list --workers`, `/docket load w<N>`, and `/docket delete w<N>`
+- worker artifact snapshots so parent sessions can inspect and reference worker findings via loaded slots
+- JSONL-backed checkpoint event log with legacy index backfill
+- navigator `s` key cycles source filter (current / all / `c1` / `w1` / ...); default view is `current`
+- carryover artifacts namespaced as `<slot>.<displayId>` (e.g. `c1.f12` or `w2.c3`), refs unchanged
+- `/docket list [--include-consumed]` shows soft-consumed checkpoints
+- `/docket delete` permanently purges checkpoints (bypasses soft-consume) and kills workers when targeting `w<N>`
+- internal deepening: Loaded Artifact Context, Checkpoint Commands, and Worker Commands concentrate reference/carryover and command-flow logic behind tested Modules
+
+## 0.1.3
+
+Included:
+- ranked artifact search index backing `/docket search`, with ripgrep-backed candidate scoring and in-memory fallback
+- npm trusted publishing pipeline for releases
+- README demo videos / gif walkthroughs
+
+## 0.1.2
+
+Included:
+- cleaner checkpoint reference lists with single file guidance note
+- hidden checkpoint context loading for `/docket continue` to avoid editor prompt bloat
+- loaded checkpoint chip above the editor
+- `/docket delete [id|last]` command
+- checkpoint selector delete action with confirmation
+
+## 0.1.1
+
+Included:
+- centered Docket command-center overlay with stronger island borders
+- denser artifact rows with filter chips, relative time, and preview toggle
+- interactive `/docket resume` / `/docket continue` checkpoint selector
+- checkpoint preview and edit-before-continue flow
+- checkpoint summaries with file, error, command, and token estimates
+
+## 0.1.0
+
+Initial package scaffold.
+
+Included:
+- `/docket` artifact navigator
+- artifact search via ripgrep-backed temp docs
+- compact artifact references
+- full artifact injection
+- summarized/raw checkpoints
+- one-off `--once` checkpoints
+- checkpoint sidecar artifacts

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Docket contributors
+
+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,241 @@
+<p align="center">
+  <img src="./assets/docket_logo.jpeg" alt="Docket logo" width="220" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@roodriigoooo/pi-docket"><img src="https://img.shields.io/npm/v/@roodriigoooo/pi-docket?color=cb3837&label=npm&logo=npm" alt="npm version" /></a>
+</p>
+
+# pi-docket
+
+Docket is a decision queue for work done inside pi.
+
+It pulls the few moments that need human judgment out of long agent work: worker findings, proposed patches, failed commands, saved evidence bundles, and questions. It is not a transcript browser, not a memory system, and not a task manager. Docket keeps evidence available and asks: **what needs a decision now?**
+
+> Formerly `trail`. The rename is intentional: the product is no longer framed as a history trail or session-resume system. Docket is a docket of cases needing judgment, with evidence bundles attached.
+
+## Core philosophy
+
+- **Pi owns sessions.** Use pi's `/tree`, `/fork`, `/clone`, `/compact`, `/new`, and `/resume` for conversation topology and context-window management.
+- **Docket owns decisions.** It ranks artifacts into review items, shows cards, and keeps evidence out of model context until you attach it.
+- **tmux owns parallel visibility.** Workers are visible pi processes in one shared tmux session. You can attach and inspect them directly.
+- **Workers are explicit.** Docket may eventually suggest a worker only when context-heavy work is obvious and maps to a known worker kind. It must never silently spawn.
+
+## Install
+
+```bash
+pi install git:github.com/roodriigoooo/pi-docket
+```
+
+Open Docket:
+
+```bash
+/docket
+```
+
+Spawn a worker explicitly:
+
+```bash
+/docket spawn --as scout map callers of getUser()
+```
+
+Save evidence as a zero-token bundle:
+
+```bash
+/docket save auth investigation findings
+```
+
+Load a bundle or worker artifacts:
+
+```bash
+/docket load last
+/docket load w1
+```
+
+## Rename from Trail
+
+This release is a breaking rename.
+
+- Package: `@roodriigoooo/pi-docket`
+- GitHub repo title: `pi-docket`
+- Slash command: `/docket`
+- Old `/trail` commands are not kept as aliases.
+- Worker protocol tools are now `docket_wait`, `docket_done`, `docket_fail`, `docket_todos`, and `docket_spawn_child`.
+- Storage/config paths now use `docket`:
+  - `~/.pi/agent/docket/`
+  - `~/.pi/agent/docket.json`
+  - `<project>/.pi/docket.json`
+  - `<project>/.pi/docket/worker-kinds/*.md`
+
+If you need old data, copy it manually before deleting the old package:
+
+```bash
+cp -R ~/.pi/agent/trail ~/.pi/agent/docket
+cp ~/.pi/agent/trail.json ~/.pi/agent/docket.json 2>/dev/null || true
+cp -R .pi/trail .pi/docket 2>/dev/null || true
+cp .pi/trail.json .pi/docket.json 2>/dev/null || true
+```
+
+## Basic loop
+
+```text
+  work / spawn       capture             decide                act
+  current pi    ->   artifacts       ->  /docket cards   ->   Enter review
+  /docket spawn      status.json         evidence             c reply/save
+                                      bundles/workers         a attach ref
+```
+
+1. **Work or spawn** — keep working in the parent session, or explicitly start a background worker with `/docket spawn`.
+2. **Capture** — Docket records failed commands, file changes, worker results, saved bundles, and questions.
+3. **Decide** — `/docket` opens only items that likely need attention.
+4. **Act** — review, reply, promote, dismiss, attach evidence, save/load bundles, or attach to tmux.
+
+## Commands
+
+Primary commands:
+
+| Command | Purpose |
+|---|---|
+| `/docket` | Open decision docket. |
+| `/docket spawn [--fresh] [--as <kind>] <task>` | Start explicit background worker. |
+| `/docket tell w<N> [text]` | Reply to worker. |
+| `/docket attach [w<N>]` | Copy tmux attach command for shared worker session. |
+| `/docket save [flags] [note]` | Save selected evidence as bundle and label current pi tree leaf. |
+| `/docket load [id\|last\|w<N>]` | Mount bundle or worker artifacts at zero model-context cost. |
+
+Advanced commands:
+
+| Command | Purpose |
+|---|---|
+| `/docket workers [--all]` | Worker dashboard. |
+| `/docket verdict [w<N>]` | Resolve highest-attention worker decision. |
+| `/docket kinds` | List worker kinds. |
+| `/docket respawn <w<N>\|all>` | Relaunch worker whose tmux window died. |
+| `/docket answers [query]` | Browse assistant/worker answers. |
+| `/docket log` | Audit timeline grouped by episode. |
+| `/docket search <query>` | Ranked artifact search. |
+| `/docket list [--include-consumed] [--workers\|--all]` | List saved bundles or workers. |
+| `/docket unload <id\|w<N>\|all>` | Drop mounted bundle/worker artifacts. |
+| `/docket delete [id\|last\|w<N>]` | Delete bundle or worker. Worker delete cascades to children. |
+| `/docket ref <artifact-id>` | Attach compact artifact reference to next prompt. |
+| `/docket inject-full <artifact-id>` | Attach full artifact text to next prompt. |
+| `/docket copy <artifact-id>` | Copy artifact text. |
+| `/docket clear` | Drop pending chips/widgets. |
+
+No short aliases are intentionally provided. Fewer commands, clearer intent.
+
+## Evidence bundles
+
+A Docket bundle is a frozen artifact sidecar plus a small orientation markdown file. It is not a model-written summary by default.
+
+`/docket save`:
+
+- selects relevant artifacts,
+- lets you prune/edit the bundle header,
+- writes `<id>.md` + `<id>.artifacts.json`,
+- labels the current pi session tree leaf as `docket:<id>`.
+
+`/docket load` mounts bundle artifacts into the current session's Docket navigator at zero model-context cost. Nothing enters the model prompt until you explicitly attach a compact ref or full artifact.
+
+This deliberately complements pi:
+
+- use `/tree` to move conversation state,
+- use `/fork` or `/clone` to split sessions,
+- use `/compact` for lossy summary,
+- use `/docket save` for durable evidence,
+- use `/docket load` when that evidence becomes relevant.
+
+## Workers
+
+`/docket spawn <task>` starts a background pi worker as one window in a shared tmux session named `docket-workers`.
+
+Workers have:
+
+- hidden workspace, often a detached git worktree,
+- task file,
+- `status.json`,
+- `artifacts.json`,
+- append-only `events.ndjson`,
+- protocol tools for parent communication.
+
+Worker artifacts never enter model context automatically except for the short ready summary, if enabled. Full evidence stays on disk until loaded or attached.
+
+### Worker kinds
+
+Bundled kinds:
+
+- `default` — general worker, edits allowed when task asks.
+- `scout` — fast read-only recon.
+- `patcher` — edits in worker worktree and proposes a change set.
+
+Examples:
+
+```bash
+/docket spawn --as scout find route handlers that touch auth cookies
+/docket spawn --as patcher rename AccountService in src only
+```
+
+Custom kinds live in:
+
+- `~/.pi/agent/docket/worker-kinds/*.md`
+- `<project>/.pi/docket/worker-kinds/*.md`
+
+See [docs/configuration.md](./docs/configuration.md#worker-kinds).
+
+### Worker protocol
+
+Workers use tools, not shell commands:
+
+| Tool | Purpose |
+|---|---|
+| `docket_todos` | Publish small progress board. |
+| `docket_wait` | Ask parent for input and pause. |
+| `docket_done` | Mark useful output ready for review. |
+| `docket_fail` | Mark cannot continue with no useful partial output. |
+| `docket_spawn_child` | Dispatch allowed child worker kind. |
+
+Worker-side `/docket wait`, `/docket done`, and `/docket fail` are fallback prompt commands only.
+
+## tmux
+
+All workers live in one shared tmux session:
+
+```bash
+tmux attach -t docket-workers
+```
+
+`/docket attach` copies the attach command. `/docket attach w2` selects that worker's window.
+
+This is intentional: tmux gives direct observability and real parallelism, while Docket controls artifact capture and parent/worker coordination.
+
+## Development
+
+Run from repo:
+
+```bash
+pi --no-extensions -e ./extensions/docket.ts
+```
+
+Smoke test:
+
+```bash
+npm run smoke:help
+```
+
+Type check:
+
+```bash
+npm run check
+```
+
+Tests:
+
+```bash
+npm test
+```
+
+Dry-run package:
+
+```bash
+npm run pack:dry
+```

package/docs/adr/0001-bundle-first-checkpoints.md

@@ -0,0 +1,21 @@
+# Bundle-first checkpoints
+
+Superseded in public UX by [ADR-0002](./0002-rename-to-docket.md): users now see **evidence bundles** via `/docket save` and `/docket load`; Pi owns session continuation. Internal storage still uses checkpoint type names for compatibility.
+
+A checkpoint is a frozen **artifact bundle** (`<id>.artifacts.json`) plus a small deterministic **orientation header** — not a model-written summary. The old `continue` path opened a fresh session, **mounted** the bundle at zero model-context tokens, and injected only the header (git, files touched, errors, the human-authored note); artifacts were chipped on demand. The model summarizer became an opt-in `--summarize` layer, off the default path. The four modes (`handoff/compact/debug/review`) were dropped in favour of one default selection (errors + files + recent decisions) that the interactive selector prunes.
+
+## Status
+
+accepted
+
+## Considered options
+
+- **Summary-first (previous default):** the summarizer ran on every checkpoint and `continue` injected its prose. Rejected: it contradicts Docket's stated thesis ("it keeps the useful artifacts around" rather than "compressing everything into a summary"), pays a model call per checkpoint, bloats the fresh session's context, and lets the model *invent* decisions/next-steps — the one thing its own system prompt warned against.
+- **Keep four modes:** rejected once the summarizer left the hot path — the modes reduced to thin kind-orderings that the interactive selector already supersedes.
+
+## Consequences
+
+- The **note** is now load-bearing: decisions and next steps are human-authored, not model-guessed. Checkpoint quality tracks what the human writes.
+- `continue` no longer puts artifact *contents* in context on turn 1 — only the orientation header. Resuming work needs a chip or a question first. This is deliberate and matches the zero-token philosophy that `load` already embodied.
+- `continue` now composes `load` (both mount); they stop being separate restore paths.
+- The summarizer module, provider/model config, and the `CheckpointMode` branch stay in-tree but become optional/back-compat surface, not the spine.

package/docs/adr/0002-rename-to-docket.md

@@ -0,0 +1,44 @@
+# Rename Trail to Docket
+
+Trail is renamed to **Docket** and the repository/package title becomes **pi-docket**.
+
+## Status
+
+accepted
+
+## Context
+
+The old name, Trail, suggested a history path, transcript browser, or session-resume tool. That conflicted with the product direction.
+
+Pi already provides first-class session topology and context-management tools: `/tree`, `/fork`, `/clone`, `/compact`, `/new`, and `/resume`. Docket should respect those instead of competing with them.
+
+The extension's stronger identity is a decision queue: artifacts become review items, workers produce evidence, verdict cards resolve cases, and evidence bundles can be mounted at zero model-context cost.
+
+## Decision
+
+Rename the product surface to Docket:
+
+- package: `@roodriigoooo/pi-docket`
+- repo title: `pi-docket`
+- command: `/docket`
+- extension entrypoint: `extensions/docket.ts`
+- extension surface: `globalThis.__docket`
+- worker tmux session: `docket-workers`
+- worker protocol tools: `docket_todos`, `docket_wait`, `docket_done`, `docket_fail`, `docket_spawn_child`
+- config/storage paths: `~/.pi/agent/docket*` and `.pi/docket*`
+
+Do not keep `/trail` compatibility aliases. Command bloat works against the new clarity.
+
+Replace checkpoint-first user language with **evidence bundle** language:
+
+- `/docket save` creates a durable evidence bundle and labels the current Pi tree leaf.
+- `/docket load` mounts bundle or worker artifacts at zero model-context cost.
+- Pi owns continuation and branch/session movement.
+
+## Consequences
+
+- This is a breaking release.
+- Users must move from `/trail` to `/docket`.
+- Old Trail storage is not automatically read from the new Docket paths. Migration is a copy operation documented in README and release notes.
+- Internal TypeScript module names may still use `checkpoint` where storage compatibility makes a full rename low-value.
+- Future spawn suggestions, if added, must be rare and explicit: only when context-heavy work is obvious, maps to a known worker kind, and separate context protects the parent session.

package/docs/architecture.md

@@ -0,0 +1,101 @@
+# Docket Architecture
+
+Docket is a pi extension. The unit of work is an **artifact**: a structured object derived from session activity (command, file edit, prompt, response, error, worker status, or saved evidence bundle). A small attention queue ranks unresolved artifacts as **review items**; the **verdict** card is where one worker decision is resolved — reading only status fields and the deterministic change set, never the transcript. **Workers** are background pi processes; **evidence bundles** are durable artifact packages. Pi owns session movement; Docket owns evidence and decisions. Rename rationale lives in [ADR-0002](./adr/0002-rename-to-docket.md).
+
+If you're contributing, read this end-to-end. If you're using Docket, the README and [configuration.md](./configuration.md) are what you want.
+
+## Module map
+
+Each module owns its data, its interface, and its tests. Adapters at the seam talk to pi, tmux, the filesystem, or the clipboard.
+
+| Module | File | Owns |
+|---|---|---|
+| Artifact Catalog | `extensions/artifact-catalog.ts` | Extraction, identity, lookup, references, full text, inspect, bundle payloads. |
+| Search Index | `extensions/search-index.ts` | Ripgrep adapter over artifact docs, in-memory fallback, attention-weighted ranking. |
+| Bundle Lifecycle | `extensions/checkpoint-lifecycle.ts` | Bundle-first: select candidates → user prune → orientation header (opt-in `--summarize`) → review → persist. Internal type names still use checkpoint for storage compatibility. See [ADR-0001](./adr/0001-bundle-first-checkpoints.md). |
+| Bundle Store | `extensions/checkpoint-store.ts` | Markdown + sidecar JSON on disk; event-backed lifecycle; soft-consume. |
+| Bundle Commands | `extensions/checkpoint-commands.ts` | `list` / `delete` support for saved bundles. |
+| Bundle Selector | `extensions/checkpoint-selector.ts` | Interactive accept/exclude before optional summarization. |
+| Loaded Artifact Context | `extensions/loaded-artifact-context.ts` | Mounted source slots, reference/full chip expansion, consume-on-use queue. |
+| Background Work | `extensions/background-work.ts` | Worker state transitions, protocol semantics, synthetic status artifacts, heartbeat dedup. |
+| Worker Commands | `extensions/worker-commands.ts` | `spawn` / `tell` / `delete` / `load` / `unload` / completion. |
+| Worker Store | `extensions/worker-store.ts` | Shared tmux session topology, `send-keys -l` stdin, session seeding. |
+| Worker Events | `extensions/worker-events.ts` | NDJSON append + tail + rotation. |
+| Worker Snapshot Cache | `extensions/worker-dock-cache.ts` | mtime-cached status/artifacts read, `fs.watch`, sticky recent-event ring. |
+| Worker Eviction | `extensions/worker-eviction.ts` | Dock idle-hide window, prune-after-hours sweep. |
+| Worker Kinds | `extensions/worker-kinds.ts` | Frontmatter parser, registry, guardrails appendix composer. |
+| Extension Surface | `extensions/docket.ts` (via `globalThis.__docket`) | `registerWorkerKind`, `listWorkerKinds`, `onWorkerEvent`. |
+| Navigator | `extensions/docket-navigator.ts` | View model, ranking, selection state, mode/source transitions. |
+| Command Router | `extensions/docket-command-router.ts` | Routes parsed intents to the modules above. |
+
+## Worker lifecycle
+
+1. `Worker Commands.spawn(task, { as, fresh, worktree })` resolves the kind, checks `maxActive`, calls `Worker Store.spawn`.
+2. `Worker Store` opens a window in the shared tmux session `docket-workers`. If `parent_seed: full`, it forks the parent's JSONL via `SessionManager.forkFrom` and launches with `--continue`.
+3. The worker pi writes to `task.md`, ticks `status.json` every 15 s (heartbeat), updates `artifacts.json` only when its signature changes, and appends every state transition / todo update / tool call to `events.ndjson`.
+4. Parent watches the workers root with `fs.watch` (recursive on macOS, polled fallback elsewhere). `WorkerSnapshotCache` reads new event bytes since its held offset, deduplicates by mtime, and keeps a 16-event sticky ring per worker.
+5. `Background Work` projects the snapshot into a synthetic status artifact. Navigator ranks it alongside file edits and errors. The dock renders one row per worker plus an event sub-line when thinking.
+6. Worker calls `docket_done` / `docket_fail` → state goes terminal → row enters `ready` / `failed` until evicted (`worker.dockIdleHideMinutes`) or pruned (`worker.pruneAfterHours`).
+
+## Worker protocol
+
+One contract for every kind. The MD body of a kind extends the universal guardrails; it does not replace them.
+
+| Tool | When | Effect |
+|---|---|---|
+| `docket_todos` | Multi-step work. | Replaces the visible todo board. |
+| `docket_wait` | Ambiguity, blocked auth, irreversible action. | Worker → `needs_input`, parent gets an inbox row. |
+| `docket_done` | Finished with useful output. | Requires `outcome`, `summary`, `evidence`. Vague work is rejected back to `docket_wait`. |
+| `docket_fail` | Cannot continue, no useful partial output. | Worker → `failed`. |
+| `docket_spawn_child` | Kind has `can_spawn`. | Opens a sibling window; child returns to parent worker, not the human. |
+
+`/docket wait` etc. via bash are intercepted inside worker sessions for fallback.
+
+## Storage layout
+
+Per-worker state under `~/.pi/agent/docket/workers/<id>/`:
+
+| File | Owner | Purpose |
+|---|---|---|
+| `task.md` | parent on spawn | Assignment, read once by the worker. |
+| `status.json` | worker heartbeat + protocol | Current state, mtime-cached by the dock. |
+| `artifacts.json` | worker heartbeat | Snapshot, signature-deduped between heartbeats. |
+| `events.ndjson` | worker live | Append-only event stream; rotated at 5 MB, one generation retained. |
+| `session/` | parent (seeded) | Forked pi JSONL prefix, enables `--continue` + cache reuse. |
+| `workspace/` | parent (seeded) | Detached git worktree isolated from the parent's working copy. |
+
+Bundle state under `~/.pi/agent/docket/`:
+
+| File | Owner | Purpose |
+|---|---|---|
+| `checkpoints/<id>.md` | Bundle Lifecycle | Orientation markdown. |
+| `checkpoints/<id>.artifacts.json` | Bundle Lifecycle | Sidecar refs, mounted by `/docket load`. |
+| `events.ndjson` | Bundle Store | Append-only lifecycle (save/consume/purge/sweep). |
+| `index.json` | Bundle Store (snapshot) | Compatibility snapshot, rebuilt from `events.ndjson`. |
+
+`index.json` is not authoritative — the event log is. It exists so external readers don't break.
+
+## Extension surface
+
+Other pi extensions read `globalThis.__docket` (installed once on activation):
+
+```ts
+declare global {
+  var __docket: {
+    registerWorkerKind(kind: WorkerKind): () => void;
+    listWorkerKinds(): WorkerKind[];
+    onWorkerEvent(handler: (event: WorkerEvent) => void): () => void;
+  };
+}
+```
+
+`onWorkerEvent` fires once per event tail per dock tick. Subscriber errors are caught and dropped — a misbehaving extension cannot crash Docket.
+
+## Key design choices
+
+- **One tmux session, N windows.** Pays for one tmux server regardless of fleet size. `send-keys -l` gives a safe parent→worker stdin without inventing a FIFO/socket protocol.
+- **NDJSON event stream over `fs.watch`.** Disk-backed, survives parent restarts, no daemon. Drives the dock without polling. `pipe-pane` captures terminal noise, not structured events — opt-in via `worker.captureTerminal` when debugging.
+- **Heartbeat dedup.** Worker hashes its artifact list each heartbeat; `writeArtifacts` is skipped when unchanged. Quiet workers cost ~0 disk I/O.
+- **mtime-cached reads in the parent.** `WorkerSnapshotCache` skips parse when neither status nor artifacts has changed.
+- **Session seeding for prompt cache.** `/docket spawn` (without `--fresh`) forks the parent JSONL into the worker session dir; worker resumes with `--continue` so the shared prefix is provider-cache eligible.
+- **Kinds extend, never replace.** Every worker runs the universal guardrails; the kind MD is appended. Adding a kind needs zero TypeScript.

package/docs/bundle-guidelines.md

@@ -0,0 +1,39 @@
+# Evidence bundle guidelines
+
+Docket bundles preserve useful evidence for future decisions. They are not transcript archives and they do not replace Pi's session commands.
+
+Use Pi for session movement:
+
+- `/tree`
+- `/fork`
+- `/clone`
+- `/compact`
+- `/new`
+- `/resume`
+
+Use Docket bundles for evidence:
+
+- `/docket save` — save selected artifacts and label current Pi tree leaf.
+- `/docket load` — mount artifacts at zero model-context cost.
+- `/docket ref` / `/docket inject-full` — attach specific artifacts only when needed.
+
+## Principles
+
+- Preserve decision-critical evidence only: goal, current state, decisions, failed attempts, dead ends, next steps, and references.
+- Prefer artifact references over pasted content. Quote exact output only when it changes the next action.
+- Separate facts from hypotheses. Do not present guesses, unknowns, or stale plans as decisions.
+- Make failure history explicit enough to avoid repeated mistakes, but remove redundant logs and low-signal output.
+- Keep next steps concrete and ordered.
+- Optimize for context-window health. Smaller bundles are better when they preserve the same continuation power.
+
+## Bundle-first shape
+
+An evidence bundle is an artifact sidecar plus a deterministic orientation header — not a summary (see [ADR-0001](./adr/0001-bundle-first-checkpoints.md)). The header carries git state, files touched, errors, and the human note. Artifact contents never auto-enter model context.
+
+The **note** is load-bearing: decisions and next steps are human-authored, never model-guessed. `--summarize` adds optional model prose on top.
+
+## Artifact selection
+
+Selection pre-picks a decision-oriented set (errors first, then files, commands, recent decisions). Interactive review removes noisy or irrelevant artifacts before persist.
+
+Excluded artifacts should stay excluded from the orientation header references and the sidecar JSON.