@skrr-ai/cli 0.1.103 → 0.1.105

package/docs/v1/operations.md

@@ -56,7 +56,7 @@ The workspace CLI also has a separate agent-turn stream (this starts work and ca
 skrr agents chat <agent-id> --prompt "Summarize the chosen repository" --jsonl
 ```
 
-Each stdout line is one JSON event. `text.delta.text` is the cumulative answer despite the event name: take the latest value rather than appending it repeatedly. A `run.result` is a terminal result; `stream.gap` describes missing envelopes, and a lost view is not proof the run failed. Preserve the process exit status: 0 for completed, 1 for a failed terminal result, 75 for lost streaming access, and 130 for actual Ctrl-C detach. Cancellation is requested but must be verified against durable work state. CLI JSONL is a different transport contract from public SSE; this guide's offline checks validate the command/flags, while real reconnect/lifetime qualification belongs to the installed CLI's release checks.
+Each stdout line is one JSON event. `text.delta.text` is the cumulative answer despite the event name: take the latest value rather than appending it repeatedly. A widget the agent wrote (a block of CSS, HTML and JavaScript that the apps draw) is its text description in `text.delta` and `run.result`; the `session.output` lane keeps the block itself. A `run.result` is a terminal result; `stream.gap` describes missing envelopes, and a lost view is not proof the run failed. Preserve the process exit status: 0 for completed, 1 for a failed terminal result, 75 for lost streaming access, and 130 for actual Ctrl-C detach. Cancellation is requested but must be verified against durable work state. CLI JSONL is a different transport contract from public SSE; this guide's offline checks validate the command/flags, while real reconnect/lifetime qualification belongs to the installed CLI's release checks.
 
 ## Quota and cost
 

package/oclif.manifest.json

@@ -7187,7 +7187,7 @@
           "type": "boolean"
         },
         "jsonl": {
-          "description": "Emit one JSON event per line while streaming. Every line is a complete JSON value. Assistant text arrives as `text.delta` whose `text` is the CUMULATIVE answer so far, not a delta — take the last one, or `run.result` at the end. The same text is mirrored inside `session.output` envelopes for consumers that want the raw stream, so folding both doubles the answer: pick ONE lane. Inside a `session.output`, `envelopes[].__seq` is the dedupe key and the ordering key — the same envelope is delivered by more than one room, and a re-delivery repeats its `__seq`. A `stream.gap` event means envelopes in that seq range never arrived and replay from the server could not recover them; a hole replay fills, or one that held only invisible envelopes (`service`, `status`), emits nothing. When the persisted message could be checked, `verified` is true and `missing` names what the stream is short of (`text`, `tool`), and the event arrives just before the terminal event; `verified: false` means it could not be checked and the text MAY be short. `run.result` and the persisted message remain authoritative. Tool calls arrive as `tool.started` / `tool.completed`, once per `toolUseId`, on cloud and local-harness runs alike. A `session.notice` with `notice: \"harness-session-reset\"` means the local harness could not resume its previous session and started a new one, which does not see earlier turns of the conversation; `message` says why. A `permission.resolved` says how a local harness permission request was decided: `decidedBy` in words, and `basis` — `person` (with `surface`), `mode` (with `mode`), `policy` or `session-grant` — beside the wire `by`. When a platform update restarts the server relaying a turn your machine is still running, the run does not end at that failure: `run.handed_over` (`code: \"AGENT_WORKER_REPLACED\"`, `reason: \"worker_replaced_daemon_running\"`, `waitMs`, `deadlineAt`) says the CLI is waiting, then exactly one terminal event follows — `run.completed` with `repaired: true` and `result` (then `run.result` with `status: \"completed\"`, `repaired: true`, exit 0) when the machine finished; `run.failed` with `handover.outcome: \"machine_failed\"` and the machine's reason when it did not; or `run.failed` with `handover.outcome: \"expired\"` and the original failure when --repair-wait ran out (exit 1 for both). Ctrl-C during the wait emits `run.detached` with `handedOver: true` and exits 130.",
+          "description": "Emit one JSON event per line while streaming. Every line is a complete JSON value. Assistant text arrives as `text.delta` whose `text` is the CUMULATIVE answer so far, not a delta — take the last one, or `run.result` at the end. The same text is mirrored inside `session.output` envelopes for consumers that want the raw stream, so folding both doubles the answer: pick ONE lane. A widget the agent wrote (a block of CSS, HTML and JavaScript the apps draw) is its text description in `text.delta` and `run.result`; the `session.output` lane carries the block itself. Inside a `session.output`, `envelopes[].__seq` is the dedupe key and the ordering key — the same envelope is delivered by more than one room, and a re-delivery repeats its `__seq`. A `stream.gap` event means envelopes in that seq range never arrived and replay from the server could not recover them; a hole replay fills, or one that held only invisible envelopes (`service`, `status`), emits nothing. When the persisted message could be checked, `verified` is true and `missing` names what the stream is short of (`text`, `tool`), and the event arrives just before the terminal event; `verified: false` means it could not be checked and the text MAY be short. `run.result` and the persisted message remain authoritative. Tool calls arrive as `tool.started` / `tool.completed`, once per `toolUseId`, on cloud and local-harness runs alike. A `session.notice` with `notice: \"harness-session-reset\"` means the local harness could not resume its previous session and started a new one, which does not see earlier turns of the conversation; `message` says why. A `permission.resolved` says how a local harness permission request was decided: `decidedBy` in words, and `basis` — `person` (with `surface`), `mode` (with `mode`), `policy` or `session-grant` — beside the wire `by`. When a platform update restarts the server relaying a turn your machine is still running, the run does not end at that failure: `run.handed_over` (`code: \"AGENT_WORKER_REPLACED\"`, `reason: \"worker_replaced_daemon_running\"`, `waitMs`, `deadlineAt`) says the CLI is waiting, then exactly one terminal event follows — `run.completed` with `repaired: true` and `result` (then `run.result` with `status: \"completed\"`, `repaired: true`, exit 0) when the machine finished; `run.failed` with `handover.outcome: \"machine_failed\"` and the machine's reason when it did not; or `run.failed` with `handover.outcome: \"expired\"` and the original failure when --repair-wait ran out (exit 1 for both). Ctrl-C during the wait emits `run.detached` with `handedOver: true` and exits 130.",
           "name": "jsonl",
           "allowNo": false,
           "type": "boolean"
@@ -16859,7 +16859,7 @@
           "type": "option"
         },
         "stale-catchup-ms": {
-          "description": "Schedule stale catch-up window in ms",
+          "description": "How late a missed occurrence may still run, in ms (a positive number). After downtime, an occurrence more than this overdue is skipped rather than run late, and the schedule moves to its next future slot. Unset: 3600000 (1 hour).",
           "name": "stale-catchup-ms",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -18274,7 +18274,7 @@
           "type": "option"
         },
         "stale-catchup-ms": {
-          "description": "Schedule stale catch-up window in ms",
+          "description": "How late a missed occurrence may still run, in ms (a positive number). After downtime, an occurrence more than this overdue is skipped rather than run late, and the schedule moves to its next future slot. Unset: 3600000 (1 hour).",
           "name": "stale-catchup-ms",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -18288,7 +18288,7 @@
           "type": "option"
         },
         "entity": {
-          "description": "Event entity type for event triggers",
+          "description": "Event entity type for event triggers (create only; refused on update)",
           "name": "entity",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -18356,14 +18356,14 @@
           "type": "option"
         },
         "eval-interval-minutes": {
-          "description": "Stochastic eval interval in minutes",
+          "description": "Stochastic eval interval in minutes (create only; refused on update)",
           "name": "eval-interval-minutes",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "next-run-at": {
-          "description": "ISO datetime for self_scheduled triggers",
+          "description": "ISO datetime: alias of --at for once triggers; for self_scheduled triggers it is set at create and refused on update",
           "name": "next-run-at",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -28528,7 +28528,7 @@
         "<%= config.bin %> commitments create --agent <agent-id> --title \"SLA\" --outcome \"p95 under 200ms\" --criterion \"p95 latency confirmed\" --evaluator metric --measure <measure-id>",
         "<%= config.bin %> commitments create --agent <agent-id> --title \"AWS cost watch\" --outcome \"Cost regressions are investigated\" --agent-directive-file ./aws-cost-policy.md",
         "<%= config.bin %> commitments create --from-json commitment.json --json",
-        "# Replace <agent-id> with your Agent ID; this creates a draft, not a running loop.\ncat > commitment.json <<'JSON'\n{\n  \"agentId\": \"<agent-id>\",\n  \"title\": \"Daily queue review\",\n  \"status\": \"draft\",\n  \"target\": { \"outcome\": \"Queue changes are reviewed\" },\n  \"cadence\": { \"mode\": \"daily\", \"times\": [\"09:15\", \"17:45\"], \"timezone\": \"Asia/Shanghai\" },\n  \"watchedSources\": [{\n    \"source\": \"agent_run\",\n    \"config\": { \"keys\": [\n      { \"key\": \"queue.depth\", \"label\": \"Queue depth\", \"requireArtifact\": true,\n        \"changeRule\": { \"mode\": \"numeric_delta\", \"minDelta\": 2, \"absoluteFloor\": 1 } },\n      \"queue.status\"\n    ] }\n  }],\n  \"policy\": {\n    \"maxUserNudgesPerDay\": 0,\n    \"executionBudget\": { \"maxRunsPerDay\": 0, \"maxObservationRunsPerDay\": 0, \"maxCostUsdPerDay\": 0 }\n  }\n}\nJSON\n<%= config.bin %> commitments preflight --from-json commitment.json\n<%= config.bin %> commitments create --from-json commitment.json --json",
+        "# Replace <agent-id> with your Agent ID; this creates a draft, not a running loop.\n# In \"policy\", 0 is a ZERO budget (nothing may run or be spent), not \"no limit\".\n# To remove a limit set it to null (e.g. \"maxCostUsdPerDay\": null) or leave the key out.\ncat > commitment.json <<'JSON'\n{\n  \"agentId\": \"<agent-id>\",\n  \"title\": \"Daily queue review\",\n  \"status\": \"draft\",\n  \"target\": { \"outcome\": \"Queue changes are reviewed\" },\n  \"cadence\": { \"mode\": \"daily\", \"times\": [\"09:15\", \"17:45\"], \"timezone\": \"Asia/Shanghai\" },\n  \"watchedSources\": [{\n    \"source\": \"agent_run\",\n    \"config\": { \"keys\": [\n      { \"key\": \"queue.depth\", \"label\": \"Queue depth\", \"requireArtifact\": true,\n        \"changeRule\": { \"mode\": \"numeric_delta\", \"minDelta\": 2, \"absoluteFloor\": 1 } },\n      \"queue.status\"\n    ] }\n  }],\n  \"policy\": {\n    \"maxUserNudgesPerDay\": 0,\n    \"executionBudget\": { \"maxRunsPerDay\": 0, \"maxObservationRunsPerDay\": 0, \"maxCostUsdPerDay\": 0 }\n  }\n}\nJSON\n<%= config.bin %> commitments preflight --from-json commitment.json\n<%= config.bin %> commitments create --from-json commitment.json --json",
         "<%= config.bin %> commitments create --agent <agent-id> --title \"Keep CI healthy\" --outcome \"Failed checks are repaired\" --watch github --github-event check_run_failed --event-driven --delivery draft-pr --repo owner/repo --base main --status draft"
       ],
       "flags": {
@@ -32041,7 +32041,7 @@
           "required": true
         }
       },
