trekoon 0.4.0 → 0.4.2

package/.agents/skills/trekoon/reference/execution-with-team.md

@@ -63,7 +63,7 @@ TaskCreate:
 
     Before starting each task:
     - claim and assign owner:
-      trekoon --toon task update <id> --status in_progress --owner <lane-name>
+      trekoon --toon task claim <id> --owner <lane-name>
     - append a short start note:
       trekoon --toon task update <id> --append "Starting implementation"
 
@@ -110,6 +110,9 @@ Agent:
     Use TaskUpdate to claim tasks (set owner to your name) and mark
     them completed.
 
+    Before starting each Trekoon task, claim it in Trekoon:
+      trekoon --toon task claim <trekoon-task-id> --owner <your-name>
+
     Status machine rules:
     - todo -> in_progress -> done (valid)
     - todo -> done (INVALID — use task done which auto-transitions)
@@ -160,14 +163,23 @@ Your job as team lead:
 
 ## Auto-recovery
 
-1. If status update fails with `status_transition_invalid`, check current status
-   and use the valid intermediate transition.
-2. If status update fails with `dependency_blocked`, refresh with
-   `task ready`/`task next` and continue with a ready candidate.
-3. Teammate attempts to fix failures (has context).
-4. If can't fix, teammate reports failure with error output via SendMessage.
-5. Dispatch fix instructions via SendMessage to the teammate.
-6. Same error twice -> stop and ask user.
+Teammate attempts to fix failures. If can't fix, teammate reports failure with
+error output via SendMessage; dispatch fix instructions in response.
+
+**`status_transition_invalid`** — exact recovery sequence:
+1. Run `trekoon --toon --compact task show <id>` to read the current status.
+2. Append a blocker note: `trekoon --toon task update <id> --append "Blocked: status_transition_invalid from <attempted transition>; current status is <actual>"`.
+3. Identify the valid intermediate transition (see `reference/status-machine.md`).
+4. Apply the correct intermediate step, then retry the intended transition.
+5. Only move on to the next task after the target task reaches the intended status or is explicitly marked `blocked`.
+6. Report resolution via SendMessage.
+
+**`dependency_blocked`** — exact recovery sequence:
+1. Run `trekoon --toon --compact task show <id>` to identify which dependency is unmet.
+2. Append a blocker note: `trekoon --toon task update <id> --append "Blocked: dependency_blocked; depends on <dep-id>"`.
+3. Run `trekoon --toon task ready --epic <epic-id>` to get a ready candidate.
+4. Only then continue with the ready candidate — do not retry the blocked task.
+5. Notify team lead via SendMessage with blocker details.
 
 ## Verify and close
 

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

@@ -90,8 +90,8 @@ subtasks:
 - Task <id>: <title>
 
 Before starting each task:
-- set status to in_progress and assign owner:
-  trekoon --toon task update <id> --status in_progress --owner <lane-name>
+- claim and assign owner:
+  trekoon --toon task claim <id> --owner <lane-name>
 - append a short start note:
   trekoon --toon task update <id> --append "Starting implementation"
 
@@ -141,13 +141,19 @@ When a sub-agent calls `task done`, the response includes:
 1. Agent attempts to fix failures (has context).
 2. If can't fix, report failure with error output.
 3. Dispatch fix agent with context.
-4. Same error twice -> stop and ask user.
 
-If a status update fails with `status_transition_invalid`, check current status
-and transition through the valid intermediate step.
+**`status_transition_invalid`** — exact recovery sequence:
+1. Run `trekoon --toon --compact task show <id>` to read the current status.
+2. Append a blocker note: `trekoon --toon task update <id> --append "Blocked: status_transition_invalid from <attempted transition>; current status is <actual>"`.
+3. Identify the valid intermediate transition (see `reference/status-machine.md`).
+4. Apply the correct intermediate step, then retry the intended transition.
+5. Only move on to the next task after the target task reaches the intended status or is explicitly marked `blocked`.
 
-If a status update fails with `dependency_blocked`, refresh with
-`task ready`/`task next` and continue with a ready candidate.
+**`dependency_blocked`** — exact recovery sequence:
+1. Run `trekoon --toon --compact task show <id>` to identify which dependency is unmet.
+2. Append a blocker note: `trekoon --toon task update <id> --append "Blocked: dependency_blocked; depends on <dep-id>"`.
+3. Run `trekoon --toon task ready --epic <epic-id>` to get a ready candidate.
+4. Only then continue with the ready candidate — do not retry the blocked task.
 
 ## Verify before closing
 
