trekoon 0.3.2 → 0.3.4

package/docs/machine-contracts.md

@@ -1,11 +1,11 @@
 # Machine contracts
 
-Use `--toon` for production agent loops. Use `--json` only when an integration
-explicitly requires JSON.
+Use `--toon` for agent loops. Use `--json` only when an integration explicitly
+requires JSON.
 
 ## Base envelope
 
-All machine responses use the same top-level shape:
+Every machine response uses the same top-level shape:
 
 ```text
 ok: true|false
@@ -16,23 +16,20 @@ metadata:
   requestId: req-<stable-id>
 ```
 
-Most subcommand identifiers are dot-namespaced, such as `task.list` or
-`sync.pull`. Root-level commands may use single-token IDs such as `help`,
-`init`, `quickstart`, `wipe`, or `version`.
+Most subcommand IDs are dot-namespaced (`task.list`, `sync.pull`). Root-level
+commands use single tokens (`help`, `init`, `quickstart`, `wipe`, `version`).
 
-Additional metadata may appear when relevant:
+Additional metadata appears when relevant:
 
 - `metadata.compatibility` when `--compat` mode is active
 - `meta.storageRootDiagnostics` when storage resolves from a non-canonical cwd
 
-## Ready queue contract
+## Ready queue
 
 ```bash
 trekoon --toon task ready --limit 3
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: task.ready
@@ -58,8 +55,6 @@ data:
 trekoon --toon dep reverse <task-or-subtask-id>
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: dep.reverse
@@ -69,22 +64,19 @@ data:
   blockedNodes[]: { id, kind, distance, isDirect }
 ```
 
-## Pagination contract for list calls
+## Pagination
 
 ```bash
 trekoon --toon task list --status todo --limit 2
 trekoon --toon task list --status todo --limit 2 --cursor 2
 ```
 
-Cursor rules:
+Rules:
 
 - `--cursor <n>` is offset-like pagination for `epic list`, `task list`, and
   `subtask list`
-- do not combine `--all` with `--cursor`
-- machine consumers should page using `meta.pagination.hasMore` and
-  `meta.pagination.nextCursor`
-
-Payload fields:
+- Don't combine `--all` with `--cursor`
+- Page using `meta.pagination.hasMore` and `meta.pagination.nextCursor`
 
 ```text
 ok: true
@@ -98,14 +90,14 @@ meta:
   pagination: { hasMore, nextCursor }
 ```
 
-## Descendant cascade update contract
+## Descendant cascade update
 
 ```bash
 trekoon --toon epic update <epic-id> --all --status done
 trekoon --toon task update <task-id> --all --status todo
 ```
 
-Success payload fields for epic/task cascade mode:
+Success:
 
 ```text
 ok: true
@@ -129,7 +121,7 @@ data:
       changedSubtasks
 ```
 
