@skrr-ai/cli 0.1.110 → 0.1.113

package/docs/v1/README.md

@@ -9,6 +9,7 @@ This edition was reviewed on **2026-10-10** against CLI **0.1.95**, daemon **0.8
 | Sign in and create your first Task | [Quickstart](quickstart.md) |
 | Make a read-only HTTP request with a scoped key | [Public API](api.md) |
 | Fix sign-in, errors, quotas, permissions, or a failed upgrade | [Operations and recovery](operations.md) |
+| Schedule, inspect, revise or cancel 1–10 lookbacks | [Lookback plans](lookback-plans.md) |
 | Understand what changed in this guide | [Changelog](changelog.md) |
 
 The workspace CLI uses the account/workspace `/api` surface. The Managed Agents public API uses `/v1` and Space-scoped API keys. A personal access token for CLI automation is a different credential. Choose the surface before issuing a credential.

package/docs/v1/lookback-plans.md

@@ -0,0 +1,88 @@
+# Scheduled lookback plans
+
+A plan provides 1–10 opportunities to inspect fresh evidence. Each check may stay silent. It does not promise one message per check.
+
+## Create
+
+Read a conversation belonging to the intended agent:
+
+```sh
+skrr convos messages YOUR_CONVERSATION_ID --json
+```
+
+Choose a completed assistant reply (`isCreatedByUser: false`, `unfinished: false`). Copy its actual `messageId` and completion `updatedAt`. The source is immutable: do not substitute the current clock or a user message.
+
+Generate a template without signing in, then replace all three source placeholders:
+
+```sh
+skrr followups plans example > plan.json
+```
+
+The generated file contains:
+
+```json
+{
+  "objective": "Check deployment health",
+  "stopCondition": "Deployment is ready or the owner cancels",
+  "source": {
+    "conversationId": "YOUR_CONVERSATION_ID",
+    "messageId": "YOUR_COMPLETED_ASSISTANT_MESSAGE_ID",
+    "replyCompletedAt": "ACTUAL_REPLY_COMPLETION_ISO_TIMESTAMP"
+  },
+  "steps": [
+    {
+      "id": "health-check",
+      "instruction": "Read the latest original conversation. Report readiness once; otherwise stay silent.",
+      "when": { "kind": "relative", "offset": "10m" }
+    }
+  ]
+}
+```
+
+```sh
+skrr followups plans create --agent YOUR_AGENT_ID --from-json plan.json --json
+```
+
+Relative time is measured from that reply's completion, so ensure the resulting time is still in the future. An envelope can explicitly separate delivery from evidence:
+
+```json
+{
+  "agentId": "YOUR_AGENT_ID",
+  "pinnedConversationId": "YOUR_CONVERSATION_ID",
+  "plan": { "objective": "...", "stopCondition": "...", "source": {}, "steps": [] }
+}
+```
+
+The envelope's abbreviated `plan` is structural guidance; replace it with the complete authored plan above. Optional delivery fields are `endpointId` and `endpointTarget`; source identity remains independent. `armed: true` confirms timer registration. A saved/pending result does not, and an existing terminal plan remains terminal on replay.
+
+## Time forms
+
+Each step's `when` accepts one of these shapes. Replace example dates with future dates:
+
+```json
+{"kind":"relative","offset":"10m"}
+```
+
+```json
+{"kind":"absolute","at":"2026-10-21T12:00:00Z"}
+```
+
+```json
+{"kind":"local","dateTime":"2026-10-21T09:00:00","timezone":"America/Los_Angeles"}
+```
+
+Absolute timestamps require `Z` or a UTC offset. Local times require an IANA timezone; ambiguous and nonexistent DST times are refused. A step may also have `label` and `expiresAfter` (for example `"1h"`). After expiry, the check must not execute. Top-level `title` and `timezone` are optional.
+
+## Inspect, revise and cancel
+
+```sh
+skrr followups plans list --agent YOUR_AGENT_ID --json
+skrr followups plans show PLAN_ID --json
+skrr followups plans revise PLAN_ID --revision 1 --from-json revised-plan.json --json
+skrr followups plans cancel PLAN_ID --revision 2 --reason "No longer needed" --json
+skrr followups plans observability --agent YOUR_AGENT_ID --json
+```
+
+Use the current revision returned by `show`. A stale edit returns `LOOKBACK_CONFLICT` with HTTP 409; reread before deciding whether to edit again. Revision JSON is the full authored plan itself, with the exact original source and existing step IDs. Start from `plan.json`, preserve IDs from `show`, and edit pending instructions/times. Do not resubmit the full `show` response: server fields such as `state`, `runAt`, `expiresAt`, outcomes and claims are not authoring input. Completed evaluations consume the same lifetime allowance after edits.
+
+Cancellation is idempotent and fences remaining work; it does not retract a message already delivered. `observability` reports a bounded sample, not lifetime totals. Normal account authority, budgets, runtime support and delivery policies still apply. No feature-flag enrollment or special two-person activation is needed.