@@ -225,3 +231,236 @@ After verification is complete:
 
 Changes should integrate cleanly with existing patterns. If a change fights the
 architecture, refactor first rather than bolt on. The goal is zero tech debt.
+
+## Single-agent execution loop
+
+Use this loop when one agent should continue the work directly. The primary loop
+is: **session → claim → work → task done → repeat**.
+
+### 1. Orient with a single call
+
+```bash
+trekoon --toon session
+```
+
+If you already know which epic you are working on, scope the session:
+
+```bash
+trekoon --toon session --epic <epic-id>
+```
+
+`session` returns diagnostics, sync status, the next ready task with subtrees,
+blocker list, and readiness counts in one envelope. Use `--compact` to reduce
+output size when you do not need contract metadata:
+
+```bash
+trekoon --toon --compact session
+```
+
+**After session returns, follow this decision tree in order:**
+
+1. **`recoveryRequired` is true?** → Stop. Run `trekoon --toon init` and
+   re-check.
+2. **`behind > 0`?** → Sync first: `trekoon --toon sync pull --from main`.
+   This pulls tracker events (not git commits) so task states are current.
+3. **`pendingConflicts > 0`?** → Resolve before claiming work:
+   `trekoon --toon sync conflicts list`. For uniform conflicts, batch resolve:
+   `trekoon --toon sync resolve --all --use ours` (or `--use theirs`). For
+   mixed conflicts, inspect individually with `sync conflicts show <id>` and
+   resolve per-conflict. See `reference/sync.md` for full conflict guidance.
+4. **Session returned a next task?** → Proceed to step 2 (claim work).
+5. **No next task and unsure what to do?** → Run `trekoon --toon suggest` for
+   priority-ranked recommendations (see step 1b below).
+
+### 1b. Get suggestions when stuck
+
+When the session has no clear next task, or you are unsure what action to take:
+
+```bash
+trekoon --toon suggest
+trekoon --toon suggest --epic <epic-id>
+```
+
+`suggest` inspects recovery state, sync status, readiness, and epic progress,
+then returns up to 3 suggestions ranked by priority. Each suggestion includes a
+category (`recovery`, `sync`, `execution`, `planning`), a reason, and a
+ready-to-run command you can execute directly.
+
+Suggest respects the status machine — it will never recommend an invalid
+transition. Use it:
+- At session start when `readyCount` is 0 and you need guidance.
+- Mid-loop when all tasks are blocked and you need to decide what to unblock.
+- Before closing an epic to confirm the right next step.
+
+### 1c. Check epic progress
+
+When you need a quick dashboard before or during work on an epic:
+
+```bash
+trekoon --toon epic progress <epic-id>
+```
+
+Returns done/in_progress/blocked/todo counts, ready task count, and the next
+candidate. Use this:
+- Before starting a work session to gauge how much remains.
+- After completing several tasks to report progress to the user.
+- To decide whether an epic is ready to be marked done.
+
+### 2. Claim work explicitly
+
+Once you know which task to work on, claim it atomically with `task claim`.
+`--owner` is required:
+
+```bash
+trekoon --toon task claim <task-id> --owner <name>
+```
+
+`task claim` sets `status=in_progress` and `owner=<name>` in a single
+compare-and-swap. It succeeds only when the task is in `todo` or `blocked`
+and is not already claimed by a different owner.
+
+For other (non-claim) status transitions such as moving to `blocked`, use
+`task update --status`:
+
+```bash
+trekoon --toon task update <task-id> --status blocked
+```
+
+To update ownership separately (e.g. reassign without claiming):
+
+```bash
+trekoon --toon task update <task-id> --owner alice
+trekoon --toon subtask update <subtask-id> --owner bob
+```
+
+### 3. Work on the task
+
+While working, append progress notes:
+
+```bash
+trekoon --toon task update <task-id> --append "Started implementation"
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
+```
+
+### 3b. Work on subtasks explicitly when they matter
+
+Use the same status discipline for subtasks when a task depends on concrete
+subtask progress:
+
+```bash
+trekoon --toon subtask claim <subtask-id> --owner <name>
+trekoon --toon subtask update <subtask-id> --append "Implemented parser branch"
+trekoon --toon subtask update <subtask-id> --append "Verified with fixture set" --status done
+trekoon --toon subtask update <subtask-id> --append "Blocked by <reason>" --status blocked
+```
+
+Use subtasks for real execution units, not filler. If a task has open subtasks
+when `task done` is called, treat the warning as a prompt to consciously decide
+whether the task is genuinely complete.
+
+### 4. Finish or report a block
+
+When done, append a completion note then mark done:
+
+```bash
+trekoon --toon task update <task-id> --append "Completed implementation and checks"
+trekoon --toon task done <task-id>
+```
+
+`task done` works from any non-done status (`todo`, `in_progress`, `blocked`).
+It auto-transitions through `in_progress` when needed. The response includes:
+
+- **Next candidate**: the next ready task with its full tree and blockers.
+- **Unblocked tasks**: downstream tasks that became ready after this completion.
+  Use this to decide what to claim next or to launch parallel work.
+- **Open subtask warning**: if subtasks remain incomplete (completion still
+  proceeds, but the warning is surfaced so you can decide whether to go back).
+
+If blocked instead of done:
+
+```bash
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
+```
+
+### 5. Repeat
+
+After `task done`, the returned next-task envelope is sufficient to continue
+the loop from step 2. A fresh `session` call is not required mid-loop unless
+you need updated diagnostics, sync status, or want to switch epics.
+
+Run `session` again at the start of each new conversation session.
+
+**When to use each command during the loop:**
+
+| Situation | Command |
+|---|---|
+| Start of session | `session` or `session --epic <id>` |
+| Unsure what to do next | `suggest` or `suggest --epic <id>` |
+| Quick progress check | `epic progress <epic-id>` |
+| Claim a task | `task claim <id> --owner <name>` |
+| Assign ownership | `task update <id> --owner <name>` |
+| Log progress | `task update <id> --append "..."` |
+| Mark done | `task done <id>` |
+| Report blocker | `task update <id> --append "..." --status blocked` |
+| Reduce output noise | Add `--compact` to any command |
+
+## Update policy: prefer append-based progress logging
+
+Use descriptions as the durable work log. For progress updates, append instead
+of rewriting full descriptions.
+
+Status transitions must follow the status machine. Use `in_progress` as the
+intermediate step to reach `done`. Direct `todo → done` is invalid via
+`task update`; use `task done` instead, which auto-transitions.
+
+### Preferred patterns
+
+```bash
+trekoon --toon task claim <task-id> --owner <name>
+trekoon --toon task update <task-id> --append "Started implementation"
+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
+trekoon --toon task update <task-id> --owner alice
+```
+
+### Bulk update rules
+
+- Bulk update is available for `epic update`, `task update`, and
+  `subtask update`.
+- Bulk mode uses `--ids <csv>` or `--all`.
+- Bulk mode supports only `--append` and/or `--status`.
+- Do not pass a positional ID in bulk mode.
+- `--append` and `--description` are mutually exclusive.
+- Prefer `--ids` for narrow, explicit updates.
+- Use `--all` only for clear maintenance sweeps or when the user explicitly wants
+  a broad update.
+
+Examples:
+
+```bash
+trekoon --toon task update --ids id1,id2 --append "Waiting on release" --status blocked
+trekoon --toon epic update --ids epic1,epic2 --append "Sprint planning refreshed" --status in_progress
+```
+
+## Read policy: use the smallest sufficient read
+
+Use the narrowest command that answers the question.
+
+| Need | Preferred command |
+|---|---|
+| Session startup (diagnostics + sync + next task) | `trekoon --toon session` |
+| Session scoped to one epic | `trekoon --toon session --epic <epic-id>` |
+| Next-action suggestions | `trekoon --toon suggest` |
+| Epic progress dashboard | `trekoon --toon epic progress <epic-id>` |
+| Next task only | `trekoon --toon task next` |
+| A few ready options | `trekoon --toon task ready --limit 5` |
+| Direct blockers for one task | `trekoon --toon dep list <task-id>` |
+| What this item unblocks | `trekoon --toon dep reverse <task-or-subtask-id>` |
+| One full task payload | `trekoon --toon task show <task-id> --all` |
+| One full epic tree | `trekoon --toon epic show <epic-id> --all` |
+| Repeated text in one scope | `trekoon --toon epic\|task\|subtask search ...` |
+
+Avoid broad scans such as `task list --all` or `epic show --all` when
+`task next`, `task ready`, `dep list`, `dep reverse`, `suggest`, or `search`
+can answer the question more cheaply.

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