-Failure contract for blocked epic/task cascade mode:
+Failure (blocked descendants):
 
 ```text
 ok: false
@@ -157,16 +149,13 @@ data:
 
 Notes:
 
-- `subtask update <subtask-id> --all --status done|todo` is accepted, but it
-  returns the normal single-subtask `subtask.update` payload because there are
-  no descendants to traverse
-- Cascade mode is reserved for status-only close/reopen operations; combine
-  append/title/description changes in separate commands
+- `subtask update <subtask-id> --all --status done|todo` is accepted but
+  returns the normal single-subtask payload (no descendants to traverse)
+- Cascade is status-only; use separate commands for append/title/description
 
-## Batch create and expand payloads
+## Batch create and expand
 
-Trekoon uses stable batch payloads for one-shot graph creation and sibling batch
-creation commands.
+Stable batch payloads for one-shot graph creation and sibling batch commands.
 
 ### `epic create` and `epic expand`
 
@@ -175,8 +164,6 @@ trekoon --toon epic create --title "..." --description "..." --task "..."
 trekoon --toon epic expand <epic-id> --task "..."
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: epic.create | epic.expand
@@ -197,8 +184,6 @@ data:
 trekoon --toon task create-many --epic <epic-id> --task "..."
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: task.create-many
@@ -215,8 +200,6 @@ data:
 trekoon --toon subtask create-many --task <task-id> --subtask "..."
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: subtask.create-many
@@ -229,57 +212,54 @@ data:
 
 ## Sync compatibility mode
 
-Compatibility mode exists for integrations that still consume legacy sync
-command IDs:
+For integrations that still use legacy sync command IDs:
 
 ```bash
 trekoon --json --compat legacy-sync-command-ids sync status
 trekoon --toon --compat legacy-sync-command-ids sync pull --from main
 ```
 
-Behavior:
+- Default output uses canonical dotted IDs (`sync.status`)
+- Compat mode rewrites to legacy forms (`sync_status`)
+- Machine-only, valid only for `sync` commands
+- Output includes `metadata.compatibility` with migration guidance and removal
+  timing
 
-- default output uses canonical dotted IDs such as `sync.status`
-- compatibility mode rewrites sync command IDs to legacy forms such as
-  `sync_status`
-- compatibility mode is machine-only and valid only for `sync` commands
-- machine output includes `metadata.compatibility` with migration guidance and
-  removal timing
-
-## Compact envelope mode
+## Compact envelope
 
 ```bash
 trekoon --toon --compact task list
 ```
 
-When `--compact` is passed, the `metadata` key is omitted from the TOON/JSON
-envelope. The `ok`, `command`, `data`, `error`, and `meta` keys are unaffected.
+`--compact` omits the `metadata` key from the envelope. `ok`, `command`, `data`,
+`error`, and `meta` are unaffected.
 
-## Status transition error contract
+## Status transition errors
 
-Invalid status transitions return:
+Invalid transitions return:
 
 ```text
 ok: false
 error:
   code: status_transition_invalid
   message: "cannot transition <kind> <id> from '<from>' to '<to>'"
-  details:
-    entity: epic|task|subtask
-    id: <entity-id>
-    fromStatus: <current-status>
-    toStatus: <attempted-status>
-    allowedTransitions[]: <valid targets from current status>
+data:
+  entity: epic|task|subtask
+  id: <entity-id>
+  fromStatus: <current-status>
+  toStatus: <attempted-status>
+  allowedTransitions[]: <valid targets from current status>
 ```
 
-## Epic progress contract
+Transition details are in `data`, not `error.details`. `error` only has `code`
+and `message`.
+
+## Epic progress
 
 ```bash
 trekoon --toon epic progress <epic-id>
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: epic.progress
@@ -295,14 +275,12 @@ data:
   nextCandidate: { id, title } | null
 ```
 
-## Task done enhanced contract
+## Task done (enhanced)
 
 ```bash
 trekoon --toon task done <task-id>
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: task.done
@@ -324,14 +302,12 @@ data:
     blockedCount
 ```
 
-## Suggest command contract
+## Suggest
 
 ```bash
 trekoon --toon suggest [--epic <epic-id>]
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: suggest
@@ -352,9 +328,9 @@ data:
     pendingConflicts
 ```
 
-## Owner field in update payloads
+## Owner field in updates
 
-Task and subtask update payloads now include `owner` in their event data:
+Task and subtask update payloads include `owner`:
 
 ```text
 data:
@@ -366,6 +342,29 @@ data:
 The board API accepts `owner` on `PATCH /api/tasks/{id}` and
 `PATCH /api/subtasks/{id}`.
 
+## Sync resolve dry-run
+
+```bash
+trekoon --toon sync resolve <conflict-id> --use ours|theirs --dry-run
+```
+
+```text
+ok: true
+command: sync.resolve
+data:
+  conflictId: <conflict-id>
+  resolution: ours|theirs
+  entityKind: epic|task|subtask
+  entityId: <entity-id>
+  fieldName: <conflicted field>
+  oursValue: <current DB value>
+  theirsValue: <source branch value>
+  wouldWrite: <value that would be written>
+  dryRun: true
+```
+
+No mutation occurs. The conflict stays pending.
+
 ## Related docs
 
 - [Quickstart](quickstart.md)

package/docs/quickstart.md

@@ -1,21 +1,19 @@
 # Quickstart
 
-Use this guide for the shortest path from an empty repo to an active Trekoon
-workflow.
+Shortest path from zero to a working Trekoon workflow.
 
-## Understand the storage model first
+## How storage works
 
-Trekoon is local-first, but inside git repos and worktrees it is **repo-shared**.
-Every worktree for the same repository resolves to one shared `.trekoon`
-directory and one shared `.trekoon/trekoon.db` database.
+Trekoon keeps one SQLite database per repository at `.trekoon/trekoon.db`. In
+worktree setups, all worktrees share the same database because storage resolves
+from the repository root.
 
