trekoon 0.4.5 → 0.4.7

package/.agents/skills/trekoon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trekoon
-description: "Use for Trekoon-based planning and execution: creating epics, tasks, and subtasks; breaking work into dependency-aware graphs; checking status and progress; planning backlog or sprint work; and coordinating agent execution from Trekoon. Prefer this whenever the user wants tracked implementation planning or Trekoon entity management, even if they do not explicitly say \"Trekoon\"."
+description: "Use for Trekoon-based planning and execution: epics, tasks, subtasks, dependency-aware graphs, status and progress, sprint or backlog work, and agent execution. Prefer whenever the user wants tracked implementation planning or Trekoon entity management, even if they do not say Trekoon."
 ---
 
 # Trekoon Skill
@@ -12,17 +12,15 @@ them.
 
 ## Mode Contracts
 
-- `trekoon plan <goal>`: create an execution-ready epic in Trekoon.
-- `trekoon <id>`: orient on the epic/task/subtask and report current state,
-  blockers, and next action.
-- `trekoon <id> execute`: own the epic until it is done, hard-blocked, or needs
-  user input. Use subagents by default for meaningful work that can run
-  independently when the harness exposes them.
-- `trekoon <id> team execute`: same completion contract, using Claude Agent
-  Teams only when the user explicitly asks and the environment supports it.
+- `trekoon plan <goal>`: create an execution-ready epic.
+- `trekoon <id>`: orient on the epic/task/subtask; report state, blockers, next.
+- `trekoon <id> execute`: own the epic until done, hard-blocked, or needs user
+  input. Use subagents by default for meaningful independent work.
+- `trekoon <id> team execute`: same contract, using Claude Agent Teams only
+  when the user explicitly asks and the environment supports it.
 
-Do not stop at analysis when Trekoon shows ready work. Do not invent a parallel
-plan outside Trekoon.
+Do not stop at analysis when ready work exists. Do not invent a parallel plan
+outside Trekoon.
 
 ## Load Rules
 
@@ -30,29 +28,36 @@ plan outside Trekoon.
 |---|---|
 | Any Trekoon request | This file |
 | Plan, break down, design tracked work | `reference/harness-primitives.md`, then `reference/planning.md` |
-| Execute, implement, complete tracked work | `reference/harness-primitives.md`, then `reference/execution.md` |
-| User explicitly asks for Claude team execution | `reference/harness-primitives.md`, then `reference/execution-with-team.md` |
+| Execute, implement, complete tracked work | `reference/harness-primitives.md`, then `reference/execution.md` (Team appendix at end) |
 | Sync gaps, conflicts, shared-storage questions | `reference/sync.md` |
 | Status transition error or status uncertainty | `reference/status-machine.md` |
 
-`reference/harness-primitives.md` is required before planning or execution
-because those modes may need local task displays, user questions, subagents,
-review agents, testing tools, and Trekoon evidence recording.
+`reference/harness-primitives.md` is required before planning or execution; it
+holds the canonical claim/append/finish recipe, harness runtime notes, local
+task tool rules, and review guidance.
 
 ## Route Input
 
-Resolve the first non-mode argument as an epic, task, or subtask:
+Resolve the first non-mode argument as an epic, task, or subtask in one call:
 
 ```bash
+trekoon --toon session --item <id>
+```
+
+Returns `kind` (`epic`|`task`|`subtask`), `parentEpicId`, the entity payload,
+epic-scoped readiness, and `suggestedNext`. Use this instead of the legacy
+three-call fallback:
+
+```bash
+# Legacy fallback (kept working, but burns ~3x the tokens):
 trekoon --toon epic show <id> 2>/dev/null || \
 trekoon --toon task show <id> 2>/dev/null || \
 trekoon --toon subtask show <id> 2>/dev/null
 ```
 
-If the ID is a task or subtask, resolve its parent epic and scope `session`,
-`suggest`, and `epic progress` to that epic. If the user asked to execute a task
-or subtask, start with that item; continue broader epic execution only when it
-matches the user intent.
+If the ID is a task or subtask, scope `suggest` and `epic progress` to its
+`parentEpicId`. If the user asked to execute that item, start with it;
+continue broader epic execution only when it matches the user intent.
 
 | User signal | Mode |
 |---|---|
@@ -74,21 +79,18 @@ matches the user intent.
 
 ## Execution Defaults
 