@@ -58,7 +58,8 @@ creating the graph.
 - **Dependency edge** = strict prerequisite only (do not add "nice to have"
   dependencies).
 
-All entities start in `todo`. See the status machine in the main SKILL.md.
+All entities start in `todo`. See `reference/status-machine.md` for the
+canonical transition table.
 
 Plan implications:
 - Never set initial status to anything other than `todo` in create commands.
@@ -290,3 +291,139 @@ in task descriptions:
 
 For large scope, create multiple epics with explicit cross-epic boundaries. Use
 dependencies within each epic DAG and keep each epic executable in bounded time.
+
+## Creation policy: prefer bulk planning workflows
+
+When creating multiple related records, do not loop through repeated single-item
+creates unless only one record is needed.
+
+### Which command to use
+
+| Situation | Preferred command |
+|---|---|
+| New epic and full graph already known | `trekoon --toon epic create ... --task ... --subtask ... --dep ...` |
+| Existing epic needs linked additions | `trekoon --toon epic expand <epic-id> ...` |
+| Multiple sibling tasks under one epic | `trekoon --toon task create-many --epic <epic-id> --task ...` |
+| Multiple sibling subtasks under one task | `trekoon --toon subtask create-many <task-id> --subtask ...` |
+| Multiple dependency edges across existing IDs | `trekoon --toon dep add-many --dep ...` |
+| One record only | `epic create`, `task create`, or `subtask create` |
+
+### Compact spec escaping rules
+
+Compact specs (pipe-delimited `--task`, `--subtask`, `--dep` values) use `\` as
+the escape character. Only these sequences are valid:
+
+| Sequence | Produces |
+|---|---|
+| `\|` | literal `\|` (not a field separator) |
+| `\\` | literal `\` |
+| `\n` | newline |
+| `\r` | carriage return |
+| `\t` | tab |
+
+Any other `\X` combination (e.g., `\!`, `\=`, `\$`) is rejected with
+`Invalid escape sequence`. To avoid accidental escapes:
+
+- Do not use `!=` or similar operators in description text; rephrase instead
+  (e.g., "null does not equal sourceBranch" instead of "null !== sourceBranch").
+- If a literal backslash is needed, double it: `\\`.
+- When using shell line continuations (`\` at end of line), ensure the next
+  line's first character is not one that forms an invalid escape with `\`.
+
+### Critical temp-key rule
+
+- Use plain temp keys when declaring records in compact specs, for example
+  `task-api` or `sub-tests`.
+- Refer to those records later in the same invocation as `@task-api` or
+  `@sub-tests`.
+- `@temp-key` references work in same-invocation graph workflows such as
+  one-shot `epic create` and `epic expand`.
+- `dep add-many` does **not** resolve temp keys from earlier commands. Use real
+  persisted IDs there.
+
+### Compact examples
+
+#### One-shot epic creation
+
+Use this when the epic does not exist yet and you already know the tree.
+
+```bash
+trekoon --toon epic create \
+  --title "Batch command rollout" \
+  --description "Ship linked planning in one transaction" \
+  --task "task-api|Design API|Define compact grammar|todo" \
+  --task "task-cli|Wire CLI|Hook parser and output|todo" \
+  --subtask "@task-api|sub-tests|Write tests|Cover parser cases|todo" \
+  --dep "@task-cli|@task-api"
+```
+
+#### Expand an existing epic
+
+Use this when the epic already exists and the new batch needs internal links.
+
+```bash
+trekoon --toon epic expand <epic-id> \
+  --task "task-docs|Document workflow|Write operator guide|todo" \
+  --subtask "@task-docs|sub-examples|Add examples|Show canonical flows|todo" \
+  --dep "@sub-examples|@task-docs"
+```
+
+#### Create sibling tasks or subtasks
+
+```bash
+trekoon --toon task create-many --epic <epic-id> \
+  --task "seed-api|Design API|Define grammar|todo" \
+  --task "seed-cli|Wire CLI|Hook output|todo"
+
+trekoon --toon subtask create-many <task-id> \
+  --subtask "seed-tests|Write tests|Cover happy path|todo" \
+  --subtask "seed-docs|Document flow|Add notes|todo"
+```
+
+#### Add dependencies after records already exist
+
+```bash
+trekoon --toon dep add-many \
+  --dep "<task-b>|<task-a>" \
+  --dep "<subtask-c>|<task-b>"
+```
+
+## Search and replace policy
+
+Use scoped search before manual tree reads when you need to locate repeated
+paths, labels, owners, or migration targets.
+
+### Scope choice
+
+Prefer the narrowest valid root:
+
+1. `subtask search` or `subtask replace`
+2. `task search` or `task replace`
+3. `epic search` or `epic replace`
+
+Scope behavior:
+
+- `subtask` scope scans only that subtask.
+- `task` scope scans the task plus descendant subtasks.
+- `epic` scope scans the epic plus descendant tasks and subtasks.
+
+### Safe replace workflow
+
+1. Search first.
+2. Preview replace.
+3. Apply only after preview matches the intended scope.
+
+```bash
+trekoon --toon epic search <epic-id> "path/to/somewhere"
+trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path"
+trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply
+```
+
+Guardrails:
+
+- Use literal, explicit search text.
+- Narrow fields when useful: `--fields title`, `--fields description`, or
+  `--fields title,description`.
+- Do not jump straight to `--apply`.
+- Prefer scoped search/replace over manually reading a whole tree and editing
+  many records one by one.

package/.agents/skills/trekoon/reference/status-machine.md

@@ -0,0 +1,21 @@
+# Status Machine Reference
+
+Trekoon enforces a status transition graph. Only these transitions are valid:
+
+| From | Allowed targets |
+|---|---|
+| `todo` | `in_progress`, `blocked` |
+| `in_progress` | `done`, `blocked` |
+| `blocked` | `in_progress`, `todo` |
+| `done` | `in_progress` |
+
+Invalid transitions (e.g. `todo → done`) return error code
+`status_transition_invalid`. Always transition through `in_progress` to reach
+`done`.
+
+**Exception:** `task done` auto-transitions through `in_progress` when the task
+is in `todo` or `blocked` status, so you can call `task done` from any
+non-done status.
+
+Recommended statuses for consistent workflows: `todo`, `in_progress`, `done`.
+Use `blocked` with an appended reason when work is stuck.

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

@@ -0,0 +1,129 @@
+# Sync Reference
+
+## Sync reminders
+
+Same-branch sync is a no-op: `sync pull --from main` while on `main` produces
+zero conflicts and simply advances the cursor. `sync status` returns `behind=0`
+on the source branch. No action is needed.
+
+Cross-branch sync matters before merging a feature branch back:
+
+- Before merge, pull tracker events from the base branch:
+
+  ```bash
+  trekoon --toon sync pull --from main
+  ```
+
+- If conflicts exist, inspect and resolve them explicitly:
+
+  ```bash
+  trekoon --toon sync conflicts list
+  trekoon --toon sync conflicts show <conflict-id>
+  trekoon --toon sync resolve <conflict-id> --use theirs --dry-run
+  trekoon --toon sync resolve <conflict-id> --use ours
+  ```
+
+### Conflict resolution: ours vs theirs
+
+Conflicts are **field-level**, not whole-record. Each conflict targets one field
+(e.g., `status`, `title`, `description`) on one entity.
+
+- `--use ours` — keep the current entity field value in the shared DB. The
+  entity is not written, but the conflict record is marked resolved and a
+  resolution event is appended.
+- `--use theirs` — overwrite the shared DB entity field with the source-branch
+  value. The conflict record is marked resolved and a resolution event is
+  appended.
+- `--dry-run` — preview the resolution without mutating the database. Returns
+  `oursValue`, `theirsValue`, `wouldWrite`, and `dryRun: true`. Use this before
+  committing to a resolution.
+
+**Example:** after `sync pull --from main`, a conflict appears on epic `abc123`,
+field `status`:
+- ours (current DB): `in_progress`
+- theirs (source branch): `done`
+- `--use ours` keeps status as `in_progress`
+- `--use theirs` changes status to `done` in the live shared DB
+
+Always inspect conflicts with `sync conflicts show` before resolving. Choosing
+`theirs` without inspection can overwrite in-progress work in the shared DB.
+
+### Understanding why conflicts happen
+
+| Scenario | Typical resolution | Why |
+|---|---|---|
+| Completed work vs stale main state | ours | Your branch has the latest progress |
+| Enriched descriptions vs original | ours | Your descriptions are more detailed |
+| Upstream updates from another agent | theirs | Accept the newer upstream state |
+| User-intentional reset | theirs | Respect the user's explicit action |
+
+### Agent decision framework
+
+1. List conflicts: `trekoon --toon sync conflicts list`
+2. Group by pattern — are conflicts on the same field or direction?
+3. If uniform pattern, batch resolve: `trekoon --toon sync resolve --all --use ours`
+4. If mixed, narrow by entity or field, or inspect individually
+5. When unsure, ask the user
+
+### Batch resolve patterns
+
+Common scenarios:
+
+```bash
+# Resolve all conflicts at once (most common after completing work)
+trekoon --toon sync resolve --all --use ours
+
+# Preview before resolving
+trekoon --toon sync resolve --all --use ours --dry-run
+
+# Narrow to status field conflicts only
+trekoon --toon sync resolve --all --use ours --field status
+
+# Narrow to a specific entity
+trekoon --toon sync resolve --all --use theirs --entity <id>
+
+# Combine filters
+trekoon --toon sync resolve --all --use ours --entity <id> --field description
+```
+
+## Shared-database model
+
+Trekoon uses **one live SQLite database per repository**. The file lives at
+`<sharedStorageRoot>/.trekoon/trekoon.db`, where `sharedStorageRoot` is the
+parent of `git rev-parse --git-common-dir` (i.e., the main worktree root).
+
+Key consequences:
+
+- **All linked worktrees share the same database.** A status change in one
+  worktree is immediately visible in every other worktree.
+- **`git checkout` / `git switch` does not change tracker state.** The database
+  is outside the git object store, so switching branches does not roll back or
+  swap task data.
+- **Sync operates on tracker events, not on the database file itself.** Use
+  `sync pull` to import events between branches — never copy or commit the
+  `.db` file.
+
+Treat every write as a mutation of shared repo-wide state, not branch-scoped
+state.
+
+**Conflicts are scoped per worktree + branch.** `sync_conflicts` rows are
+recorded with the originating worktree path and current branch, so resolving a
+conflict in one worktree never erases a peer worktree's conflict on the same
+entity. `sync conflicts list` and `sync resolve` from a given worktree only
+see and act on rows scoped to that worktree's branch.
+
+## Worktree diagnostics and destructive scope
+
+- Inspect machine-readable storage fields when debugging worktrees:
+  `storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`, and
+  `databaseFile`.
+- `sharedStorageRoot` is the repo-scoped source of truth for `.trekoon` in git
+  worktrees.
+- If `trekoon wipe --yes --toon` is explicitly requested, warn that it deletes
+  shared storage for the entire repository and every linked worktree.
+- Wipe is destructive recovery only; it is never the right fix for a tracked DB
+  or gitignore mistake.
+
+Trekoon stores local state in `.trekoon/trekoon.db`. In git repos and
+worktrees, storage resolves from the shared repository root rather than each
+worktree independently.

package/README.md

@@ -14,12 +14,6 @@ accounts. The database lives in `.trekoon/` inside your repo.
 bun add -g trekoon
 ```
 