-- `worktreeRoot` identifies the current checkout.
-- `sharedStorageRoot` identifies the repository root that owns `.trekoon`.
-- `databaseFile` points at the shared SQLite database.
-- `.trekoon` stays gitignored because the DB is operational state, not source
-  code.
+Key points:
 
-Outside git repos, Trekoon falls back to the current working directory.
+- `.trekoon` is gitignored. It's operational state, not source code.
+- Outside git repos, Trekoon falls back to the current working directory.
+- `worktreeRoot` is your checkout. `sharedStorageRoot` is the repo root that
+  owns `.trekoon`.
 
 ## Initialize
 
@@ -24,93 +22,30 @@ trekoon init
 trekoon --version
 ```
 
-If an agent is driving the workflow, use the machine-readable form:
+If an agent is driving the workflow:
 
 ```bash
 trekoon --toon init
 trekoon --toon sync status
 ```
 
-Bootstrap rules:
+Run `init` once per repository. It creates the shared storage root and installs
+the board runtime under `.trekoon/board`. If `sync status` reports
+`recoveryRequired` or a tracked/ignored mismatch, fix the setup before
+continuing.
 
-- Run `trekoon --toon init` once per repository to create or re-bootstrap the
-  shared storage root and install the bundled board runtime under
-  `.trekoon/board`.
-- Run `trekoon --toon sync status` before agent work to inspect diagnostics.
-- If diagnostics report `recoveryRequired`, a tracked or ignored mismatch, or an
-  ambiguous recovery path, stop and repair setup before continuing.
-
-## Open the local board
-
-After `trekoon init`, you can browse and update the same repo-shared Trekoon
-state in the browser:
+## Open the board
 
 ```bash
 trekoon board open
-trekoon board update
 ```
 
-For day-to-day use, treat `trekoon board open` as the one-command entry point.
-It both verifies the runtime files and launches the board. Reach for
-`trekoon board update` only when you need to refresh the copied runtime without
-opening the browser.
-
-What these commands do:
-
-- `trekoon board open` ensures bundled board assets are installed, starts a
-  loopback-only server on `127.0.0.1`, opens the browser, and prints a fallback
-  URL you can paste manually if launch fails
-- `trekoon board update` refreshes the runtime assets in `.trekoon/board`
-  without opening a browser or starting the server
-
-Why the board uses a local server instead of a bare HTML file:
-
-- the UI needs live reads and writes against Trekoon data, not a static export
-- the server binds only to `127.0.0.1`
-- each `board open` call generates a per-session token used by the browser/API
-- bundled assets are copied from the CLI package into `.trekoon/board`, so the
-  board works without a separate frontend install or local build step
-
-Current runtime expectations for operators:
-
-- the served HTML, styles, and board app files come from the local
-  `.trekoon/board` runtime directory
-- all assets are self-hosted: the board ships its own CSS, fonts (Inter,
-  Material Symbols), and vanilla JS with no framework or CDN dependencies
-- the board works fully offline once the runtime assets are copied into
-  `.trekoon/board`
-
-Current layout behavior:
-
-- the topbar is a compact navbar with workspace identity, Epics and Board
-  navigation, debounced search, theme toggle, and workspace info
-- the board toggles between an epics overview and a task workspace view; task
-  detail opens as a modal overlay
-- responsive breakpoints adjust kanban column counts and component spacing so
-  the board remains navigable on narrower widths
-- the page scrolls naturally as one document; modal overlays lock body scroll
-  while open
-- task cards show truncated descriptions; clicking a card opens the task detail
-  modal with the full description and edit controls
-- search filters client-side across titles, descriptions, statuses, and subtask
-  content with a 180ms debounce
-
-Verification checklist for operators:
-
-1. Open the board with `trekoon board open` and confirm the first view is the
-   epic overview with all epics listed and scrollable.
-2. Click an epic card and confirm you enter the board workspace with the topbar
-   showing the active epic context.
-3. Type in search and verify results filter as you type; confirm focus stays in
-   the search input while typing.
-4. Click a task card and confirm the task detail modal opens with the full
-   description, edit form, and subtask list.
-5. On desktop width, confirm the kanban board shows multiple columns.
-6. Resize to a narrow viewport and confirm columns reflow cleanly without
-   horizontal overflow.
-7. Close modals and confirm you return to the previous board context.
-
-## Create an epic, task, and subtask
+Starts a loopback-only server on `127.0.0.1`, opens the browser, and prints a
+fallback URL. The board is a self-hosted single-page app with no CDN
+dependencies, so it works offline once initialized. Use `trekoon board update`
+if you just need to refresh the runtime assets without opening the browser.
+
+## Create work
 
 ```bash
 trekoon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