-- Start with `trekoon --toon session`; scope with `--epic <id>` when known.
+- Start with `session`; scope with `--epic <id>` when known.
 - If ready work exists, keep moving. After each `task done`, inspect
   `unblocked`, `warning`/`openSubtaskIds`, and `next`.
-- When executing an epic, use subagents by default for any meaningful work that
-  can run independently. Keep small or tightly coupled tasks in the parent
-  agent.
+- When executing an epic, use subagents by default for meaningful independent
+  work. Keep small or tightly coupled tasks in the parent agent.
 - Use your context for orchestration, dependency decisions, user communication,
   and final synthesis. Your job is to finish the epic, not personally perform
   every implementation step.
 - If a higher-priority harness rule blocks subagents without explicit user
-  wording, ask immediately and explain that Trekoon execution preserves the
-  parent context for orchestration.
-- For non-trivial implementation, run relevant tests and a separate review pass
-  when a review agent/skill is available. Record checks and review results in
-  Trekoon before closing work.
+  wording, ask immediately.
+- For non-trivial implementation, run relevant tests and a separate review pass.
+  Record checks and review results in Trekoon before closing work.
 
 ## Non-Negotiables
 
@@ -113,15 +115,14 @@ matches the user intent.
 
 ## Status Reminder
 
-Normal status flow is `todo -> in_progress -> done`; `blocked` requires an
-appended reason. Use `task done` for task completion because it auto-transitions
-from `todo` or `blocked` through `in_progress`. Load
-`reference/status-machine.md` for transition errors or uncertainty. For
-subtasks, claim or move through `in_progress` before marking `done`.
+`task done` auto-transitions from `todo` or `blocked` through `in_progress`,
+so prefer it for completion. Subtasks must claim or move through `in_progress`
+before `done`. Load `reference/status-machine.md` for transition errors or
+uncertainty.
 
 ## Recovery
 
-If Trekoon diagnostics show `recoveryRequired`, stop task selection and run:
+If diagnostics show `recoveryRequired`, stop task selection and run:
 
 ```bash
 trekoon --toon init

package/.agents/skills/trekoon/reference/execution.md

@@ -1,17 +1,20 @@
 # Execution Reference
 
 You are an orchestrator. Execute work from Trekoon, not markdown plan files.
-Execution is complete only when the epic is marked `done`, all remaining work is
-blocked with recorded reasons, or real user input is required.
+Execution is complete only when the epic is `done`, all remaining work is
+`blocked` with recorded reasons, or real user input is required.
 
-When executing an epic, use subagents by default for any meaningful work that
-can run independently. Keep small or tightly coupled tasks in the parent agent.
-Use your context for orchestration, dependency decisions, user communication,
-and final synthesis.
+Use subagents by default for meaningful independent work. Keep small or tightly
+coupled tasks in the parent. Use your context for orchestration, dependency
+decisions, user communication, and synthesis.
 
 If the plan has unclear requirements or meaningful tradeoffs, ask before
 starting. Do not stop at status reporting when ready work exists.
 
+The atomic-claim, append-progress, and `task done` recipes live in
+`reference/harness-primitives.md`. This file references them rather than
+restating.
+
 ## Choose Shape
 
 - Direct work: one ready task, tiny change, narrow scope, or tightly coupled
@@ -79,40 +82,28 @@ Scope:
 - Read first: <paths/patterns to inspect before editing>
 - Do not touch: <paths owned by other lanes>
 
-Before each task:
-- trekoon --toon task claim <id> --owner <lane-name>
-- trekoon --toon task update <id> --append "Starting implementation"
-
-While working:
-- Complete required subtasks and update subtask statuses.
-- Append meaningful progress notes; do not rewrite task descriptions.
-- Respect status flow: todo -> in_progress -> done. Use task done for task
-  completion; for subtasks, claim or move through in_progress before done.
-- Assume other agents may edit unrelated files. Do not revert unrelated changes.
+For each task use the atomic-claim + append-progress recipe in
+reference/harness-primitives.md:
+- claim with --owner <lane-name>
+- append progress, verification, and blockers; do not rewrite descriptions
+- task done on completion; for subtasks move through in_progress first
+- on block: append reason + dependency id + failing command output, then
+  --status blocked
 
-On completion:
-- Append verification evidence.
-- trekoon --toon task done <id>
-- Read and report unblocked tasks, open subtask warnings, and next candidate.
-- For non-trivial code changes, report review result or review gap.
+Assume other agents may edit unrelated files. Do not revert unrelated changes.
 
-If blocked:
-- Append blocker reason, dependency id, and exact failing command/output.
-- trekoon --toon task update <id> --append "Blocked by <reason>" --status blocked
+Claude Code parallel tool calls:
+- Parallel Trekoon Bash calls must stay read-only (session, progress, ready,
+  suggest, targeted show).
+- Do not issue multiple status-changing Bash commands in one parallel batch.
+  Use task/subtask claim for atomic races, then serialize updates and
+  completion commands.
+- If a parallel batch reports sibling cancellation, re-read the affected task
+  before retrying; recover from current Trekoon state.
 
 Use --compact in noisy Trekoon reads. Do not create branches, commits, pushes,
 or PRs unless the user explicitly asked and harness policy allows it.
 
-Claude Code parallel tool calls:
-- Parallel Trekoon Bash calls are for read-only commands such as session,
-  progress, ready, suggest, and targeted show.
-- Do not issue multiple Trekoon status-changing Bash commands in one parallel
-  tool batch. Use task/subtask claim for atomic races, then serialize updates
-  and completion commands.
-- If a parallel batch reports sibling cancellation, re-read the affected task or
-  subtask before retrying; recover from current Trekoon state, not the cancelled
-  command text.
-
 Final report: tasks completed, files changed, checks, review result/gap,
 task done response, blockers.
 ```