-Or via npm (Bun still needs to be installed as the runtime):
-
-```bash
-npm i -g trekoon
-```
-
 ```bash
 trekoon init          # set up .trekoon/ in your repo
 trekoon quickstart    # walkthrough of the basics
@@ -197,7 +191,9 @@ trekoon board update    # refresh assets only
 ```
 
 Binds to `127.0.0.1` only with a per-session token. Gives you an epics
-overview, kanban workspace per epic, task detail modals, and search.
+overview, kanban workspace per epic, task detail modals, and search. The board
+client subscribes to `/api/snapshot/stream` (SSE), so mutations from another
+shell, worktree, or browser tab show up live without a manual refresh.
 
 ## Commands
 
@@ -212,8 +208,13 @@ overview, kanban workspace per epic, task detail modals, and search.
 | Get next-action suggestions | `trekoon suggest --epic <id>` |
 | Check epic progress | `trekoon epic progress <id>` |
 | Export epic to Markdown | `trekoon epic export <id>` |
+| Claim a task atomically | `trekoon task claim <id> --owner <owner>` |
+| Claim a subtask atomically | `trekoon subtask claim <id> --owner <owner>` |
 | Mark a task done | `trekoon task done <id>` |
 | Sync across worktrees | `trekoon sync pull --from main` |
+| Back up the DB before migrations | `trekoon migrate backup` |
+| Reveal full board token | `trekoon board open --reveal-token` |
+| Run experimental daemon | `trekoon serve` (experimental) |
 | Get help | `trekoon [command] -h` |
 
 Every command supports `--toon`, `--json`, `--compact` for structured output.