@@ -118,7 +53,7 @@ trekoon task create --title "Implement sync status" --description "Add status re
 trekoon subtask create --task <task-id> --title "Add cursor model" --status todo
 ```
 
-Useful follow-up reads:
+Browse results:
 
 ```bash
 trekoon task list
@@ -127,10 +62,9 @@ trekoon task list --limit 25
 trekoon task list --all --view compact
 ```
 
-## Prefer one-shot planning when the graph is already known
+## One-shot planning
 
-If you already know the epic tree, create the epic, tasks, subtasks, and
-dependencies in one call:
+If you already know the full epic tree, create everything in one call:
 
 ```bash
 trekoon epic create \
@@ -143,84 +77,57 @@ trekoon epic create \
   --dep "@sub-a|@task-a"
 ```
 
-Use this when:
-
-- the epic does not exist yet
-- later records need to reference earlier records with `@temp-key`
-- you want one atomic create step and one machine response with mappings and
-  counts
+This is better than sequential creates because later records can reference
+earlier ones with `@temp-key`, and you get one atomic operation with mappings
+and counts in the response.
 
-## Add dependencies
+## Dependencies
 
 ```bash
 trekoon dep add <task-id> <depends-on-id>
 trekoon dep list <task-id>
 ```
 
-## Use batch commands for larger updates
+## Batch commands
 
-When one call needs to create or link multiple records, prefer the transactional
-batch commands:
+For larger updates, use batch commands instead of looping:
 
 | Need | Command |
 | --- | --- |
-| Create multiple tasks under one epic | `trekoon task create-many --epic <epic-id> --task ...` |
-| Create multiple subtasks under one task | `trekoon subtask create-many <task-id> --subtask ...` |
-| Add multiple dependency edges | `trekoon dep add-many --dep ...` |
-| Expand an existing epic with linked records | `trekoon epic expand <epic-id> ...` |
+| Multiple tasks under one epic | `trekoon task create-many --epic <epic-id> --task ...` |
+| Multiple subtasks under one task | `trekoon subtask create-many <task-id> --subtask ...` |
+| Multiple dependency edges | `trekoon dep add-many --dep ...` |
+| Expand an existing epic | `trekoon epic expand <epic-id> ...` |
 
-These commands validate the whole batch before applying changes, so a bad input
-fails the whole operation instead of leaving partial state behind.
+These validate the whole batch before applying, so a bad input fails the entire
+operation instead of leaving partial state.
 
-## Close or reopen a whole tree in one update
-
-When you need to manually finish or reopen an entire epic or task tree, use the
-positional-ID cascade form of `update --all`:
+## Close or reopen a whole tree
 
 ```bash
 trekoon epic update <epic-id> --all --status done
-trekoon epic update <epic-id> --all --status todo
 trekoon task update <task-id> --all --status done
-trekoon task update <task-id> --all --status todo
-trekoon subtask update <subtask-id> --all --status done
 ```
 
-Rules:
-
-- `epic update <id> --all --status done|todo` updates the epic and all
-  descendants atomically
-- `task update <id> --all --status done|todo` updates the task and all
-  descendant subtasks atomically
-- `subtask update <id> --all --status done|todo` is accepted for consistency,
-  but it only updates that one subtask
-- Positional-ID cascade mode is status-only; do not combine it with `--append`,
-  `--description`, `--title`, or `--ids`
-- If any epic/task descendant is blocked by an unresolved external dependency,
-  the whole cascade fails with no partial writes
+Cascades atomically through all descendants. If any descendant has an unresolved
+external dependency, the whole update fails with no partial writes. Works with
+`--status done` and `--status todo` only.
 
-## Check progress and get suggestions
-
-After creating work, use `epic progress` to see status counts and the next ready
-candidate:
+## Check progress
 
 ```bash
 trekoon epic progress <epic-id>