package/docs/v1/operations.md

@@ -85,3 +85,55 @@ The npm CLI and signed native daemon are separately promoted artifacts. Updating
 For a failed CLI install, inspect Node version, npm prefix/PATH and package/plugin completeness before changing credentials. A missing `dist` in a source checkout requires a build; an architecture-specific dependency copied from another OS is not proof that the public tarball is broken. Keep the failing output and environment so support can distinguish those cases.
 
 Use the product's available support entry point or your deployment administrator and include the redacted evidence above. Do not assume a private GitHub issue link is accessible to an external user. See the [changelog](changelog.md) for this guide's scope and release gates.
+
+
+## Projects and task dependencies in a Space
+
+Projects are managed by the top-level `projects` topic. To group work into phases,
+create a project in the existing Space and attach its tasks. Replace `OSK-S-3`
+with your Space ref; use the project ref returned by `projects create` in place
+of `OSK-P-12`:
+
+```bash
+skrr projects create --space OSK-S-3 --title "Website launch"
+skrr projects list --space OSK-S-3
+skrr projects show OSK-P-12 --space OSK-S-3
+```
+
+A short project ref is unique within its Space. Pass `--space`, or write it as
+`OSK-S-3/OSK-P-12`. A canonical project UUID can resolve its owning Space on
+servers that support project lookup.
+
+Save this as `launch-tasks.json`. The tasks share a project; the `release` task
+waits for `build`. Dependencies refer to another node's `tempId`, independently
+of whether it is a parent, child, or sibling:
+
+```json
+{
+  "nodes": [
+    { "tempId": "build", "title": "Build website", "executionMode": "human", "assigneeUserIds": ["me"] },
+    { "tempId": "release", "title": "Release website", "executionMode": "human", "assigneeUserIds": ["me"], "blockedByTempIds": ["build"] }
+  ]
+}
+```
+
+```bash
+skrr tasks create-tree --space OSK-S-3 --project OSK-P-12 --from-json launch-tasks.json --dry-run --json
+skrr tasks create-tree --space OSK-S-3 --project OSK-P-12 --from-json launch-tasks.json --external-key-prefix website-launch --json
+```
+
+Use the returned task refs for inspection and changes. In this example,
+`OSK-102` is the release task and `OSK-101` is the build task:
+
+```bash
+skrr tasks show OSK-102 --json
+skrr tasks update OSK-102 --remove-blocked-by OSK-101
+skrr tasks update OSK-102 --add-blocked-by OSK-101
+```
+
+The JSON task contains `blockedByIds` (tasks it waits on) and `blocksIds` (tasks
+that wait on it). The server maintains reciprocal dependency edges. Task parent
+and child relationships are separate from dependency edges; `tasks descendants`
+queries hierarchy. For discovery, `spaces projects` and `spaces phases` point
+to Projects, while `tasks dependencies` and `tasks blockers` point to these
+inspection and update commands. These diagnostic hints do not execute writes.

package/docs/v1/space-search.md

@@ -0,0 +1,19 @@
+# Space search
+
+`skrr spaces list --q <query>` searches title, description, and identifier. Queries are trimmed and limited to 200 characters; longer queries fail instead of being silently shortened. All modes respect the caller's access, archive, label, and status filters before pagination.
+
+Choose a matching policy for the job:
+
+- `--match fuzzy` (the default) discovers related spaces. With Meilisearch enabled, results include tokenized, typo-tolerant index candidates and literal database substring matches. Index token dropping can return a space that does not contain the complete query. If the index is unavailable, this falls back to database substring matching.
+- `--match phrase` uses a literal case-insensitive substring in the stored fields. Word order and punctuation matter. It always queries the database, so a newly created space is searchable before indexing catches up.
+- `--match exact` requires case-insensitive equality with an entire stored field. Use it to check an existing title or identifier. It does not normalize punctuation or internal whitespace. Descriptions are matched as stored, including any markup.
+
+```sh
+skrr spaces list --q "Codex" --match fuzzy
+skrr spaces list --q "scratch space" --match phrase
+skrr spaces list --q "My workspace" --match exact --fields id,title --json
+```
+
+The response's `search` metadata reports the normalized query, requested mode, actual backend, effective semantics, searched fields, and the fuzzy index candidate bound. `candidates_may_be_truncated` means the index filled its candidate window; it is separate from `has_more`, which describes pagination of the matched visible rows. Fuzzy results cannot establish absence. For strict modes, page through `next_cursor` until `has_more` is false before treating the visible result set as complete. A lookup is not an atomic uniqueness guarantee for a subsequent create.
+
+Text output prints the effective policy. JSON preserves `search` alongside the pagination envelope; NDJSON includes it in stderr metadata. A CLI requesting an explicit policy fails if an older server does not confirm that policy, so a silently ignored flag cannot masquerade as an exact lookup.