-      "description": "Show what the commitment's runs reported observing",
+      "description": "Show what the commitment's runs reported observing.\n\nColumns: VALUE is shortened to fit the table (--json has the stored value). DECLARED no / REASON undeclared means the key is not declared on the Commitment's agent_run source: the reading is recorded but can never open a loop. CLAMPED yes means the observed time the run claimed was moved into the accepted window (CLAIMED is what it said). CHANGED is the server's verdict against the previous reading of the same key, never the run's. CONF is a cap on how much an Agent-reported reading is worth, not a measurement.",
       "examples": [
         "<%= config.bin %> commitments observations obj_abc123",
         "<%= config.bin %> commitments observations obj_abc123 --declared-only --changed-only",
@@ -38000,6 +38000,7 @@
         "<%= config.bin %> daemon logs --lines 500",
         "<%= config.bin %> daemon logs --stderr",
         "<%= config.bin %> daemon logs --path",
+        "<%= config.bin %> daemon logs --rotated | grep arun_",
         "<%= config.bin %> daemon logs --profile dogfood-laptop --lines 50"
       ],
       "flags": {
@@ -38012,14 +38013,14 @@
         },
         "lines": {
           "char": "n",
-          "description": "Number of recent log lines to print",
+          "description": "Number of recent log lines to print (default 200; every line with --rotated)",
           "name": "lines",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "stderr": {
-          "description": "Read daemon.err.log — every WARN and ERROR — instead of daemon.log",
+          "description": "Read the daemon's raw stderr instead of its log: the file its installed service redirects stderr to, or the profile's daemon.err.log. A daemon started with --log-file by anything else has no known stderr file, so its live log (which carries every WARN and ERROR) is shown instead, with a note",
           "name": "stderr",
           "allowNo": false,
           "type": "boolean"
@@ -38030,6 +38031,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "rotated": {
+          "description": "Include the rotated files (daemon.app.1.log …) before the current one, oldest first; with --path, list them all",
+          "name": "rotated",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "profile": {
           "char": "p",
           "description": "Read the logs of this daemon profile instead of the active one",
@@ -41792,7 +41799,7 @@
           "type": "option"
         },
         "in": {
-          "description": "Duration from now (2h, 3d)",
+          "description": "Duration from now (2h, 3d), between 1m and 30d",
           "exclusive": [
             "at"
           ],
@@ -41995,7 +42002,7 @@
           "type": "option"
         },
         "in": {
-          "description": "Duration from now (90m, 2h) — the once form",
+          "description": "Duration from now (90m, 2h), between 1m and 30d — the once form",
           "exclusive": [
             "frequency"
           ],
@@ -42497,7 +42504,7 @@
           "type": "option"
         },
         "in": {
-          "description": "New offset from now (90m, 2h)",
+          "description": "New offset from now (90m, 2h); between 1m and 30d",
           "exclusive": [
             "at"
           ],
@@ -75046,20 +75053,14 @@
       "aliases": [],
       "args": {
         "kind": {
+          "description": "Proposal kind, or the KIND:ID that `proposals list` prints",
           "name": "kind",
-          "options": [
-            "commitment_action_proposal",
-            "agent_initiative",
-            "northstar_intent",
-            "commitment_remediation_proposal",
-            "request",
-            "task_approval"
-          ],
           "required": true
         },
         "id": {
+          "description": "Proposal id",
           "name": "id",
-          "required": true
+          "required": false
         }
       },
       "description": "Discard one displayed proposal through its domain authority",
@@ -75162,20 +75163,14 @@
       "aliases": [],
       "args": {
         "kind": {
+          "description": "Proposal kind, or the KIND:ID that `proposals list` prints",
           "name": "kind",
-          "options": [
-            "commitment_action_proposal",
-            "agent_initiative",
-            "northstar_intent",
-            "commitment_remediation_proposal",
-            "request",
-            "task_approval"
-          ],
           "required": true
         },
         "id": {
+          "description": "Proposal id",
           "name": "id",
-          "required": true
+          "required": false
         }
       },
       "description": "Keep one displayed proposal through its domain authority",
@@ -75277,7 +75272,7 @@
     "proposals:list": {
       "aliases": [],
       "args": {},
-      "description": "List the bounded proposal inbox and source coverage",
+      "description": "List the bounded proposal inbox and source coverage. BASIS is how the proposal's own cost/benefit estimate was established (agent_estimate, human_confirmed or measured); — means it carries none.",
       "flags": {
         "bare": {
           "description": "Bare mode — ignore keychain/file credential sources. Token must come from env or --token.",
@@ -75372,6 +75367,7 @@
           "type": "option"
         },
         "sort": {
+          "description": "recent: newest first, page by page through every source. value: rows you can decide now first, then by estimated savings per effort hour (risk-discounted; a row with no estimate after every row that has one), then newest. value ranks one bounded window and is not exhaustive.",
           "name": "sort",
           "default": "recent",
           "hasDynamicHelp": false,
@@ -75405,23 +75401,21 @@
       "aliases": [],
       "args": {
         "kind": {
+          "description": "Proposal kind, or the KIND:ID that `proposals list` prints",
           "name": "kind",
-          "options": [
-            "commitment_action_proposal",
-            "agent_initiative",
-            "northstar_intent",
-            "commitment_remediation_proposal",
-            "request",
-            "task_approval"
-          ],
           "required": true
         },
         "id": {
+          "description": "Proposal id",
           "name": "id",
-          "required": true
+          "required": false
         }
       },
       "description": "Show one viewer-scoped proposal and its frozen revision",
+      "examples": [
+        "<%= config.bin %> proposals show request <proposal-id>",
+        "<%= config.bin %> proposals show request:<proposal-id>"
+      ],
       "flags": {
         "bare": {
           "description": "Bare mode — ignore keychain/file credential sources. Token must come from env or --token.",
@@ -75484,20 +75478,14 @@
       "aliases": [],
       "args": {
         "kind": {
+          "description": "Proposal kind, or the KIND:ID that `proposals list` prints",
           "name": "kind",
-          "options": [
-            "commitment_action_proposal",
-            "agent_initiative",
-            "northstar_intent",
-            "commitment_remediation_proposal",
-            "request",
-            "task_approval"
-          ],
           "required": true
         },
         "id": {
+          "description": "Proposal id",
           "name": "id",
-          "required": true
+          "required": false
         }
       },
       "description": "Snooze one displayed proposal through its domain authority",
@@ -75934,9 +75922,9 @@
       "args": {},
       "description": "Create a new request",
       "examples": [
-        "<%= config.bin %> requests create --title \"Approve budget\" --type approval",
-        "<%= config.bin %> requests create --title \"Q1 review\" --type task --description \"Review Q1 goals\"",
-        "<%= config.bin %> requests create --from-json request.json"
+        "<%= config.bin %> requests create --title \"Approve budget\" --type approval --target-user <user-id>",
+        "<%= config.bin %> requests create --title \"Q1 review\" --type task --description \"Review Q1 goals\" --target-agent <agent-id>",
+        "cat > request.json <<'JSON'\n{ \"title\": \"Approve budget\", \"type\": \"approval\", \"targetUserId\": \"<user-id>\" }\nJSON\n<%= config.bin %> requests create --from-json request.json"
       ],
       "flags": {
         "bare": {
@@ -95269,21 +95257,21 @@
           "type": "option"
         },
         "graph": {
-          "description": "Required exactly once with --draft/--starter: path to graph JSON ({ nodes, edges }); inspect config with spaces workflows node-types",
+          "description": "One of --graph, --draft or --starter (exactly one): path to graph JSON ({ nodes, edges }); inspect config with spaces workflows node-types",
           "name": "graph",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "draft": {
-          "description": "Required exactly once with --graph/--starter: path to complete Canvas draft JSON ({ semantic, presentation })",
+          "description": "One of --graph, --draft or --starter (exactly one): path to complete Canvas draft JSON ({ semantic, presentation })",
           "name": "draft",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "starter": {
-          "description": "Required exactly once with --graph/--draft: create a valid one-node starter graph",
+          "description": "One of --graph, --draft or --starter (exactly one): create a valid one-node starter graph",
           "name": "starter",
           "allowNo": false,
           "type": "boolean"
@@ -109061,7 +109049,7 @@
           "type": "option"
         },
         "savings": {
-          "description": "Expected USD savings (requires --per)",
+          "description": "Expected USD savings (requires --per). An estimate you write as a person is recorded as Human confirmed under your name, and an Agent edit is then refused with a 409; an Agent writes an Agent estimate. Re-sending the same values changes nothing.",
           "name": "savings",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -109080,14 +109068,14 @@
           "type": "option"
         },
         "effort": {
-          "description": "Expected effort in hours, nonnegative",
+          "description": "Expected effort in hours, nonnegative (part of the estimate; see --savings)",
           "name": "effort",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "risk": {
-          "description": "Expected risk",
+          "description": "Expected risk (part of the estimate; see --savings)",
           "name": "risk",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -109098,6 +109086,25 @@
           ],
           "type": "option"
         },
+        "confidence": {
+          "description": "How sure the estimate is (part of the estimate; see --savings). An earlier confidence stays on the claim until you replace it.",
+          "name": "confidence",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "low",
+            "medium",
+            "high"
+          ],
+          "type": "option"
+        },
+        "rationale": {
+          "description": "Why the estimate is what it is, up to 500 characters (part of the estimate). An earlier rationale stays on the claim, under its new basis, until you replace it.",
+          "name": "rationale",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "estimate": {
           "description": "Estimate value from the Space estimate scale. Requires a scale on the Space (or an ancestor it inherits from); with none set, the server drops the value. Set one with `spaces update <space> --estimate-scale <scale> --estimate-migration <clear|migrate>`.",
           "name": "estimate",
@@ -120833,7 +120840,7 @@
           "type": "option"
         },
         "savings": {
-          "description": "Expected USD savings (requires --per)",
+          "description": "Expected USD savings (requires --per). An estimate you write as a person is recorded as Human confirmed under your name, and an Agent edit is then refused with a 409; an Agent writes an Agent estimate. Re-sending the same values changes nothing.",
           "name": "savings",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -120852,14 +120859,14 @@
           "type": "option"
         },
         "effort": {
-          "description": "Expected effort in hours, nonnegative",
+          "description": "Expected effort in hours, nonnegative (part of the estimate; see --savings)",
           "name": "effort",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "risk": {
-          "description": "Expected risk",
+          "description": "Expected risk (part of the estimate; see --savings)",
           "name": "risk",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -120870,6 +120877,25 @@
           ],
           "type": "option"
         },
+        "confidence": {
+          "description": "How sure the estimate is (part of the estimate; see --savings). An earlier confidence stays on the claim until you replace it.",
+          "name": "confidence",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "low",
+            "medium",
+            "high"
+          ],
+          "type": "option"
+        },
+        "rationale": {
+          "description": "Why the estimate is what it is, up to 500 characters (part of the estimate). An earlier rationale stays on the claim, under its new basis, until you replace it.",
+          "name": "rationale",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "estimate": {
           "description": "New estimate value from the Space estimate scale. Requires a scale on the Space (or an ancestor it inherits from); with none set, the server drops the value. Set the scale in the web UI — no CLI command configures it.",
           "name": "estimate",
@@ -120892,6 +120918,17 @@
           "multiple": false,
           "type": "option"
         },
+        "review-policy": {
+          "description": "Raise or lower the review bar: 'required' means closing this Task needs someone other than the Result author to accept it, 'none' (the default) does not. Not a specification change.",
+          "name": "review-policy",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "none",
+            "required"
+          ],
+          "type": "option"
+        },
         "goal": {
           "description": "Move task to a different goal (goal id), or \"none\" to detach it from its goal",
           "name": "goal",
@@ -125118,14 +125155,14 @@
           "type": "option"
         },
         "outcome": {
-          "description": "Outcome filter for owner-wide audit history",
+          "description": "Outcome filter for owner-wide audit history (succeeded, failed, skipped, incomplete, capped, ...); an unknown value is refused with the full list",
           "name": "outcome",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "source": {
-          "description": "Source filter for owner-wide audit history",
+          "description": "Source filter for owner-wide audit history (schedule, once, event, manual, webhook, replay, ...); an unknown value is refused with the full list",
           "name": "source",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -125562,7 +125599,7 @@
           "type": "option"
         },
         "stale-catchup-ms": {
-          "description": "Schedule stale catch-up window in ms",
+          "description": "How late a missed occurrence may still run, in ms (a positive number). After downtime, an occurrence more than this overdue is skipped rather than run late, and the schedule moves to its next future slot. Unset: 3600000 (1 hour).",
           "name": "stale-catchup-ms",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -126175,7 +126212,8 @@
       "description": "Fire a universal trigger immediately",
       "examples": [
         "<%= config.bin %> triggers fire <trigger-id>",
-        "<%= config.bin %> triggers fire <trigger-id> --from-json fire-options.json --json"
+        "<%= config.bin %> triggers fire <trigger-id> --from-json fire-options.json --json",
+        "<%= config.bin %> triggers fire <trigger-id> --strict   # exit 1 unless the fire succeeded"
       ],
       "flags": {
         "bare": {
@@ -126218,11 +126256,17 @@
           "type": "boolean"
         },
         "from-json": {
-          "description": "Path to a JSON file (or \"-\" for stdin) to use as fire options",
+          "description": "Path to a JSON file (or \"-\" for stdin) of fire options. Read: occurrenceId (a key of your own; firing it again is the same fire) and, for an event trigger only, event ({payload}; the entity and event type come from the trigger). Any other key is ignored, and the answer names it",
           "name": "from-json",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "strict": {
+          "description": "Exit 1 unless the fire was accepted (outcome succeeded, in_progress or awaiting_runtime, or a repeat of one that was). A fire that resolved nothing or was refused (incomplete, skipped, failed, …) exits 1 with it; without it every outcome exits 0",
+          "name": "strict",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -127346,7 +127390,7 @@
           "type": "option"
         },
         "stale-catchup-ms": {
-          "description": "Schedule stale catch-up window in ms",
+          "description": "How late a missed occurrence may still run, in ms (a positive number). After downtime, an occurrence more than this overdue is skipped rather than run late, and the schedule moves to its next future slot. Unset: 3600000 (1 hour).",
           "name": "stale-catchup-ms",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -127360,7 +127404,7 @@
           "type": "option"
         },
         "entity": {
-          "description": "Event entity type for event triggers",
+          "description": "Event entity type for event triggers (create only; refused on update)",
           "name": "entity",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -127428,14 +127472,14 @@
           "type": "option"
         },
         "eval-interval-minutes": {
-          "description": "Stochastic eval interval in minutes",
+          "description": "Stochastic eval interval in minutes (create only; refused on update)",
           "name": "eval-interval-minutes",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "next-run-at": {
-          "description": "ISO datetime for self_scheduled triggers",
+          "description": "ISO datetime: alias of --at for once triggers; for self_scheduled triggers it is set at create and refused on update",
           "name": "next-run-at",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -132305,7 +132349,7 @@
           "required": true
         },
         "userId": {
-          "description": "Member user ID",
+          "description": "Member user ID: 24 hexadecimal characters, not an email (`skrr whoami` prints your own)",
           "name": "userId",
           "required": true
         }
@@ -132453,5 +132497,5 @@
       ]
     }
   },
-  "version": "0.1.103"
+  "version": "0.1.105"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skrr-ai/cli",
-  "version": "0.1.103",
+  "version": "0.1.105",
   "description": "Command-line interface for skrr",
   "license": "ISC",
   "author": "skrr",