@@ -144,26 +135,13 @@ lanes are already delegated.
 2. If diagnostics show `recoveryRequired`, stop and run `trekoon --toon init`.
 3. If behind or conflicts exist, resolve sync before claiming work. Load
    `reference/sync.md` for conflict handling.
-4. Claim:
-   ```bash
-   trekoon --toon task claim <task-id> --owner <name>
-   ```
-5. Work and append notes:
-   ```bash
-   trekoon --toon task update <task-id> --append "Started implementation"
-   ```
-6. Update important subtasks explicitly:
+4. Claim, append, finish per the recipe in `reference/harness-primitives.md`.
+5. Update important subtasks explicitly:
    ```bash
    trekoon --toon subtask claim <subtask-id> --owner <name>
    trekoon --toon subtask update <subtask-id> --append "Verified with fixture set" --status done
    ```
-7. Finish or block:
-   ```bash
-   trekoon --toon task update <task-id> --append "Completed implementation and checks"
-   trekoon --toon task done <task-id>
-   trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
-   ```
-8. Repeat from the returned `unblocked`/`next` data. A fresh `session` is not
+6. Repeat from the returned `unblocked`/`next` data. A fresh `session` is not
    needed mid-loop unless you need updated diagnostics or switch epics.
 
 If `task done` warns about open subtasks, decide whether the task is genuinely
@@ -195,27 +173,21 @@ All applicable checks must pass before marking the epic done.
 ### Review
 
 For non-trivial implementation, run a separate review pass before closing the
-task or epic. Prefer a specialized review agent/skill when available. Review
-the actual diff for correctness, regressions, missing tests, security,
-reliability, performance, and integration risks. Tiny docs/mechanical changes
-may skip separate review, but record that decision.
-
-### Tests and Manual Checks
-
-- Run the relevant automated tests for touched scope.
-- Run broader tests when shared behavior, cross-module contracts, or user flows
-  changed.
-- Exercise CLI/API/parser/integration changes with realistic inputs when
-  possible.
+task or epic. Prefer a specialized review agent/skill. Review the diff for
+correctness, regressions, missing tests, security, reliability, performance,
+and integration risks. Tiny docs/mechanical changes may skip separate review
+but record that decision.
+
+### Tests And Manual Checks
+
+- Run relevant automated tests for touched scope.
+- Run broader tests when shared behavior or cross-module contracts changed.
+- Exercise CLI/API/parser/integration changes with realistic inputs.
 - Record gaps when credentials or external services are unavailable.
 - Fix confusing errors, noisy output, inconsistent behavior, or rough DX.
 
-Append evidence:
-
-```bash
-trekoon --toon task update <task-id> --append "Verified: <commands/results>"
-trekoon --toon task update <task-id> --append "Review: <result or accepted gap>"
-```
+Append evidence with the `task update --append` recipe in
+`reference/harness-primitives.md`.
 
 ## Close The Epic
 