-```
-
-Use `suggest` for priority-ranked next-action recommendations:
-
-```bash
 trekoon suggest
 trekoon suggest --epic <epic-id>
 ```
 
-## Status machine
+`epic progress` returns task status counts and the next ready candidate.
+`suggest` gives priority-ranked next-action recommendations.
 
-Trekoon enforces valid status transitions. The canonical statuses are `todo`,
-`in_progress`, `done`, and `blocked`. Direct jumps like `todo → done` are
-rejected — use `task done` which auto-transitions through `in_progress`.
+## Status machine
 
-Valid transitions:
+Trekoon enforces status transitions. The statuses are `todo`, `in_progress`,
+`done`, and `blocked`.
 
 | From | Allowed targets |
 | --- | --- |
@@ -229,8 +136,45 @@ Valid transitions:
 | `blocked` | `in_progress`, `todo` |
 | `done` | `in_progress` |
 
+Direct jumps like `todo` to `done` are rejected. Use `task done` instead, which
+auto-transitions through `in_progress`.
+
+## Install the AI skill
+
+```bash
+trekoon skills install                # repo-local (default)
+trekoon skills install -g             # global (~/.agents/skills/trekoon)
+trekoon skills install --link --editor claude  # repo-local + editor symlink
+```
+
+After upgrading Trekoon, refresh installed skills:
+
+```bash
+trekoon update                        # alias for: trekoon skills update
+```
+
+For agent integration details, see [AI agents and the Trekoon skill](ai-agents.md).
+
+## Pre-merge sync
+
+Before opening or merging a PR:
+
+```bash
+trekoon --toon sync status
+trekoon --toon sync pull --from main
+trekoon --toon sync conflicts list
+trekoon --toon sync conflicts show <id>
+trekoon --toon sync resolve <id> --use theirs --dry-run
+trekoon --toon sync resolve <id> --use ours|theirs
+trekoon --toon sync status
+```
+
+Always run `sync conflicts show` before resolving so you know what you're
+overwriting. In human mode, `--use theirs` prompts for confirmation with a
+30-second timeout.
+
 ## What to read next
 
-- [Command reference](commands.md)
-- [AI agents and the Trekoon skill](ai-agents.md)
-- [Machine contracts](machine-contracts.md)
+- [Command reference](commands.md) for flags, defaults, and behavior
+- [AI agents and the Trekoon skill](ai-agents.md) for agent integration
+- [Machine contracts](machine-contracts.md) for structured output schemas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "AI-first local issue tracker CLI.",
   "keywords": [
     "ai",
@@ -45,7 +45,7 @@
     "lint": "bunx tsc --noEmit"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.9",
+    "@types/bun": "^1.3.11",
     "typescript": "^5.9.3"
   },
   "dependencies": {

package/src/board/assets/state/utils.js

@@ -143,7 +143,7 @@ export function normalizeSnapshot(rawSnapshot) {
       id: epicId,
       title: String(epic.title ?? "Untitled epic"),
       description: String(epic.description ?? "").replace(/\\n/g, "\n"),
-      status: String(epic.status ?? "todo"),
+      status: normalizeStatus(String(epic.status ?? "todo")),
       createdAt: Number(epic.createdAt ?? Date.now()),
       updatedAt: Number(epic.updatedAt ?? epic.createdAt ?? Date.now()),
       taskIds: epicTasks.map((task) => task.id),

package/src/commands/arg-parser.ts

@@ -42,6 +42,7 @@ export interface ParsedCompactFields {
 }
 
 const LONG_PREFIX = "--";
+const SHORT_FLAG_PATTERN = /^-([A-Za-z])$/u;
 
 export function parseArgs(args: readonly string[]): ParsedArgs {
   const positional: string[] = [];
@@ -57,6 +58,15 @@ export function parseArgs(args: readonly string[]): ParsedArgs {
       continue;
     }
 
+    // Short flag: single dash + single letter (e.g. -g).
+    const shortMatch = SHORT_FLAG_PATTERN.exec(token);
+    if (shortMatch) {
+      const key: string = shortMatch[1]!;
+      flags.add(key);
+      providedOptions.push(key);
+      continue;
+    }
+
     if (!token.startsWith(LONG_PREFIX)) {
       positional.push(token);
       continue;