workbite 0.1.19 → 0.1.21

package/skills/workbite-native/references/commands.md

@@ -1,213 +1,213 @@
-# workbite agent / workbite mcp reference
-
-Contents: invocation · binding flags · commands · packets · output and
-exits · refusals and recovery · file input on Windows · MCP tools.
-
-## Invocation
-
-`workbite` is the npm launcher's bin. Where it is not on `PATH`, run the same
-entry with Node: `node <path-to-installed-workbite>/bin/workbite.js agent ...`.
-Only the commands below exist under `workbite agent`; anything else (raw RPC,
-legacy apply, delete, migration, provider control) is refused. Each call is
-one request to the native client of the installed bundle, which talks to the
-workspace's running owner; nothing is started, and a refusal starts nothing.
-
-## Binding flags
-
-```text
-workbite agent [--workspace ABS --workspace-uid UUID] <command> ...
-```
-
-- `--workspace` (absolute path) and `--workspace-uid` (the workspace's UUID)
-  are given together or not at all.
-- Without them, a read binds the workspace saved by the last successful
-  `workbite open`. Writes (`tasks create`, `tasks update`, `checkpoint`,
-  import apply/rollback) refuse without the explicit pair. Use the default only for discovery
-  (`capabilities`, the first `status`, `tasks list`); once `status` has
-  named the workspace, pass the pair on `context` and `operation-status` too.
-- The binding is checked before every call: the workspace descriptor must
-  still carry that UUID and its owner must be the same ready, authenticated
-  owner. A changed selection never retargets an explicit binding.
-
-## Commands
-
-| Command | Writes | Form |
-|---|---|---|
-| capabilities | no | `workbite agent capabilities` |
-| status | no | `workbite agent [binding] status` |
-| tasks list | no | `workbite agent [binding] tasks list [--status S] [--limit N] [--offset N]` |
-| context | no | `workbite agent --workspace ABS --workspace-uid UUID context --task T-0001 [--view V]` |
-| tasks create | yes | `workbite agent --workspace ABS --workspace-uid UUID tasks create --intent-id ID (--input-file FILE \| --stdin)` |
-| tasks update | yes | `workbite agent --workspace ABS --workspace-uid UUID tasks update --intent-id ID (--input-file FILE \| --stdin)` |
-| checkpoint | yes | `workbite agent --workspace ABS --workspace-uid UUID checkpoint --intent-id ID (--input-file FILE \| --stdin)` |
-| operation-status | no | `workbite agent --workspace ABS --workspace-uid UUID operation-status --intent-id ID` |
-
-- `capabilities` lists what the installed native client actually supports;
-  a command it does not list is refused, never emulated.
-- `status`: the native answer plus a top-level `workbite` object
-  (`schema: "workbite.agent.binding.v1"`, `workspace`, `workspace_uid`,
-  `endpoint`, `state`). Take the pair from `workbite.workspace` and
-  `workbite.workspace_uid`, and continue only with exit 0, `data.ready: true`
-  and `data.actual_workspace_uid` equal to `workbite.workspace_uid`. It never
-  contains tokens or credentials.
-- `tasks list`: `--status` `active` (default: open + started), `all`, `open`,
-  `started`, `done`, `dropped`; `--limit` 1–100 (default 20); `--offset` ≥ 0.
-  Rows are `id`, `title`, `status`, `priority`, `revision`; order is backlog
-  order. Page with `data.next_offset` (`null` on the last page).
-- `context --task ID`: the Task (`id`, `uid`, `title`, `detail`, `status`,
-  `priority`, `due`, `revision`) plus at most five newest `recent_worklog`
-  entries. `--view` is `core-v1` (default), `planning-v1`, `planning-v2` or
-  `resume-v1`, when the native client lists it.
-
-## Advertised fields and transfer commands
-
-Probe `workbite agent capabilities` before using new fields or transfer
-commands. Task fields require the exact command's `packet_schema`; MCP
-`tools/list` must agree. See [task-fields.md](task-fields.md) for field types
-and full packets, and [transfer.md](transfer.md) for unreleased,
-capability-gated export/import preview/apply/status/rollback. A refusal never
-authorizes legacy apply, raw HTTP or another install.
-
-## Packets
-
-Exactly one JSON object from `--input-file FILE` or `--stdin` (one is
-required; they are exclusive), valid UTF-8 of at most 32768 bytes, with only
-the keys admitted by the advertised `packet_schema`. Write it without a BOM.
-A packet never names a workspace. The launcher checks size and UTF-8 and hands the text to the native
-client as stdin; the packet never travels in argv.
-
-`tasks create`:
-
-```json
-{"title": "Fix login redirect loop", "detail": "Seen on /settings after token refresh.", "follows_task_id": "T-0004"}
-```
-
-`title` is required and nonblank; `detail` and `follows_task_id` are
-original optional fields. Additional fields require `packet_schema`; see
-[task-fields.md](task-fields.md). `follows_task_id` is receipt provenance only
-(no parent or dependency). One intent ID creates at most one Task.
-
-`tasks update`:
-
-```json
-{"task_id": "T-0001", "expected_revision": 4, "changes": {"detail": "…", "status": "started"}}
-```
-
-`expected_revision` is the integer from a fresh `context`. `changes` is a
-non-empty object matching the advertised schema. The original subset is
-`detail`/`status`; additions require explicit field/type advertisement.
-See [task-fields.md](task-fields.md).
-
-`checkpoint`:
-
-```json
-{"task_id": "T-0001", "date": "2026-10-13", "done": ["Reproduced the loop."], "next": ["Patch the guard."], "blockers": []}
-```
-
-All five keys are required; `date` is `YYYY-MM-DD`; `done`, `next` and
-`blockers` are lists of strings with at least one item across the three.
-
-Intent IDs match `[A-Za-z0-9._:-]{8,128}`. Pick them so you can tell them
-apart later, for example `wb.create.20261013.login-bug`,
-`wb.update.T-0001.r4.started`, `wb.checkpoint.T-0001.20261013.1`.
-
-## Output and exits
-
-| Exit | Meaning |
-|---:|---|
-| 0 | success, idempotent replay, or an operation-status answer (committed or unknown); one `workstack.cli.v1` JSON envelope on stdout |
-| 1 | refused. A native/domain refusal prints a `workstack.cli.v1` envelope with `error.code`. A WorkBite binding, argument, input or transport refusal (missing write pair, binding mismatch, unreadable or oversize packet, unavailable owner, lost response) prints only a short redacted message on stderr and no JSON |
-| 2 | native usage error; no envelope |
-
-- An envelope has `data` on success and `error` on failure, never both.
-- A committed write has `meta.commit_state: "committed"`, `meta.intent_id`
-  and `meta.replayed`. `tasks create` / `tasks update` add `data.receipt`
-  (`operation`, `result` `created` / `applied` / `no_change`, `task_id`,
-  `before_revision`, `after_revision`, `committed_at`) and `data.task`. A
-  receipt lookup precedes revision CAS. A replay returns the original snapshot
-  even after later edits: read `context` for current state.
-  If `data.omitted` names `task` or `receipt`, they were dropped for size;
-  `commit_state` still settles the write.
-- A write whose answer was lost or timed out exits 1 with a stderr message
-  saying the commit is unknown and was not replayed: treat it exactly like
-  `commit_unknown` below.
-
-## Refusals and recovery
-
-| `error.code` | Do |
-|---|---|
-| `revision_conflict` | re-read `context`; re-issue against `details.current_revision` with a new intent ID only if still within the user's intent, else stop and report |
-| `idempotency_conflict` | that intent ID was used for a different packet: stop; never reuse it |
-| `task_not_found` | ask the user; never substitute another Task |
-| `invalid_body`, `input_unreadable` | fix the packet (keys, types, encoding) or file path |
-| `operation_refused` | report it; nothing was written |
-| `workspace_mismatch`, `invalid_authority`, `owner_unavailable`, `owner_upgrade_required`, `store_sync_required`, `capability_not_enabled`, `unsupported`, `internal_error` | stop and report; no fallback |
-| `commit_unknown`, or a stderr "commit unknown" message | stop writing; keep the intent ID and packet; follow operation-status below |
-
-`operation-status --intent-id ID` is read-only and exits 0 with either:
-
-- `data.commit_state: "committed"`: the original receipt and task; the write
-  happened.
-- `data.commit_state: "unknown"` with a `reason` (`no_receipt`,
-  `recovery_pending`, `purged`, `incomplete_evidence`,
-  `not_an_agent_intent`, …). Unknown never means "not written". Only for
-  `no_receipt` may you resend the same intent ID with the byte-identical
-  packet. Never send a changed packet under that ID and never switch to a new
-  ID to force it through.
-
-A checkpoint has no Task receipt: on `commit_unknown` report it and do not
-append another checkpoint.
-
-## File input on Windows
-
-Windows PowerShell 5.1 pipes re-encode non-ASCII text, and
-`Set-Content -Encoding utf8` adds a BOM. Write BOM-free UTF-8 through .NET and
-use `--input-file`:
-
-```powershell
-$packet = New-TemporaryFile
-$body = '{"title":"Fix login redirect loop","detail":"Seen after token refresh."}'
-[IO.File]::WriteAllText($packet.FullName, $body, (New-Object Text.UTF8Encoding $false))
-workbite agent --workspace 'C:\work\demo' --workspace-uid '11111111-1111-4111-8111-111111111111' tasks create --intent-id wb.create.20261013.login-bug --input-file $packet.FullName
-$LASTEXITCODE
-```
-
-Keep the file unchanged until the write is committed or recovered, so a
-permitted resend is byte-identical. POSIX shells can use `--stdin` with a
-here-document.
-
-## MCP tools
-
-`workbite mcp [--workspace ABS --workspace-uid UUID]` serves the same
-commands over MCP stdio. It binds once at startup and keeps that workspace for
-the life of the process: with the explicit pair (recommended) that workspace;
-otherwise the selection saved at startup. A later `workbite open` of another
-workspace does not move a running server; restart it to rebind.
-
-Arguments are flat (no nested packet); `workspace_uid` must equal the
-server's bound UUID wherever it is given, and is required on writes. Unknown
-or mistyped arguments are refused before anything runs.
-
-| Tool | Writes | Arguments (required **bold**) |
-|---|---|---|
-| `workbite_status` | no | `workspace_uid` |
-| `workbite_tasks_list` | no | `workspace_uid`, `status`, `limit`, `offset` |
-| `workbite_context` | no | `workspace_uid`, **`task_id`**, `view`, `fingerprint`, `if_fingerprint` |
-| `workbite_tasks_create` | yes | **`workspace_uid`**, **`intent_id`**, **`title`**, `detail`, `follows_task_id`, other advertised create fields |
-| `workbite_tasks_update` | yes | **`workspace_uid`**, **`intent_id`**, **`task_id`**, **`expected_revision`**, **`changes`** (advertised update fields) |
-| `workbite_checkpoint` | yes | **`workspace_uid`**, **`intent_id`**, **`task_id`**, **`date`**, **`done`**, **`next`**, **`blockers`** |
-| `workbite_operation_status` | no | `workspace_uid`, **`intent_id`** |
-
-- Pass `workspace_uid` on reads of a selected Task too, so a server bound
-  elsewhere refuses instead of answering for another workspace.
-- `workbite_status` adds a `workbite` object (`workspace`, `workspace_uid`).
-- Results carry the envelope as `structuredContent` (from protocol
-  `2025-06-18`) and as text. A refusal is `isError: true`; adapter refusals
-  use contract `workbite.mcp.v1` with codes such as `invalid_arguments`,
-  `workspace_mismatch`, `binding_unavailable`, `not_sent` and
-  `commit_unknown` (with `meta.commit_state: "unknown"` and the `intent_id`
-  for `workbite_operation_status`). Calls run one at a time and are never
-  retried.
-- Transfer tool names and exact preview/apply/status/rollback argument rules:
-  [transfer.md](transfer.md). They require actual native capability support.
-- No tool runs shells, raw RPC, deletes or policy changes.
+# workbite agent / workbite mcp reference
+
+Contents: invocation · binding flags · commands · packets · output and
+exits · refusals and recovery · file input on Windows · MCP tools.
+
+## Invocation
+
+`workbite` is the npm launcher's bin. Where it is not on `PATH`, run the same
+entry with Node: `node <path-to-installed-workbite>/bin/workbite.js agent ...`.
+Only the commands below exist under `workbite agent`; anything else (raw RPC,
+legacy apply, delete, migration, provider control) is refused. Each call is
+one request to the native client of the installed bundle, which talks to the
+workspace's running owner; nothing is started, and a refusal starts nothing.
+
+## Binding flags
+
+```text
+workbite agent [--workspace ABS --workspace-uid UUID] <command> ...
+```
+
+- `--workspace` (absolute path) and `--workspace-uid` (the workspace's UUID)
+  are given together or not at all.
+- Without them, a read binds the workspace saved by the last successful
+  `workbite open`. Writes (`tasks create`, `tasks update`, `checkpoint`,
+  import apply/rollback) refuse without the explicit pair. Use the default only for discovery
+  (`capabilities`, the first `status`, `tasks list`); once `status` has
+  named the workspace, pass the pair on `context` and `operation-status` too.
+- The binding is checked before every call: the workspace descriptor must
+  still carry that UUID and its owner must be the same ready, authenticated
+  owner. A changed selection never retargets an explicit binding.
+
+## Commands
+
+| Command | Writes | Form |
+|---|---|---|
+| capabilities | no | `workbite agent capabilities` |
+| status | no | `workbite agent [binding] status` |
+| tasks list | no | `workbite agent [binding] tasks list [--status S] [--limit N] [--offset N]` |
+| context | no | `workbite agent --workspace ABS --workspace-uid UUID context --task T-0001 [--view V]` |
+| tasks create | yes | `workbite agent --workspace ABS --workspace-uid UUID tasks create --intent-id ID (--input-file FILE \| --stdin)` |
+| tasks update | yes | `workbite agent --workspace ABS --workspace-uid UUID tasks update --intent-id ID (--input-file FILE \| --stdin)` |
+| checkpoint | yes | `workbite agent --workspace ABS --workspace-uid UUID checkpoint --intent-id ID (--input-file FILE \| --stdin)` |
+| operation-status | no | `workbite agent --workspace ABS --workspace-uid UUID operation-status --intent-id ID` |
+
+- `capabilities` lists what the installed native client actually supports;
+  a command it does not list is refused, never emulated.
+- `status`: the native answer plus a top-level `workbite` object
+  (`schema: "workbite.agent.binding.v1"`, `workspace`, `workspace_uid`,
+  `endpoint`, `state`). Take the pair from `workbite.workspace` and
+  `workbite.workspace_uid`, and continue only with exit 0, `data.ready: true`
+  and `data.actual_workspace_uid` equal to `workbite.workspace_uid`. It never
+  contains tokens or credentials.
+- `tasks list`: `--status` `active` (default: open + started), `all`, `open`,
+  `started`, `done`, `dropped`; `--limit` 1–100 (default 20); `--offset` ≥ 0.
+  Rows are `id`, `title`, `status`, `priority`, `revision`; order is backlog
+  order. Page with `data.next_offset` (`null` on the last page).
+- `context --task ID`: the Task (`id`, `uid`, `title`, `detail`, `status`,
+  `priority`, `due`, `revision`) plus at most five newest `recent_worklog`
+  entries. `--view` is `core-v1` (default), `planning-v1`, `planning-v2` or
+  `resume-v1`, when the native client lists it.
+
+## Advertised fields and transfer commands
+
+Probe `workbite agent capabilities` before using new fields or transfer
+commands. Task fields require the exact command's `packet_schema`; MCP
+`tools/list` must agree. See [task-fields.md](task-fields.md) for field types
+and full packets, and [transfer.md](transfer.md) for unreleased,
+capability-gated export/import preview/apply/status/rollback. A refusal never
+authorizes legacy apply, raw HTTP or another install.
+
+## Packets
+
+Exactly one JSON object from `--input-file FILE` or `--stdin` (one is
+required; they are exclusive), valid UTF-8 of at most 32768 bytes, with only
+the keys admitted by the advertised `packet_schema`. Write it without a BOM.
+A packet never names a workspace. The launcher checks size and UTF-8 and hands the text to the native
+client as stdin; the packet never travels in argv.
+
+`tasks create`:
+
+```json
+{"title": "Fix login redirect loop", "detail": "Seen on /settings after token refresh.", "follows_task_id": "T-0004"}
+```
+
+`title` is required and nonblank; `detail` and `follows_task_id` are
+original optional fields. Additional fields require `packet_schema`; see
+[task-fields.md](task-fields.md). `follows_task_id` is receipt provenance only
+(no parent or dependency). One intent ID creates at most one Task.
+
+`tasks update`:
+
+```json
+{"task_id": "T-0001", "expected_revision": 4, "changes": {"detail": "…", "status": "started"}}
+```
+
+`expected_revision` is the integer from a fresh `context`. `changes` is a
+non-empty object matching the advertised schema. The original subset is
+`detail`/`status`; additions require explicit field/type advertisement.
+See [task-fields.md](task-fields.md).
+
+`checkpoint`:
+
+```json
+{"task_id": "T-0001", "date": "2026-10-13", "done": ["Reproduced the loop."], "next": ["Patch the guard."], "blockers": []}
+```
+
+All five keys are required; `date` is `YYYY-MM-DD`; `done`, `next` and
+`blockers` are lists of strings with at least one item across the three.
+
+Intent IDs match `[A-Za-z0-9._:-]{8,128}`. Pick them so you can tell them
+apart later, for example `wb.create.20261013.login-bug`,
+`wb.update.T-0001.r4.started`, `wb.checkpoint.T-0001.20261013.1`.
+
+## Output and exits
+
+| Exit | Meaning |
+|---:|---|
+| 0 | success, idempotent replay, or an operation-status answer (committed or unknown); one `workstack.cli.v1` JSON envelope on stdout |
+| 1 | refused. A native/domain refusal prints a `workstack.cli.v1` envelope with `error.code`. A WorkBite binding, argument, input or transport refusal (missing write pair, binding mismatch, unreadable or oversize packet, unavailable owner, lost response) prints only a short redacted message on stderr and no JSON |
+| 2 | native usage error; no envelope |
+
+- An envelope has `data` on success and `error` on failure, never both.
+- A committed write has `meta.commit_state: "committed"`, `meta.intent_id`
+  and `meta.replayed`. `tasks create` / `tasks update` add `data.receipt`
+  (`operation`, `result` `created` / `applied` / `no_change`, `task_id`,
+  `before_revision`, `after_revision`, `committed_at`) and `data.task`. A
+  receipt lookup precedes revision CAS. A replay returns the original snapshot
+  even after later edits: read `context` for current state.
+  If `data.omitted` names `task` or `receipt`, they were dropped for size;
+  `commit_state` still settles the write.
+- A write whose answer was lost or timed out exits 1 with a stderr message
+  saying the commit is unknown and was not replayed: treat it exactly like
+  `commit_unknown` below.
+
+## Refusals and recovery
+
+| `error.code` | Do |
+|---|---|
+| `revision_conflict` | re-read `context`; re-issue against `details.current_revision` with a new intent ID only if still within the user's intent, else stop and report |
+| `idempotency_conflict` | that intent ID was used for a different packet: stop; never reuse it |
+| `task_not_found` | ask the user; never substitute another Task |
+| `invalid_body`, `input_unreadable` | fix the packet (keys, types, encoding) or file path |
+| `operation_refused` | report it; nothing was written |
+| `workspace_mismatch`, `invalid_authority`, `owner_unavailable`, `owner_upgrade_required`, `store_sync_required`, `capability_not_enabled`, `unsupported`, `internal_error` | stop and report; no fallback |
+| `commit_unknown`, or a stderr "commit unknown" message | stop writing; keep the intent ID and packet; follow operation-status below |
+
+`operation-status --intent-id ID` is read-only and exits 0 with either:
+
+- `data.commit_state: "committed"`: the original receipt and task; the write
+  happened.
+- `data.commit_state: "unknown"` with a `reason` (`no_receipt`,
+  `recovery_pending`, `purged`, `incomplete_evidence`,
+  `not_an_agent_intent`, …). Unknown never means "not written". Only for
+  `no_receipt` may you resend the same intent ID with the byte-identical
+  packet. Never send a changed packet under that ID and never switch to a new
+  ID to force it through.
+
+A checkpoint has no Task receipt: on `commit_unknown` report it and do not
+append another checkpoint.
+
+## File input on Windows
+
+Windows PowerShell 5.1 pipes re-encode non-ASCII text, and
+`Set-Content -Encoding utf8` adds a BOM. Write BOM-free UTF-8 through .NET and
+use `--input-file`:
+
+```powershell
+$packet = New-TemporaryFile
+$body = '{"title":"Fix login redirect loop","detail":"Seen after token refresh."}'
+[IO.File]::WriteAllText($packet.FullName, $body, (New-Object Text.UTF8Encoding $false))
+workbite agent --workspace 'C:\work\demo' --workspace-uid '11111111-1111-4111-8111-111111111111' tasks create --intent-id wb.create.20261013.login-bug --input-file $packet.FullName
+$LASTEXITCODE
+```
+
+Keep the file unchanged until the write is committed or recovered, so a
+permitted resend is byte-identical. POSIX shells can use `--stdin` with a
+here-document.
+
+## MCP tools
+
+`workbite mcp [--workspace ABS --workspace-uid UUID]` serves the same
+commands over MCP stdio. It binds once at startup and keeps that workspace for
+the life of the process: with the explicit pair (recommended) that workspace;
+otherwise the selection saved at startup. A later `workbite open` of another
+workspace does not move a running server; restart it to rebind.
+
+Arguments are flat (no nested packet); `workspace_uid` must equal the
+server's bound UUID wherever it is given, and is required on writes. Unknown
+or mistyped arguments are refused before anything runs.
+
+| Tool | Writes | Arguments (required **bold**) |
+|---|---|---|
+| `workbite_status` | no | `workspace_uid` |
+| `workbite_tasks_list` | no | `workspace_uid`, `status`, `limit`, `offset` |
+| `workbite_context` | no | `workspace_uid`, **`task_id`**, `view`, `fingerprint`, `if_fingerprint` |
+| `workbite_tasks_create` | yes | **`workspace_uid`**, **`intent_id`**, **`title`**, `detail`, `follows_task_id`, other advertised create fields |
+| `workbite_tasks_update` | yes | **`workspace_uid`**, **`intent_id`**, **`task_id`**, **`expected_revision`**, **`changes`** (advertised update fields) |
+| `workbite_checkpoint` | yes | **`workspace_uid`**, **`intent_id`**, **`task_id`**, **`date`**, **`done`**, **`next`**, **`blockers`** |
+| `workbite_operation_status` | no | `workspace_uid`, **`intent_id`** |
+
+- Pass `workspace_uid` on reads of a selected Task too, so a server bound
+  elsewhere refuses instead of answering for another workspace.
+- `workbite_status` adds a `workbite` object (`workspace`, `workspace_uid`).
+- Results carry the envelope as `structuredContent` (from protocol
+  `2025-06-18`) and as text. A refusal is `isError: true`; adapter refusals
+  use contract `workbite.mcp.v1` with codes such as `invalid_arguments`,
+  `workspace_mismatch`, `binding_unavailable`, `not_sent` and
+  `commit_unknown` (with `meta.commit_state: "unknown"` and the `intent_id`
+  for `workbite_operation_status`). Calls run one at a time and are never
+  retried.
+- Transfer tool names and exact preview/apply/status/rollback argument rules:
+  [transfer.md](transfer.md). They require actual native capability support.
+- No tool runs shells, raw RPC, deletes or policy changes.