@@ -238,7 +210,7 @@ remaining blockers, and dependency state.
 
 ## Update And Read Policies
 
-Use descriptions as the durable work log. Append progress instead of rewriting
+Descriptions are the durable work log. Append progress instead of rewriting
 descriptions unless the plan itself is wrong.
 
 Preferred commands:
@@ -265,3 +237,35 @@ Bulk updates:
 - `--append` and `--description` are mutually exclusive.
 - Use `--all` only for clear maintenance sweeps or when the user explicitly
   wants broad updates.
+
+## Claude Agent Teams (Appendix)
+
+Use this section only when the user explicitly asks for Claude Code Agent
+Teams and `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`. Otherwise use the
+standard subagent flow above.
+
+Team-specific surface:
+
+| Purpose | Tool |
+|---|---|
+| Create team | `TeamCreate` |
+| Manage shared tasks | `TaskCreate` / `TaskList` / `TaskUpdate` / `TaskGet` |
+| Spawn teammates | `Agent` with `team_name` |
+| Communicate | `SendMessage` |
+| Clean up | `TeamDelete` |
+
+Flow:
+
+1. Build the graph and mark the epic in progress per the standard flow.
+2. `TeamCreate` with name `<epic-slug>` and a description naming the epic.
+3. One `TaskCreate` per lane. Reuse the standard subagent prompt body
+   (claim, append, task done, blocker handling). Use `blockedBy` for
+   sequential lanes.
+4. `Agent` with `team_name` to spawn one teammate per parallel lane.
+   Use `general-purpose`; reserve `Explore`/`Plan` for read-only research.
+   Use 3-5 teammates for most epics.
+5. Coordinate via `SendMessage`. Update Trekoon owners with
+   `task update <task-id> --owner <teammate-name>`. When all teammates
+   block, run `suggest --epic <epic-id>`.
+6. Close the epic per the standard flow. Then `shutdown_request` each
+   teammate and `TeamDelete`.

package/.agents/skills/trekoon/reference/harness-primitives.md

@@ -78,3 +78,40 @@ checks and record the review gap or decision:
 ```bash
 trekoon --toon task update <task-id> --append "Review: <summary or accepted gap>"
 ```
+
+## Atomic Claim And Append-Progress Recipe
+
+Canonical recipe for owning a Trekoon item and recording progress. Other
+references point here instead of restating these commands.
+
+Atomic claim before editing:
+
+```bash
+trekoon --toon task claim <task-id> --owner <name>
+trekoon --toon subtask claim <subtask-id> --owner <name>
+```
+
+`task claim` races safely across parallel subagents; the loser sees the
+existing owner. `task update --status in_progress` does not race; prefer
+`claim` for ownership transitions.
+
+Append progress, verification, blocker notes:
+
+```bash
+trekoon --toon task update <task-id> --append "Started implementation"
+trekoon --toon task update <task-id> --append "Verified: <commands/results>"
+trekoon --toon task update <task-id> --append "Review: <result or accepted gap>"
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
+```
+
+Append, do not rewrite descriptions. Use `--ids <csv>` for bulk append; bulk
+mode supports only `--append` and/or `--status`.
+
+Finish:
+
+```bash
+trekoon --toon task done <task-id>
+```
+
+`task done` auto-walks `todo` or `blocked` through `in_progress`. For subtasks,
+move through `in_progress` (claim or status) before `done`.

package/.agents/skills/trekoon/reference/planning.md

@@ -94,29 +94,25 @@ Can run in parallel with: billing-lane. Blocked by: task-types.
 
 ## Design For Delegated Execution
 
-Plan so meaningful independent work can run in subagents:
-
 - Tasks with no dependency edge are parallel candidates.
 - Different subsystems usually become different lanes.
 - Same subsystem work should usually be grouped or sequenced.
-- Keep each active subsystem lane to about 3-4 tasks.
-- Add owners after creation when lanes are clear:
+- Keep each active lane to about 3-4 tasks.
+- Add owners after creation:
   ```bash
-  trekoon --toon task update <task-id> --owner auth-lane
-  trekoon --toon task update <task-id> --owner billing-lane
+  trekoon --toon task update <task-id> --owner <lane-name>
   ```
 
-Use dependencies only for hard prerequisites. Prefer task-to-task dependencies.
-Use subtask dependencies only when task-level ordering is too coarse.
+Use dependencies for hard prerequisites only. Prefer task-to-task; use subtask
+dependencies only when task-level ordering is too coarse.
 
 ## Create Records Efficiently
 
-Use `--toon` on every planning command. It saves tokens and gives agents a
-stable structured response.
+Use `--toon` on every planning command for stable structured responses.
 
-Prefer one transactional planning command over repeated single-item creates. If
-you know the epic, tasks, subtasks, and dependencies, one-shot the whole epic
-with `epic create --task ... --subtask ... --dep ...`. This saves tool calls and
+Prefer one transactional command over repeated single-item creates. If the
+epic, tasks, subtasks, and dependencies are known, one-shot with
+`epic create --task ... --subtask ... --dep ...`. This saves tool calls and
 keeps the graph internally consistent.
 
 | Situation | Command |
@@ -138,80 +134,89 @@ Compact specs use pipe-delimited values. `\` is the escape character:
 | `\r` | carriage return |
 | `\t` | tab |
 
-Any other `\X` is invalid. Do not paste regex-escaped or shell-escaped
-patterns directly into compact specs: sequences like `\?`, `\.`, `\{`, `\}`,
-`\(`, `\)`, `\[`, and `\]` will fail before records are created. When a task
-description needs a search pattern, prefer prose over exact regex syntax. Avoid
-operators like `!=` in descriptions because shell or compact-spec escaping can
-be confusing; rephrase as words.
-
-Good:
-
-```text
-Verify: search docs for currentUpdatedAt, updatedAt-ms, SSE auth token rides, and token query contract text.
-```
-
-Bad:
-
-```text
-Verify: search with regex "currentUpdatedAt|<updatedAt-ms>|/api/snapshot/stream\?token|\?token=\{token\}" in docs and README.md
-```
+Any other `\X` is invalid. Do not paste regex/shell-escaped patterns into
+compact specs: `\?`, `\.`, `\{`, `\(`, `\[` etc. fail before records are
+created. Prefer prose over exact regex in descriptions. Rephrase operators
+like `!=` as words to avoid escaping confusion.
+
+Bare `|` inside field values is a field separator and will silently corrupt
+records when the spec omits an explicit `|<status>` field. A single shell
+pipe (`cmd a | cmd b`) in a Verify line on a 3-field task spec or 4-field
+subtask spec (epic create/expand) splits into one extra field, and the parser
+treats that trailing fragment as the status — but does not validate it.
+Creation succeeds and the record only breaks on the next status transition.
+Concrete failure: `--task "task-x|API|Verify: bun test foo | tail -20"`
+splits to `[task-x, API, "Verify: bun test foo ", " tail -20"]`; ` tail -20`
+becomes the status, and the bad status only surfaces on the next update.
+
+Escape literal `|` as `\|` or rephrase to avoid the character. `||` fallbacks
+(`cmd a || cmd b`) and other multi-pipe constructs are caught loudly by the
+parser: every unescaped `|` adds a field, so multi-pipe input overshoots the
+field-count gate and fails before any record is written. The empty-field gate
+fires on a different shape — a single bare middle pipe like
+`key|title||desc`. Either way, the silent failure mode is specifically the
+single-pipe / no-explicit-status case. Specs that already pass `|<status>`
+fail loudly even on a single unescaped `|`.
+
+Spec shape (status optional, defaults to `todo`):
+
+- `--task <temp-key>|<title>|<description>` or `<temp-key>|<title>|<description>|<status>`
+- `--subtask <temp-key>|<title>|<description>` or `<temp-key>|<title>|<description>|<status>` (subtask create-many)
+- `--subtask <parent-ref>|<temp-key>|<title>|<description>` or `<parent-ref>|<temp-key>|<title>|<description>|<status>` (epic create/expand)
+
+Prefer the shorter form. Pass an explicit `|<status>` only when seeding a
+non-`todo` status.
 
 One-shot rules:
 
-- Declare tasks/subtasks with plain temp keys, e.g. `task-api`, `sub-tests`.
-- Refer to records created in the same command as `@task-api` or `@sub-tests`.
+- Declare tasks/subtasks with plain temp keys, e.g. `task-api`, `sub-api-tests`.
+- Temp keys form a flat namespace per command. Every `--task` and `--subtask`
+  key must be unique across the whole `epic create` / `epic expand` call, not
+  per parent task. Prefix subtask keys with the parent task key
+  (`sub-api-tests`, `sub-ui-states`) to stay safe across re-runs.
+- Refer to records created in the same command as `@task-api` or
+  `@sub-api-tests`.
 - Use `@task-key` as the subtask parent ref and in `--dep` specs.
 - `--dep <source>|<depends-on>` points from blocked item to prerequisite.
 - `epic create` returns `result.mappings` and counts. Use those real UUIDs in
   handoff summaries and follow-up updates. Never show temp keys as real IDs.
 - `dep add-many` does not resolve temp keys from earlier commands. Use real IDs.
 
-One-shot example:
+One-shot example (status omitted, defaults to `todo`):
 
 ```bash
 trekoon --toon epic create \
   --title "Checkout: add idempotent payment capture" \
   --description "Goal: prevent duplicate charges.\nVerification: bun test tests/payments" \
-  --task "task-api|[API] add capture endpoint|Target files: src/payments/capture.ts\nRead first: src/payments/service.ts\nDo not touch: src/ui/*\nAcceptance: duplicate request returns prior result.\nVerify: bun test tests/payments/capture.test.ts\nOwner: api-lane\nCan run in parallel with: task-ui.|todo" \
-  --task "task-ui|[UI] show capture states|Target files: src/ui/checkout.tsx\nRead first: src/ui/form.tsx\nDo not touch: src/payments/*\nAcceptance: loading and retry states render.\nVerify: bun test tests/ui/checkout.test.ts\nOwner: ui-lane\nBlocked by: task-api.|todo" \
-  --subtask "@task-api|sub-api-tests|Write capture tests|Cover idempotent retry and conflict responses.|todo" \
-  --subtask "@task-ui|sub-ui-states|Write UI state tests|Cover loading, success, retry, and error states.|todo" \
+  --task "task-api|[API] add capture endpoint|Target files: src/payments/capture.ts\nRead first: src/payments/service.ts\nDo not touch: src/ui/*\nAcceptance: duplicate request returns prior result.\nVerify: bun test tests/payments/capture.test.ts\nOwner: api-lane\nCan run in parallel with: task-ui." \
+  --task "task-ui|[UI] show capture states|Target files: src/ui/checkout.tsx\nRead first: src/ui/form.tsx\nDo not touch: src/payments/*\nAcceptance: loading and retry states render.\nVerify: bun test tests/ui/checkout.test.ts\nOwner: ui-lane\nBlocked by: task-api." \
+  --subtask "@task-api|sub-api-tests|Write capture tests|Cover idempotent retry and conflict responses." \
+  --subtask "@task-ui|sub-ui-states|Write UI state tests|Cover loading, success, retry, and error states." \
   --dep "@task-ui|@task-api"
 ```
 
 ## Append Efficiently
 
-Use `--append` for progress notes, shared findings, verification requirements,
-or planning refinements. Appending is cheaper and safer than rewriting full
-descriptions.
+Use the append-progress recipe from `reference/harness-primitives.md` for
+planning notes, shared findings, verification, or refinements. Appending is
+cheaper and safer than rewriting full descriptions.
 
-Entity-specific append:
-
-```bash
-trekoon --toon epic update <epic-id> --append "Planning note: <text>"
-trekoon --toon task update <task-id> --append "Planning note: <text>"
-trekoon --toon subtask update <subtask-id> --append "Planning note: <text>"
-```
-
-Append to selected tasks or subtasks with IDs from `result.mappings`:
+Bulk append uses IDs from `result.mappings`, `epic show --all`, or
+`task ready`:
 
 ```bash
 trekoon --toon task update --ids id1,id2,id3 --append "Shared verification: bun test tests/payments"
-trekoon --toon subtask update --ids id1,id2 --append "Shared note: follow capture endpoint contract"
 ```
 
 Important:
 
 - `epic update <epic-id> --append ...` appends only to the epic description.
-- There is no scoped "append to all tasks in this epic" command. Use task IDs
-  from one-shot mappings, `epic show --all`, or `task ready`, then
-  `task update --ids ... --append ...`.
+- There is no scoped "append to all tasks in this epic" command.
 - Do not use `task update --all --append ...` unless you truly mean every task
   in the database.
 - `epic update <epic-id> --all` is cascade status mode only and rejects
   `--append`.
-- Bulk append is per-row, not one atomic transaction.
+- Bulk append is per-row, not atomic.
 
 ## Validate Before Handoff
 
@@ -234,15 +239,11 @@ Verify:
 
 ## Handoff Summary
 
-Do not stop at a prose-only design. Return the actual Trekoon epic and first
-execution wave.
+Return the actual Trekoon epic and first execution wave, not prose-only design.
 
-Rules:
-
-- Always use full UUIDs for epic/task IDs in summaries.
-- Never use temp keys (`task-api`, `@sub-tests`) outside create commands.
+- Full UUIDs in summaries; never temp keys outside create commands.
 - Render IDs in code formatting.
-- Group tasks by wave with title, owner/lane, and dependencies.
+- Group tasks by wave with title, owner/lane, dependencies.
 - Include final verification gate.
 
 Format:
@@ -266,16 +267,9 @@ Verification: bun run build && bun run test
 
 ## Search And Replace
 
-Use scoped search before manual tree reads when locating repeated paths, labels,
-owners, or migration targets.
-
-Narrowest valid scope first:
-
-1. `subtask search` / `subtask replace`
-2. `task search` / `task replace`
-3. `epic search` / `epic replace`
-
-Workflow:
+Use scoped search before manual tree reads for repeated paths, labels, owners,
+or migration targets. Narrowest scope first:
+`subtask search`/`replace`, then `task`, then `epic`.
 
 ```bash
 trekoon --toon epic search <epic-id> "path/to/somewhere"

package/README.md

@@ -194,6 +194,33 @@ Trekoon enforces valid transitions. You can't skip straight from `todo` to
 Exception: `task done` auto-transitions through `in_progress`, so agents can
 call it from any non-done status.
 
+## Storage and durability
+
+Trekoon stores all state in `.trekoon/trekoon.db` (SQLite, WAL mode). The
+database file lives outside the git object store; never commit it. Open-time
+PRAGMAs are tuned for read+write throughput:
+
+- `journal_mode = WAL` — required for concurrent readers + a single writer.
+- `synchronous = NORMAL` — paired with WAL per the
+  [SQLite recommendation](https://www.sqlite.org/wal.html#performance_considerations).
+  On a hard kernel/OS crash, the last few unfsynced transactions may be lost,
+  but the database file itself never corrupts. To restore the pre-tuning
+  behaviour (`synchronous = FULL`), set `TREKOON_SQLITE_DURABILITY=full`
+  before invoking any `trekoon` command.
+- `temp_store = MEMORY`, `mmap_size = 256 MiB`, `wal_autocheckpoint = 1000` —
+  keep hot reads in-process and bound the WAL size under sustained writes.
+- `cache_size` — defaults to 64 MiB per connection. Override with
+  `TREKOON_SQLITE_CACHE_MIB=<N>` (non-negative integer). In daemon mode
+  (`trekoon serve`) up to 16 connections may be cached simultaneously, so
+  peak page-cache usage approaches `CACHED_DATABASES_CAPACITY × cache_size`
+  (e.g. 16 × 64 MiB = 1 GiB at the default). Lower `TREKOON_SQLITE_CACHE_MIB`
+  when memory is constrained (e.g. `TREKOON_SQLITE_CACHE_MIB=16` → 256 MiB
+  total for a 16-handle daemon).
+
+These pragmas apply per open connection. Recovery path on suspected
+corruption: `trekoon migrate backup`, then copy a known-good backup over
+`.trekoon/trekoon.db`.
+
 ## Local board
 
 Trekoon includes a browser-based board for humans who like having a visual
@@ -224,6 +251,7 @@ shell, worktree, or browser tab show up live without a manual refresh.
 | Create tasks in bulk | `trekoon task create-many ...` |
 | Add dependencies | `trekoon dep add-many ...` |
 | Start an agent session | `trekoon session --epic <id>` |
+| Resolve any epic/task/subtask id | `trekoon session --item <id>` |
 | Get next-action suggestions | `trekoon suggest --epic <id>` |
 | Check epic progress | `trekoon epic progress <id>` |
 | Export epic to Markdown | `trekoon epic export <id>` |