@skrr-ai/cli 0.1.8

package/README.md

@@ -0,0 +1,1952 @@
+# @skrr-ai/cli
+
+Command-line interface for OverSky, wrapping the `@skrr-ai/data-provider` client.
+
+## Status
+
+**Comprehensive CRUD + workflow surface across the OverSky public API.**
+130+ commands across auth, conversations, messages, agents (+ groups + shares),
+universal triggers, spaces (+ members + briefs + heartbeats + triggers + widgets + skills),
+goals, tasks (+ comments + labels + approvals + attachments + cascade + DRI +
+observability), and shared links.
+
+### Command Catalog
+
+| Topic                                 | Commands                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **auth**                              | `login`, `logout`, `whoami`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| **convos**                            | `list` (`--agent`, `--search`, `--tag`, `--archived`, `--order`), `show`, `update`, `delete`, `archive`, `unarchive`, `fork`, `duplicate`, `import`                                                                                                                                                                                                                                                                                                                                                             |
+| **messages**                          | `list` (`--limit`, `--head`), `show`, `update`, `update-content`, `feedback`, `edit-artifact`                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| **agent call**                        | `request`, `show`, `cancel` — autonomous Agent → owner app voice-call invites; the owner must accept before a LiveKit call starts                                                                                                                                                                                                                                                                                                                                                                               |
+| **shares** (conversation share links) | `list`, `get`, `link-for`, `create`, `update`, `delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| **agents**                            | `list`, `show`, `overview`, `chat`, `create`, `update`, `attach-harness`, `delete`, `duplicate`, `revert`, `versions`, `visibility`, `schedule`, `upcoming`, `plan-day`, `reflect`, `schedule-overview`, `activity`                                                                                                                                                                                                                                                                                             |
+| **agents triggers**                   | `list`, `create`, `show`, `update`, `enable`, `disable`, `fire`, `delete`, `runs`, `replay`, `policy` (agent-scoped facade over the universal trigger engine)                                                                                                                                                                                                                                                                                                                                                   |
+| **agents todos**                      | `list`, `create`, `cancel` (the day-plan feed; Smart Schedule = `agents plan-day`)                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **agent-groups**                      | `list`, `show`, `create`, `update`, `delete`, `add`, `remove`                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| **agent-shares**                      | `received`, `sent`, `with`, `list-for`, `create`, `accept`, `decline`, `revoke`, `leave`                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **triggers**                          | `list`, `show`, `create`, `update`, `delete`, `enable`, `disable`, `fire`, `fire-detail`, `replay`, `audit`, `capabilities`, `event-catalog`, `parse-intent`, `rotate-secret`                                                                                                                                                                                                                                                                                                                                   |
+| **spaces**                            | `list`, `show`, `create`, `update`, `delete`, `archive`, `unarchive`, `tasks`, `conversations`, `snapshot`, `goals`, `revisions`, `subspaces`, `move`, `reorder`, `pin`, `summary`, `bootstrap`, `capacity`, `auto-executor update/preview/run`                                                                                                                                                                                                                                                                 |
+| **spaces members**                    | `list`, `search`, `add`, `remove`                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **spaces briefs**                     | `list`, `get`, `set`, `delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **spaces files**                      | `list`, `upload`, `rename`, `move`, `delete`, `folders list/create/update/delete`                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **spaces actions**                    | `list`, `add`, `update`, `delete`, `replace`                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **spaces views**                      | `list`, `create`, `update`, `delete`, `duplicate`, `reorder`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **spaces live**                       | `scene`, `cards list/create/update/delete/reorder`                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **spaces preferences**                | `show`, `tabs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **spaces heartbeats**                 | `list`, `create`, `update`, `delete`, `status`                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **spaces triggers**                   | `show`, `set`, `delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| **spaces widgets**                    | `list`, `add`, `remove`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| **spaces skills**                     | `list`, `add`, `remove`, `pin`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **spaces labels**                     | `list`, `add`, `remove` (attach/detach; filter with `spaces list --label`)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **labels**                            | `list`, `palette`, `create`, `update`, `archive`, `restore`, `delete`, `reorder` (unified labels across `user`, `space`, and `workspace` scopes)                                                                                                                                                                                                                                                                                                                                                                |
+| **chats triggers**                    | `show`, `set`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| **dm**                                | `list`, `show`, `messages`, `threads`, `thread show/messages/follow/mute/share`, `send` (agent 1:1 main chat and Slack-style Thread controls)                                                                                                                                                                                                                                                                                                                                                                   |
+| **diagnostics**                       | `context`, `doctor`, `usage`, `commands` (agent-friendly runtime identity, readiness, progressive token-budgeted discovery, and complete machine-readable schemas)                                                                                                                                                                                                                                                                                                                                             |
+| **goals**                             | `list`, `show`, `create`, `update`, `delete`, `descendants`, `tasks`, `archive`, `revisions`                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **commitments**                       | `list`, `show`, `create`, `plan`, `preflight`, `update`, `checks`, `check-now`, `autonomy`, `pause`, `resume`, `complete`, `subject`, `attach`, `detach`, `reports`, `export`, `import`, `fork` (durable agent commitment contracts)                                                                                                                                                                                                                                                                            |
+| **goals briefing**                    | `enable`, `disable`, `preview`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **tasks**                             | `list`, `show`, `create`, `upsert`, `create-tree`, `bulk-update`, `tree`, `update`, `delete`, `actionability`, `ready`, `start`, `active`, `monitor`, `watch`, `wait`, `continue-ready`, `move`, `complete`, `children`, `ancestors`, `descendants`, `activity`, `runs`, `execution-summary`, `execution-timeline`, `replay`, `checkout`, `release`, `start-all`, `cancel-cascade`, `cascade-status`, `dri-status`, `duplicate-pipeline`, `archive`, `today`, `prompt-log`, `revisions`, `transcript`, `output` |
+| **tasks input**                       | `show`, `answer`, `dismiss` (durable Human-input handoff)                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **tasks comments**                    | `list`, `add`, `anchor`, `delete`, `resolve`, `reopen` (human collaboration threads)                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| **tasks events**                      | `append`, `list`, `tail` (canonical typed append-only task facts)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **tasks labels**                      | `list`, `create`, `delete`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **tasks approvals**                   | `list`, `create`, `delete`, `resolve`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| **tasks attachments**                 | `list`, `delete`, `upload`, `download`                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| **integrations**                      | `toolkits`, `search`, `execute`, `tools list`, `tools allow`, `connections connect`, `connections list`, `connections finalize`, `connections disconnect`, `connections reconnect`                                                                                                                                                                                                                                                                                                                              |
+| **runtimes**                          | `start`, `list`, `status`, `exec`, `pull`, `connect`, `pause`, `resume`, `destroy` (OverSky Hosted Machine workspaces backed by the server runtime engine)                                                                                                                                                                                                                                                                                                                                                      |
+| **github**                            | `connect`, `finalize`, `connections`, `tools`, `run`, `allow-tools`, `reconnect`, `disconnect`                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **slack**                             | `send-as-agent`, `list-channels`, `list-users`, `read-channel`, `read-thread`, `tools`, `run`                                                                                                                                                                                                                                                                                                                                                                                                                   |
+
+### Reading history (conversations, tasks, agent output)
+
+Recent conversations, optionally scoped to one agent, then the transcript:
+
+```bash
+sky convos list --limit 10                     # id, title, agent, updated
+sky convos list --agent <agent-id>             # server-side agent scope
+sky convos list --search "login bug" --json    # Meilisearch-backed
+sky messages list -c <convo-id> --limit 20     # newest 20 (default: whole transcript)
+sky messages show <convo-id> <message-id>      # one message, full body
+```
+
+Tasks, and what the agent actually produced:
+
+```bash
+sky tasks list --assignee-agent <agent-id>     # what this agent is working on
+sky tasks show <task-id>                       # includes the Convo: pointer
+sky tasks output <task-id>                     # verdict + last-run + final agent message
+sky tasks transcript <task-id> --assistant-only  # full agent transcript, no prompt
+sky tasks comments list <task-id>              # raw comment thread
+```
+
+One agent's recent work across all three surfaces:
+
+```bash
+sky agents activity <agent-id> --limit 10      # merged DM + conversations + tasks feed
+```
+
+`--agent` / `agents activity` need a server that implements `?agentId=` on
+`GET /api/convos`. Against an older deployment `convos list --agent` fails with
+`SERVER_AGENT_FILTER_UNSUPPORTED` rather than returning another agent's
+conversations, and `agents activity` filters locally with a printed caveat.
+
+### Production CLI Contract
+
+Sky CLI is designed for both humans and daemon agents. New commands should
+preserve these contracts:
+
+- Positional args never read from stdin implicitly. Every `Args.string` must
+  set `ignoreStdin: true`; commands that consume stdin expose an explicit flag
+  or value such as `--from-json -` or an input arg whose literal value is `-`.
+- Machine callers use `--json` or `SKY_JSON=1`. Local validation errors,
+  auth errors, network errors, and API errors all emit `{ ok: false, error }`
+  in JSON mode.
+- Commands that accept `--from-json` also expose `--json`; typed flags override
+  JSON fields on conflict.
+- Agent runtime scripts start with `sky context --json`, then `sky usage --json`.
+  It is the recommended command-discovery bootstrap: the overview is generated
+  from the oclif manifest and stays within a small token budget. Read exactly
+  the relevant reference next with `sky usage tasks --json` (or the convenient
+  `sky tasks usage --json` form), then use `sky commands --schema "tasks list"`
+  only when the selected command needs its complete flag contract. Use
+  `sky doctor --json` for auth/build readiness and `sky commands --audit --json`
+  for command-surface hygiene.
+- Side-effecting commands use explicit idempotency keys only when the caller
+  owns retry coordination. Daemon session commands derive stable defaults when
+  possible, such as `sky agent message send --text "..."`.
+
+### Agent-initiated app voice calls
+
+`sky agent call` is a session-only consent flow, not a phone dialer. It reads
+the Agent identity and owner target from `OVERSKY_SESSION_TOKEN`,
+`OVERSKY_SESSION_ID`, and `OVERSKY_SESSION_AGENT_ID`; no flag or JSON field can
+select another person. The user receives an in-app/push invitation and must
+accept it before the normal LiveKit call is created.
+
+```bash
+# From an autonomous daemon session
+sky agent call request \
+  --reason "The production rollback decision needs you." \
+  --conversation <conversation-id> \
+  --expires-in 120 \
+  --json
+
+sky agent call show <call-id> --json
+sky agent call cancel <call-id> --json
+```
+
+The request is idempotent. With no explicit `--idempotency-key`, Sky derives a
+stable key from the daemon request plus the call payload. A second pending call
+from the same Agent to the same owner is coalesced rather than ringing again.
+
+This feature has no PSTN/SIP/Twilio integration and never accepts or stores a
+phone number. Calling a real mobile number is a separate Phase 2 capability:
+it requires verified-number ownership, explicit renewable consent, quiet-hour
+and frequency controls, recording consent, and a full audit trail. It is not a
+default Sky CLI capability.
+
+Run the hygiene audit before publishing CLI changes:
+
+```bash
+sky commands --audit --json
+```
+
+### PSTN phone calls (Phase 2)
+
+`sky agent phone-call request --purpose "…"` is an explicit, autonomous-
+session-only command. It does not accept a phone number, carrier setting,
+caller ID, or recording option; the server derives the owner and agent and
+uses only that owner's verified endpoint plus active, renewable consent.
+
+It is disabled unless the telephony deployment is configured, and is not an
+alias for the normal browser/LiveKit app call. Real mobile dialing requires a
+verified endpoint, explicit continuing consent, owner-selected quiet hours and
+frequency limits, a fixed AI/no-recording disclosure, and audit records.
+
+### Known Gaps
+
+Agent detail/config/mini-computer parity now includes provider-backed commands
+for preferences/notepad, agent files and folders, avatar upload/generation,
+intuitions, widget history/reordering, publishing releases, channel
+configuration, and workspace header scoping. Remaining gaps are architectural
+or intentionally not exposed as request/response APIs:
+
+- **Generic streaming chat** (`/api/agents/chat`, `/api/agentic/chat`): the CLI
+  has no SSE/WebSocket adapter — the node-adapter is pure request/response.
+  Chat streaming would need a separate client layer (Socket.io client + event
+  plumbing). This does not include persistent main-chat DM sends; use
+  `sky agent message send --text "..." --json` for that agent-facing path.
+- **2FA / OAuth / SAML / LDAP sign-in**: `sky login` exits code 6 on
+  `twoFAPending`. The server supports these; the CLI does not.
+- **Message delete**: `DELETE /api/messages/:convoId/:messageId` — server
+  only.
+- **Tests**: the CLI has focused Jest coverage, but broader command/API
+  contract coverage remains a follow-up.
+- **Task hierarchy reparenting via typed flag**: `tasks update` accepts
+  `parentId` only via `--from-json`. A typed `--parent` flag would be a small
+  follow-up.
+
+## Prerequisites
+
+- Node.js 20+
+- A running OverSky API (default target: `http://localhost:3080`)
+- `@skrr-ai/data-provider` must be built — it's a workspace dep and the CLI
+  imports from its `dist/`
+
+## Install
+
+From the repo root (the CLI is a workspace, so there's no separate install):
+
+```bash
+# 1. Install workspace deps (picks up cli/ because it was added to the root
+#    package.json "workspaces" array).
+npm install
+
+# 2. Build the data-provider if you haven't already.
+npm run build:data-provider
+
+# 3. Build the CLI.
+cd cli && npm run build
+```
+
+## Run
+
+From `cli/`:
+
+```bash
+./bin/run.js login
+./bin/run.js whoami
+./bin/run.js convos list
+./bin/run.js agents list
+./bin/run.js logout
+```
+
+Or globally, after `npm link` from `cli/`:
+
+```bash
+sky login
+sky convos list --json
+```
+
+## GitHub tools from local runtimes
+
+`sky github` is the GitHub-specific facade over OverSky's integration
+provider bridge. Local daemon sessions should set `OVERSKY_SESSION_AGENT_ID`;
+the CLI then binds every GitHub command to that selected agent and refuses a
+conflicting `--agent`.
+
+Connect GitHub for the selected agent:
+
+```bash
+sky github connect
+```
+
+List or search the agent's available GitHub tools:
+
+```bash
+sky github tools --json
+sky github tools "pull request" --json
+```
+
+Run a tool from stdin JSON. Use `--request-id` for side effects so a local
+runtime can safely retry the same action without firing it twice:
+
+```bash
+sky github run create_issue --request-id run_abc:github_1 --json - <<'JSON'
+{
+  "owner": "acme",
+  "repo": "app",
+  "title": "Bug from local runtime",
+  "body": "Details..."
+}
+JSON
+```
+
+Restrict or clear the GitHub tool allowlist for an agent:
+
+```bash
+sky github allow-tools --tools create_issue,list_pull_requests
+sky github allow-tools --all
+```
+
+Manage the OAuth grant:
+
+```bash
+sky github reconnect
+sky github disconnect
+sky github finalize <requestId>
+```
+
+## Hosted Machine workspaces
+
+`sky machines hosted` is the CLI surface for OverSky Hosted Machine sessions. It
+talks to `/api/agentic/sandbox-sessions`, so the CLI works with the OverSky
+session id (`sbs_...`) and never receives raw provider handles such as E2B
+sandbox ids.
+
+Start a scratch runtime and wait for it to become ready:
+
+```bash
+sky machines hosted start --name scratch --wait
+sky machines hosted list
+sky machines hosted status <runtime-id> --watch
+sky machines hosted pull <runtime-id> /home/user/app ./app-copy
+sky context --json
+sky agents attach-harness <runtime-id>
+```
+
+`runtimes start --agent <agent-id>` associates session metadata only. Use
+`agents attach-harness` to update the current/context agent's default runtime
+engine. In external scripts, pass `--agent <agent-id>` explicitly.
+
+Start and attach a GitHub repo. Repository access still flows through the
+server-side GitHub App, so the CLI needs the installation id:
+
+```bash
+sky machines hosted start \
+  --repo acme/app \
+  --installation-id 123 \
+  --branch main \
+  --wait
+```
+
+Run commands against a specific Hosted Machine session:
+
+```bash
+sky machines hosted exec <runtime-id> -- pwd
+sky machines hosted exec <runtime-id> --cwd /home/user/app -- npm test
+sky machines hosted pull <runtime-id> /home/user/app ./app-copy
+sky machines hosted connect <runtime-id>
+```
+
+`pull` copies files or directories back through the execute API as a tar.gz
+archive. `connect` is a lightweight command REPL over the same session execute
+API. It is intentionally not a raw provider shell and does not expose E2B
+sandbox ids.
+
+Lifecycle controls:
+
+```bash
+sky machines hosted pause <runtime-id>
+sky machines hosted resume <runtime-id> --wait
+sky machines hosted destroy <runtime-id>
+```
+
+For fast iteration while editing source, run the TypeScript compiler in watch
+mode in one terminal:
+
+```bash
+cd cli && npm run watch
+```
+
+…then invoke `./bin/run.js <cmd>` from another terminal. Each save recompiles
+to `dist/` and the next invocation picks up the change.
+
+## Commands
+
+### `sky login`
+
+Sign in to an OverSky instance.
+
+**You probably don't need to run this at all.** If the local `oversky`
+daemon is authenticated, every `sky` command silently auto-brokers a
+sibling cli-scope token on first use — no `sky login`, no browser, no
+device code, no user interaction whatsoever. See
+[Auto-broker on first use](#auto-broker-on-first-use) below.
+
+**When `sky login` is still useful:**
+
+- You want to log in to a DIFFERENT account than the daemon
+- You want to log in to a DIFFERENT server (`--base-url <url>`)
+- The daemon isn't installed / isn't running, and you want sky alone
+- You want to force a re-authentication (e.g. revoked refresh family)
+
+**Behavior when invoked explicitly:**
+
+- If the daemon is authed for the same server, `sky login` brokers the
+  handoff (still no browser).
+- If the daemon is not running or not authed, the CLI runs its own
+  PKCE-localhost OAuth flow (popping your browser); device-code is the
+  secondary fallback (SSH, port-bind failure, `--device-code`).
+
+```bash
+sky login
+sky login --base-url https://oversky.ai
+sky login --device-code      # skip broker + PKCE; use device-code directly
+```
+
+On first run, pass `--base-url` to target your API host. It is saved to
+`~/.sky/config.json` and reused until you override it again.
+
+Flags:
+
+- `-u, --base-url <url>` — API base URL to save and use
+- `--device-code` — force the device-code flow (also skips the
+  daemon broker pre-flight)
+- `--port <n>` — pin the localhost callback port (PKCE flow)
+- `--scope <cli|daemon>` — token scope (default `cli`)
+- `--recovery-code <code>` — non-interactive sign-in with a printable
+  recovery code
+
+Env overrides:
+
+- `OVERSKY_SKIP_DAEMON_BROKER=1` — disable the broker pre-flight
+- `OVERSKY_FORCE_DEVICE_CODE=1` — same as `--device-code`
+- `OVERSKY_REFRESH_TOKEN=...` + `OVERSKY_CLI_ID=...` — non-interactive
+  restore from a backed-up refresh token
+
+2FA, OAuth, SAML, and LDAP are not yet supported via the interactive
+PKCE / device-code flows. (The recovery-code path is unaffected.)
+
+### Auto-broker on first use
+
+Every `sky` command (except `login`, `logout`, `pair`,
+`generate-recovery-code`) runs the daemon-broker handoff transparently
+when no token is in the keychain. So:
+
+```bash
+oversky login                # authenticate the daemon, once
+sky tasks list               # silently auto-brokers, persists, runs
+sky tasks list --json        # uses the persisted token, no broker call
+sky whoami                   # confirms identity from the persisted token
+```
+
+There is no opt-in flag. The mechanism is the long-term default.
+
+**Skip rules** — auto-broker does NOT fire when any of these hold:
+
+- `--bare` flag is set (operator opted out of keychain/file persistence)
+- `OVERSKY_TOKEN` or `OVERSKY_REFRESH_TOKEN` env vars are set (operator
+  controls auth out-of-band — CI runners, ephemeral containers)
+- `OVERSKY_SKIP_DAEMON_BROKER=1` (explicit escape hatch for debugging
+  or testing the PKCE flow itself)
+- The command is one of `login`, `logout`, `pair`,
+  `generate-recovery-code` — these manage their own auth lifecycle
+
+**Failure handling.** If the broker can't reach the daemon, can't read
+its bootstrap file, or the daemon isn't authenticated, the auto-broker
+fails quietly and the command's normal `requireAuth()` produces the
+familiar "Not signed in. Run `sky login` first." error. The one case
+that gets a louder hint is baseURL mismatch, since the fix is precise:
+
+```
+[sky] Local oversky daemon is logged in to http://localhost:3080, but sky
+is configured for https://oversky.ai. Run `sky login --base-url http://localhost:3080`
+to use the daemon.
+Not signed in. Run `sky login` first.
+```
+
+### Daemon-as-broker handoff
+
+Mechanism for "logged-in daemon implies logged-in sky":
+
+1. `sky login` reads the daemon's bootstrap file:
+   - macOS: `~/Library/Application Support/OverSky/daemon-island.<profile>.json`
+   - Linux/Windows: `~/.oversky/profiles/<profile>/daemon-island.json`
+     (pre-Phase-K fallback: `~/.oversky/daemon-island.json`)
+2. CLI POSTs to `http://127.0.0.1:<port>/v1/auth/cli-handoff` with the
+   bootstrap secret as `Authorization: Bearer ...` and the requested
+   cliId in the body.
+3. Daemon's loopback handler (`daemon/src/auth/cliHandoff.ts`) forwards
+   to the server's `POST /api/daemons/cli-handoff` using the daemon's
+   own bearer as proof of "this user is already authenticated here".
+4. Server mints a **fresh cli-scope refresh family** (independent
+   rotation, distinct revocation, blast-radius isolated from the
+   daemon) bound to the supplied cliId.
+5. CLI persists via the canonical `writeToBackend()` — Keychain on
+   macOS, `cli-auth.json` elsewhere.
+
+Trust model is the same same-UID loopback fence the Socket.IO server
+uses: any attacker who can read the 0600 bootstrap file can already
+read the daemon's keychain. CI tokens are refused at the server
+(daemon bootstrapped from `osk_ci_*` cannot auto-elevate to CLI).
+
+### `sky logout`
+
+Sign out and clear the saved token. The `baseURL` is preserved so the next
+`sky login` defaults to the same host.
+
+```bash
+sky logout
+```
+
+The server-side logout call is best-effort — if the network is down, the
+local token is still cleared.
+
+### `sky whoami`
+
+Show the currently signed-in user.
+
+```bash
+sky whoami
+sky whoami --json
+```
+
+### `sky convos list`
+
+List recent conversations. Renders a column-aligned table by default; use
+`--json` for machine-readable output.
+
+```bash
+sky convos list
+sky convos list --json
+sky convos list --cursor <cursor-from-previous-page>
+```
+
+Flags:
+
+- `--json` — emit raw JSON instead of the table
+- `--cursor <cursor>` — pagination cursor returned from a previous page
+
+### `sky convos show <id>`
+
+Show details for a single conversation: title, endpoint, model, user, and
+timestamps. Pair with `messages list --convo <id>` to see the transcript.
+
+```bash
+sky convos show <convo-id>
+sky convos show <convo-id> --json
+```
+
+### `sky messages list --convo <id>`
+
+List messages in a conversation. Renders a table with time, role, text
+preview (truncated to 80 chars), and message ID. Use `--json` for the full
+message objects.
+
+```bash
+sky messages list --convo <convo-id>
+sky messages list --convo <convo-id> --json
+sky messages list -c <convo-id>
+```
+
+Flags:
+
+- `-c, --convo <id>` — conversation ID (required)
+- `--json` — emit raw JSON
+
+### `sky agents list`
+
+List agents available to the signed-in user.
+
+```bash
+sky agents list
+sky agents list --json
+```
+
+### `sky agents versions <id>`
+
+List an agent's edit-history snapshots so you know which index to revert to.
+The version array is EDIT-gated (it rides the expanded agent payload), so this
+needs EDIT permission on the agent — a VIEW-only caller gets a clear exit-3
+message. The printed **INDEX** is the literal `version_index` consumed by
+`sky agents revert`; index `0` is the genesis snapshot and the last row
+(marked `current`) is the live state.
+
+```bash
+sky agents versions <agent-id>
+sky agents versions <agent-id> --json
+# then revert to a listed index:
+sky agents revert <agent-id> --version 2
+```
+
+### `sky agents triggers ...` / `sky agents schedule`
+
+Agent-scoped automation. These are ergonomic facades over the universal Trigger
+Engine (`sky triggers`) that inject `scope=agent, agentId=<id>` for you — the
+same canonical surface the web agent page authors against (the legacy
+per-agent `/api/agents/:id/triggers` route is deprecated and intentionally not
+used here).
+
+```bash
+# List every trigger owned by an agent
+sky agents triggers list <agent-id>
+sky agents triggers list <agent-id> --kind schedule --enabled --json
+
+# Full authoring surface (all kinds + knobs)
+sky agents triggers create <agent-id> --kind schedule --cron "0 9 * * *" --prompt "Prepare the daily brief"
+sky agents triggers create <agent-id> --kind schedule --daily-time 09:00 --daily-time 14:00 --prompt "Check the queue"
+sky agents triggers create <agent-id> --kind schedule --interval-minutes 30 --prompt "Look for blockers"
+sky agents triggers create <agent-id> --kind once --at 2026-06-01T15:30:00Z --prompt "Send the launch recap"
+sky agents triggers create <agent-id> --kind event --entity task --event task.completed --prompt "Summarize the finished task"
+sky agents triggers create <agent-id> --kind form --form-fields '[{"id":"message","type":"textarea","label":"Message","required":true}]' --prompt "Review {{form.message}}"
+
+# Convenience one-liner for schedule-board cases (kind inferred from timing flags)
+sky agents schedule <agent-id> --cron "0 9 * * 1-5" --prompt "Prepare the daily brief"
+sky agents schedule <agent-id> --daily-time 09:00 --daily-time 14:00 --prompt "Check the queue"
+sky agents schedule <agent-id> --interval-minutes 30 --prompt "Look for blockers"
+sky agents schedule <agent-id> --at 2026-06-01T15:30:00Z --prompt "Send the launch recap"
+
+# Recurring with a lifetime cap / end date
+sky agents schedule <agent-id> --cron "0 9 * * 1-5" --prompt "Daily brief" --max-runs 20 --end-at 2026-12-31T00:00:00Z
+```
+
+The per-trigger lifecycle is wrapped under `agents triggers` too, taking
+`<agent-id> <trigger-id>` and validating the trigger is agent-scoped to that
+agent first (a fat-finger fence). They print the trigger ids via `agents
+triggers list`:
+
+```bash
+sky agents triggers show    <agent-id> <trigger-id>
+sky agents triggers fire    <agent-id> <trigger-id>     # the board's "Run"
+sky agents triggers disable <agent-id> <trigger-id>     # the board's "Disable"
+sky agents triggers enable  <agent-id> <trigger-id>
+sky agents triggers update  <agent-id> <trigger-id> --label "..." --cron "0 8 * * *" --max-runs 20
+sky agents triggers delete  <agent-id> <trigger-id> --yes
+sky agents triggers runs    <agent-id> <trigger-id>                 # fire history
+sky agents triggers runs    <agent-id> <trigger-id> --fire <fire-id>  # one fire's outcome + conversation
+sky agents triggers replay  <agent-id> <trigger-id> <fire-id>       # replay a historical fire
+sky agents triggers policy  <agent-id>                              # initiative policy summary
+```
+
+(For triggers in any other scope, or to operate on a trigger id regardless of
+scope, use the global `sky triggers <verb> <trigger-id>`.)
+
+### `sky agent message send`
+
+Send an agent-authored message through the canonical communication path. Main
+chat is the default destination; Slack owner DM and Slack channel destinations
+are also available. In daemon task runtimes the CLI derives the self identity
+and stable idempotency key from the bound session.
+
+```bash
+sky context --json
+sky agent message send --text "Done" --json
+sky agent message send --agent <agent-id> --text "Done" --json
+sky agent message send --agent <agent-id> --kind blocker --attention interrupt --text "I need your approval to continue" --json
+sky agent message send --text "Task is ready" --attach-task-card --json
+sky agent message send --destination slack_channel --channel C123 --text "Update" --json
+```
+
+`--attention` is an intent for app-owner DMs, not a channel override. The user’s
+notification settings and contextual gates choose actual reach. A separate
+user policy chooses quiet, standard, or time-sensitive native presentation;
+the sender cannot select an Android channel or iOS interruption level. Slack delivery
+does not use this policy, so the CLI rejects attention and notification-policy
+flags for Slack destinations instead of silently ignoring them.
+
+Task context does not render a Task Card by itself. Add `--attach-task-card`
+(or `presentation.taskCard: true` in JSON) only when the message should help
+the user open or follow the live task. Managed sessions derive trusted task
+identity server-side, so the Agent chooses presentation, not task identity.
+
+### `sky context`
+
+Print the current runtime identity without requiring a network round trip. This
+is the first command an automated agent should call when it needs to know
+whether it is running inside a daemon-bound agent session.
+
+```bash
+sky context --json
+sky context --json --include-account              # optional read-only /api/user lookup
+```
+
+### `sky agents upcoming <id>`
+
+The unified "what fires next" feed — the same source the web Schedule Board
+calendar plots. Merges pending scheduled messages, routine triggers assigned to
+the agent, and the agent's own schedule/once/self*scheduled triggers into one
+time-ordered stream (`GET /api/upcoming`). Unlike `agents triggers list` (which
+shows trigger \_definitions*), this shows concrete _occurrences_ with fire times.
+
+```bash
+sky agents upcoming <agent-id>
+sky agents upcoming <agent-id> --horizon-days 30 --expand all   # every occurrence in 30d
+sky agents upcoming <agent-id> --kinds agent_trigger --json
+```
+
+### `sky agents plan-day <id>` — Smart Schedule
+
+The CLI form of the Schedule Board's "Plan my day". A propose → review → approve
+flow: propose builds a DRAFT day plan from the agent's open tasks + working
+hours; nothing is scheduled until you approve.
+
+```bash
+sky agents plan-day <agent-id>                 # propose (or recover the pending draft) and print it
+sky agents plan-day <agent-id> --approve       # materialize the pending plan as to-dos
+sky agents plan-day <agent-id> --dismiss       # discard the pending plan
+sky agents plan-day <agent-id> --regenerate "prioritize the Q2 launch" \
+  --hours-start 09:00 --hours-end 17:00        # a fresh plan with a working-hours window
+```
+
+### `sky agents schedule-overview <id>` — full-visibility view
+
+One call for everything an agent needs when it wakes to think: its
+self-reflection-loop state, upcoming fires (future), recent fires (past), open
+tasks assigned to it, and today's to-dos. Stitches `GET /api/upcoming`,
+`/api/triggers/audit`, `/api/triggers`, `/api/tasks`, and `/api/todos` into one
+view; a failing source degrades to a `(unavailable: …)` note rather than failing
+the whole overview. `--json` emits the full aggregate for programmatic use.
+
+```bash
+sky agents schedule-overview <agent-id>
+sky agents schedule-overview <agent-id> --horizon-days 14 --json
+```
+
+### `sky agents reflect <id>` — the self-reflection loop
+
+The agent's meta-cadence loop: a single recurring trigger (`scope:agent,
+kind:schedule, execution.mode:run_only` — the same shape a personal-agent
+heartbeat uses) that fires a **silent** agent turn to review its own schedule and
+**retune its own cadence**. The cognition is entirely prompt-driven (no bespoke
+server logic); the loop is idempotent (located by a stable `self-reflection`
+label, so re-running retunes it rather than stacking duplicates) and coalesces so
+a slow reflection turn never overlaps itself. Default cadence is 6h. Pair it with
+`agents schedule-overview` — the reflection prompt tells the agent to open that
+view, judge its own rhythm, and reschedule this trigger.
+
+```bash
+sky agents reflect <agent-id>                   # status of the loop
+sky agents reflect <agent-id> --enable          # start it at the default 6h
+sky agents reflect <agent-id> --set-cadence 8h  # start / retune to a new interval
+sky agents reflect <agent-id> --set-cadence 90m --timezone America/New_York
+sky agents reflect <agent-id> --disable         # pause it (safe to re-enable later)
+```
+
+### `sky agents todos ...`
+
+The agent's day-plan feed (the web ToDoPanel). To-Dos are time-boxed work
+blocks — manual or produced by `plan-day`. Each is backed by a `once` trigger.
+
+```bash
+sky agents todos list <agent-id>               # today; --date YYYY-MM-DD for another day
+sky agents todos create <agent-id> --name "Draft update" --at 2026-06-01T09:00:00Z --prompt "Draft the weekly update." --duration 45
+sky agents todos cancel <todo-id> --yes
+```
+
+### `sky triggers ...`
+
+Manage raw Universal Trigger Engine rows for any supported scope.
+
+```bash
+sky triggers list --scope agent
+sky triggers create --scope agent --ref agentId=<agent-id> --kind schedule --mode send_message --cron "0 9 * * *" --prompt "Prepare the daily brief"
+sky triggers update <trigger-id> --no-enabled
+sky triggers fire <trigger-id>
+sky triggers audit <trigger-id>
+sky triggers audit --agent <agent-id> --limit 50
+sky triggers fire-detail <trigger-id> <fire-id>
+sky triggers replay <trigger-id> <fire-id>
+sky triggers event-catalog
+sky triggers parse-intent --scope agent --ref agentId=<agent-id> --message "Every weekday at 9, review tasks"
+sky triggers capabilities space_subscriber
+```
+
+Use `--from-json <file|->` on `create`, `update`, and `fire` for full request
+bodies. Scope refs are passed as repeatable `--ref key=value` flags.
+
+### `sky commitments ...`
+
+Durable **commitment contracts**. A commitment is not a unit of work — it is a
+standing commitment ("hold this outcome true") that an agent watches on a cadence
+with its own control loop: a fast _check_ (sense → project open loops → pick a
+posture → act) and a slower _reflection_ that retunes the commitment's own cadence
+from realized outcomes. Commitments sit above goals/tasks, which they watch as
+sensors and can create work in.
+
+```bash
+sky commitments list --agent <agent-id> --status active
+sky commitments show <commitment-id>
+sky commitments preflight <commitment-id>                    # explain gates before it runs
+
+# Author one (draft by default — read it back, then activate)
+sky commitments create --agent <agent-id> \
+  --title "Hiring loop" --outcome "Every candidate hears back within 48h" \
+  --watch tasks --watch email --cadence 12h
+sky commitments resume <commitment-id>          # activate
+
+# Or draft it from a sentence (read-only proposal)
+sky commitments plan --agent <agent-id> --sentence "Make sure every candidate hears back in 48h"
+
+# Steer it
+sky commitments update <commitment-id> --cadence 6h        # retune how often it checks
+sky commitments autonomy <commitment-id> --mode ask_first  # how much it may act alone
+sky commitments checks <commitment-id>                     # what it has been deciding
+sky commitments check-now <commitment-id>                  # run one iteration now
+sky commitments pause <commitment-id>                      # kill-switch
+```
+
+Autonomy ladder: `off` → `suggestions_only` (default) → `ask_first` →
+`auto_run_limited` → `auto_run`. Full reference:
+[docs/cli/SKRR_COMMITMENTS.md](../docs/cli/SKRR_COMMITMENTS.md).
+
+### `sky spaces` — perspective guide
+
+Run `sky spaces` before operating on an unfamiliar space. It maps each sidebar
+perspective to the command family and web route; use `--json` for agent discovery.
+
+```bash
+sky spaces
+sky spaces --json
+sky commands --schema "spaces files list"
+```
+
+Mutating bulk commands support validation-only planning with `--dry-run`:
+
+```bash
+sky spaces reorder --root --space <space-a> --space <space-b> --dry-run --json
+sky spaces views reorder <space-id> --view <view-a> --view <view-b> --dry-run --json
+sky spaces actions replace <space-id> --from-json actions.json --dry-run --json
+```
+
+### `sky spaces list`
+
+List spaces. Renders ID, title, status, goal count, and lead agent by default.
+
+```bash
+sky spaces list
+sky spaces list --status active
+sky spaces list --include-archived
+sky spaces list --json
+```
+
+Flags:
+
+- `--status <status>` — filter by space status
+- `--include-archived` — include archived spaces
+- `--limit <n>` — max results (default 50)
+- `--cursor <cursor>` — pagination cursor from a previous page
+- `--json` — emit raw JSON
+
+### `sky spaces show <id>`
+
+Show details for a single space.
+
+```bash
+sky spaces show <space-id>
+sky spaces show <space-id> --json
+```
+
+### `sky spaces create`
+
+Create a new space. `--title` is required unless you supply it in a JSON body.
+
+```bash
+sky spaces create --title "Q2 Launch"
+sky spaces create --title "Support" --status active --color "#4f46e5"
+sky spaces create --from-json space.json
+cat space.json | sky spaces create --from-json -
+sky spaces create --from-json template.json --title "Override title"
+```
+
+Flags: `--title`, `--description`, `--status`, `--color`, `--lead-agent`,
+`--target-date`, `--group-chat`, `--from-json <file|->`, `--json`.
+
+### `sky spaces update <id>`
+
+Partial patch. At least one flag (or `--from-json`) is required.
+
+```bash
+sky spaces update <space-id> --title "New title"
+sky spaces update <space-id> --status active --color "#4f46e5"
+sky spaces update <space-id> --from-json patch.json
+```
+
+Flags: `--title`, `--description`, `--status`, `--color`, `--lead-agent`,
+`--target-date`, `--from-json <file|->`, `--json`.
+
+### `sky spaces delete <id>`
+
+Delete a space. Prompts for confirmation by default; `--yes` skips the prompt.
+
+```bash
+sky spaces delete <space-id>
+sky spaces delete <space-id> --yes
+```
+
+When stdin is not a TTY (piped input, CI), the command refuses to prompt and
+exits with code 7 unless `--yes` is passed. This prevents hangs in
+non-interactive environments.
+
+### `sky spaces archive <id>` / `sky spaces unarchive <id>`
+
+Reversible alternative to `spaces delete`. Archives the space (setting
+`archivedAt`) without destroying its data; `unarchive` reverses it.
+
+```bash
+sky spaces archive <space-id>
+sky spaces unarchive <space-id>
+sky spaces archive <space-id> --json
+```
+
+### `sky spaces` — subspaces (parent / child hierarchy)
+
+Spaces form a tree. Each space tracks `parentSpaceId`, the materialized
+`ancestorSpaceIds` path, its `depth` (root = 0, capped at 20), and
+`inheritAccess` (default `true`) — when `inheritAccess` is `false` the space is
+a **private subspace** that does not inherit members/permissions from its parent
+chain. These mirror the web app's subspace features.
+
+```bash
+# Create a child space under a parent
+sky spaces create --title "Frontend" --parent <parent-space-id>
+
+# Create a private child that does NOT inherit the parent's members
+sky spaces create --title "Private notes" --parent <parent-space-id> --no-inherit-access
+
+# List the direct children of a space
+sky spaces subspaces <space-id>
+sky spaces subspaces <space-id> --include-archived --json
+
+# Move a space under a new parent (reparent) — the whole subtree follows
+sky spaces move <space-id> --parent <new-parent-space-id>
+
+# Detach a space back to the top level (no parent)
+sky spaces move <space-id> --root
+
+# Toggle inheritance on an existing space
+sky spaces update <space-id> --no-inherit-access   # make private
+sky spaces update <space-id> --inherit-access      # re-inherit from parents
+
+# Inspect a space's place in the tree (Parent / Depth / Ancestors / Inherits ACL)
+sky spaces show <space-id>
+```
+
+Server-side guards are surfaced as ordinary CLI errors: moving a space under
+itself or a descendant fails with `cycle_detected`; exceeding the depth cap
+fails with `max_depth_exceeded`; crossing workspaces fails with
+`workspace_mismatch`; and `spaces delete` refuses (`space_has_subspaces`) while
+a space still has children — move or delete them first. Reparenting requires
+EDIT on both the space and the target parent.
+
+### `sky spaces reorder` / `sky spaces pin`
+
+Reorder a complete sibling group atomically, or toggle the current user's
+sidebar pin for a space.
+
+```bash
+sky spaces reorder --root --space <space-a> --space <space-b>
+sky spaces reorder --parent <parent-id> --space <child-a> --space <child-b>
+sky spaces reorder --from-json order.json
+sky spaces reorder --from-json order.json --dry-run --json
+sky spaces pin <space-id>
+sky spaces pin <space-id> --json
+```
+
+The reorder JSON shape is `{ "parentSpaceId": null, "orderedIds": ["..."] }`.
+
+### `sky spaces summary` / `sky spaces bootstrap`
+
+Fetch the aggregated dashboard summary or the full bootstrap payload used by the
+space detail page.
+
+```bash
+sky spaces summary <space-id> --json
+sky spaces bootstrap <space-id> --json
+```
+
+### `sky spaces files ...`
+
+Manage the complete space file tree. Folder deletion requires `--yes` in
+non-interactive environments; pass `--delete-contents` when deleting a
+non-empty folder is intentional.
+
+```bash
+sky spaces files folders list <space-id>
+sky spaces files folders create <space-id> --name docs
+sky spaces files folders update <space-id> <folder-id> --name archive
+sky spaces files folders delete <space-id> <folder-id> --yes
+sky spaces files rename <space-id> <file-id> --filename report-final.pdf
+sky spaces files move <space-id> <file-id> --folder <folder-id>
+sky spaces files move <space-id> <file-id> --root
+sky spaces files delete <space-id> <file-id> --yes
+```
+
+### `sky spaces actions ...`
+
+Manage the custom actions displayed by a space's Actions surface. Action
+payloads can be supplied as JSON to preserve fields added by the server.
+
+```bash
+sky spaces actions list <space-id>
+sky spaces actions add <space-id> --id triage --label Triage \
+  --prompt "Triage the open tasks" --color "#4f46e5"
+sky spaces actions update <space-id> <action-id> --from-json action-patch.json
+sky spaces actions delete <space-id> <action-id> --yes
+sky spaces actions replace <space-id> --from-json actions.json
+sky spaces actions replace <space-id> --from-json actions.json --dry-run --json
+```
+
+### `sky spaces actions available <space-id>`
+
+List the agent quick actions attachable to tasks in a space (member agents'
+`agentActions`, filtered to enabled + scope general/this-space). Distinct from
+`sky spaces actions list` above, which manages the space's own custom actions.
+Each row's `REF` (`<agentId>:<actionId>`) feeds `sky tasks actions attach`.
+
+```bash
+sky spaces actions available <space-id>
+sky spaces actions available <space-id> --json
+```
+
+### `sky spaces views ...`
+
+Manage saved task views used by the Tasks perspective.
+
+```bash
+sky spaces views list <space-id>
+sky spaces views create <space-id> --name Board --type board --scope shared
+sky spaces views update <space-id> <view-id> --name "Launch board"
+sky spaces views duplicate <space-id> <view-id>
+sky spaces views reorder <space-id> --view <view-id> --view <other-view-id>
+sky spaces views delete <space-id> <view-id> --yes
+```
+
+### `sky views ...`
+
+Create persistent, personalized Task Views that can select exact task IDs or
+apply criteria across one or more Spaces. The create/show JSON response includes
+a durable `url`; opening it displays the view in a focused modal.
+
+```bash
+sky views create --name "Launch scope" --task-id <task-id> --task-id <task-id>
+sky views create --name "Cross-space blockers" \
+  --space <space-id> --space <space-id> --status blocked --group-by space
+sky views create --name "My reviews" --status in_review --assignee <id> --json
+sky views list
+sky views show <view-id>
+sky views delete <view-id> --yes
+
+### `sky space-directory-views ...`
+
+Manage global Space Directory Views. These are distinct from `sky spaces views`,
+which manages task views inside one Space.
+
+```bash
+sky space-directory-views list --json
+sky space-directory-views create --name "Active delivery" --config '{"schemaVersion":1,"layout":"list"}' --json
+sky space-directory-views update <view-id> --version 3 --from-json ./space-view-patch.json
+sky space-directory-views delete <view-id> --version 3 --yes
+```
+
+### `sky work-views ...`
+
+Manage saved cross-entity Work Views and read their ACL-safe Space-to-Task projection.
+
+```bash
+sky work-views list --json
+sky work-views create --from-json ./work-view.json --json
+sky work-views update <view-id> --version 2 --from-json ./work-view-patch.json
+sky work-views result <view-id> --json
+sky work-views delete <view-id> --version 2 --yes
+```
+```
+
+### `sky spaces live ...`
+
+Inspect and manage the Live perspective's cards and current-user character.
+
+```bash
+sky spaces live scene <space-id>
+sky spaces live scene <space-id> --character <character-id>
+sky spaces live cards list <space-id>
+sky spaces live cards create <space-id> --kind tasks --title Tasks --slot top
+sky spaces live cards update <space-id> <card-id> --enabled
+sky spaces live cards reorder <space-id> --card <card-id> --card <other-card-id>
+sky spaces live cards delete <space-id> <card-id> --yes
+```
+
+### `sky spaces preferences ...`
+
+Read and update the current user's server-backed space sidebar preferences.
+
+```bash
+sky spaces preferences show <space-id>
+sky spaces preferences tabs <space-id> \
+  --visible dashboard --visible tasks --hidden skills --hidden members
+sky spaces preferences tabs <space-id> --from-json tabs.json
+```
+
+### `sky spaces room ...` — the space's group chat
+
+Every space can have a **Room**: the group chat behind the Room tab on the
+space detail page. The link is a single field on the space (`space.groupChatId`),
+and the Room's group chat is tagged `space-room` + `space-room:<space-id>`.
+
+```bash
+# Who and what is in the Room (read-only — never creates)
+sky spaces room show <space-id>
+sky spaces room show <space-id> --json          # full payload incl. groupChatId
+
+# Create the Room if absent, and sync its members from the space (idempotent)
+sky spaces room ensure <space-id>
+
+# Read the transcript
+sky spaces room messages <space-id> --limit 50
+sky spaces room messages <space-id> --cursor <cursor>       # next page
+sky spaces room messages <space-id> --thread <message-id>   # one thread
+
+# Post to it
+sky spaces room send <space-id> -m "Standup in 5"
+sky spaces room send <space-id> -m "Take a look?" --mention agent:<agent-id>
+sky spaces room send <space-id> -m "Kickoff" --ensure       # create-then-send
+```
+
+**`ensure` is the only path that creates a Room.** `show` / `messages` / `send`
+read the existing link and fail with `space_room_not_found` when the space has
+never had its Room tab opened — the error names `ensure` as the fix. `ensure` is
+safe to re-run: it creates only when absent, otherwise it just reconciles the
+chat's participants and agents against the space membership. Run it after adding
+members or agents to a space if you drive the Room entirely from the CLI, since
+nothing else syncs them headlessly.
+
+**Mentions decide whether an agent answers.** Each agent in a chat has a trigger
+mode (`always` / `mention` / `keyword` / `manual`); a `mention`-mode agent stays
+silent unless it is mentioned. `sky spaces room show` prints each agent's mode so
+you can tell in advance. `--mention` is repeatable and accepts `agent:<id>`,
+`user:<id>`, `all` (or `everyone`), plus bare `agent_…` / bare 24-hex user ids.
+An ambiguous bare value is rejected rather than guessed.
+
+Room membership and settings are managed **from the space**, not the chat:
+`sky chats agents add`, `chats update`, and the participant routes all refuse a
+Room with `space_room_managed` (409). Use `sky spaces members ...` instead.
+Messaging is unaffected — `send` and `messages` work normally.
+
+The inverse lookup (chat → its spaces) is `sky chats spaces list --chat <chat-id>`.
+
+### `sky spaces triggers ...`
+
+Configure the current user's floating assistant triggers for a space.
+
+```bash
+sky spaces triggers show <space-id>
+sky spaces triggers set <space-id> --agent <agent-id> --event-enabled --event-type task.created
+sky spaces triggers set <space-id> --agent <agent-id> --schedule-enabled --schedule-mode daily --daily-time 09:00 --timezone America/New_York
+sky spaces triggers set <space-id> --agent <agent-id> --schedule-mode cron --cron "0 9 * * MON"
+sky spaces triggers delete <space-id> --yes
+```
+
+For event triggers, use `--event-type`, `--task-status`, `--visibility`,
+`--sender-type`, `--quiet-hours`, and rate-limit flags. For schedule triggers,
+use `--schedule-mode`, `--interval-minutes`, `--daily-time`, `--cron`,
+`--timezone`, `--working-hours`, and `--max-per-day`.
+
+### `sky chats send` / `sky chats messages`
+
+Read and post to any group chat by its id. These are the chat-addressed twins of
+`sky spaces room send` / `... messages` — same flags, same behaviour; only the
+way you name the chat differs.
+
+```bash
+sky chats messages <chat-id> --limit 50
+sky chats messages <chat-id> --cursor <cursor>       # next page
+sky chats messages <chat-id> --thread <message-id>   # replies in one thread
+
+sky chats send <chat-id> -m "Hello team!"
+sky chats send <chat-id> -m "Take a look?" --mention agent:<agent-id>
+sky chats send <chat-id> -m "Heads up" --mention all
+sky chats send <chat-id> -m "On it" --thread <message-id>
+sky chats send <chat-id> -m "Answering" --reply-to <message-id>
+```
+
+`--mention` is repeatable and accepts `agent:<id>`, `user:<id>`, `all` (or
+`everyone`), plus bare `agent_…` / bare 24-hex user ids; ambiguous bare values
+are rejected rather than guessed. Mentions matter because an agent whose trigger
+mode is `mention` will not respond to an unmentioned message. The server rejects
+a mention of anyone who is not already in the chat.
+
+`--thread <root-message-id>` posts into (or reads) a thread; `--reply-to` marks a
+direct reply without opening a thread.
+
+### `sky chats list`
+
+```bash
+sky chats list
+sky chats list --rooms            # only Space Rooms
+sky chats list --exclude-rooms    # only ordinary group chats
+sky chats list --limit 50 --cursor <cursor>
+```
+
+The `KIND` column reads `room` for a Space Room and `chat` otherwise, and the
+`SPACE` column names the owning space. Both come from the chat's tags
+(`space-room` + `space-room:<space-id>`), which the list endpoint now returns.
+
+`--rooms` / `--exclude-rooms` filter **the fetched page**, not the query — a Room
+on a later page is not excluded by `--rooms`, it was simply never fetched. For an
+authoritative space → Room lookup use `sky spaces room show <space-id>`, which
+resolves the link directly off the space.
+
+`sky chats show <chat-id>` flags a Space Room explicitly and names the space that
+owns it, so you learn membership is managed elsewhere before a mutation fails
+with `space_room_managed`.
+
+### `sky chats triggers ...`
+
+Configure the current user's assistant trigger preset for a group chat.
+
+```bash
+sky chats triggers show <chat-id>
+sky chats triggers set <chat-id> --agent <agent-id> --message-enabled --message-mode mention
+sky chats triggers set <chat-id> --agent <agent-id> --message-mode keyword --keyword urgent --keyword review
+sky chats triggers set <chat-id> --agent <agent-id> --schedule-enabled --schedule-mode interval --interval-minutes 60
+```
+
+The command writes the preset API (`/api/triggers/gcs-preset`), which expands
+message and schedule lanes into the underlying universal trigger rows.
+
+### `sky goals list`
+
+List goals. With `--space`, scopes to goals inside a specific space (uses
+the `listSpaceGoals` endpoint internally). Without it, the command uses the
+general `listGoals` endpoint with status/level filters.
+
+```bash
+sky goals list
+sky goals list --space <space-id>
+sky goals list --status active
+sky goals list --level company --json
+```
+
+Flags:
+
+- `--space <id>` — scope to goals in a specific space
+- `--status <status>` — filter by goal status
+- `--level <level>` — filter by goal level
+- `--include-archived` — include archived goals
+- `--limit <n>` — max results (default 50)
+- `--cursor <cursor>` — pagination cursor
+- `--json` — emit raw JSON
+
+### `sky goals show <id>`
+
+Show details for a single goal, including the DRI and completion percentage.
+
+```bash
+sky goals show <goal-id>
+sky goals show <goal-id> --json
+```
+
+### `sky goals create`
+
+Create a new goal. `--title` is required unless supplied via `--from-json`.
+
+```bash
+sky goals create --title "Ship Q2 roadmap"
+sky goals create --title "Milestone 1" --level milestone --parent <parent-id>
+sky goals create --from-json goal.json
+```
+
+Flags: `--title`, `--description`, `--level`, `--parent`, `--owner-agent`,
+`--dri-agent`, `--dri-user`, `--from-json <file|->`, `--json`.
+
+### `sky goals update <id>`
+
+Partial patch.
+
+```bash
+sky goals update <goal-id> --title "New title"
+sky goals update <goal-id> --status active --dri-user <user-id>
+sky goals update <goal-id> --from-json patch.json
+```
+
+Flags: `--title`, `--description`, `--level`, `--status`, `--parent`,
+`--owner-agent`, `--dri-agent`, `--dri-user`, `--from-json <file|->`, `--json`.
+
+### `sky goals delete <id>`
+
+Delete a goal. Same confirmation behavior as `spaces delete`.
+
+```bash
+sky goals delete <goal-id>
+sky goals delete <goal-id> --yes
+```
+
+### `sky tasks list`
+
+List tasks. All filter flags are passed through to `listTasks` as params;
+combine freely.
+
+```bash
+sky tasks list
+sky tasks list --space <space-id>
+sky tasks list --goal <goal-id> --status in_progress
+sky tasks list --space <space-id> --external-key ws0/root --json
+sky tasks list --q "login bug"
+sky tasks list --priority high --json
+```
+
+Flags:
+
+- `--space <id>` — filter by space ID
+- `--goal <id>` — filter by goal ID
+- `--parent <id>` — filter by parent task ID (lists direct children)
+- `--status <status>` — filter by task status
+- `--priority <priority>` — filter by task priority
+- `--external-key <key>` — filter by caller-supplied idempotency key
+- `--q <query>` — free-text search
+- `--limit <n>` — max results (default 50)
+- `--cursor <cursor>` — pagination cursor
+- `--json` — emit raw JSON
+
+The table shows the task ref (identifier or `#taskNumber`), title, status,
+priority, assignee counts (`Na/Mu` = N agents, M users), and ID.
+
+### Current task defaults
+
+In daemon task runtimes, the CLI reads `OVERSKY_SESSION_TASK_ID` as the
+canonical current task. Agent-facing task commands therefore accept no task
+positional when the current task is obvious:
+
+```bash
+sky tasks show --json
+sky tasks comments add --body "Done investigating." --json # human discussion comment
+sky tasks events append --kind checkpoint --summary "Done investigating." --idempotency-key investigation-1 --json
+sky tasks complete --summary "Shipped the fix." --artifacts none --verdict approved --json
+sky tasks move --status in_progress --json
+```
+
+Use `--task <task-id>` when a script intentionally operates on a different
+task. `--from-json` payloads may include `taskId` for commands that accept a
+task-scoped JSON body; the CLI uses it for routing and strips it from the API
+payload before sending the business fields.
+
+### `sky tasks show [id]`
+
+Show details for a single task. Enriched by default — pass `--no-enrich` to
+skip the server-side enrichment (assignee names, parent titles).
+
+```bash
+sky tasks show <task-id>
+sky tasks show
+sky tasks show --task <task-id> --json
+sky tasks show <task-id> --json
+sky tasks show <task-id> --no-enrich
+```
+
+### `sky tasks create`
+
+Create a new task. `--title` is required unless supplied via `--from-json`.
+The assignee flags are repeatable — pass `--assignee-agent` multiple times to
+assign several agents.
+
+```bash
+sky tasks create --title "Fix login bug" --space <space-id>
+sky tasks create --title "Design review" --space <space-id> --goal <goal-id> --priority high
+sky tasks create --title "Runnable by default" --space <space-id> --default-agent auto
+sky tasks create --title "QA pass" \
+  --assignee-agent <agent-id> \
+  --assignee-agent <other-agent-id> \
+  --tag release --tag urgent \
+  --label-id <existing-label-id>
+sky tasks create --title "Follow up" --source-conversation <conversation-id>
+sky tasks create --title "Spec task" --external-key ws0/spec --dry-run --json
+sky tasks create --from-json task.json
+```
+
+When no assignee is supplied, `sky tasks create` uses a deterministic default:
+the bound daemon-session agent, the lead agent for a space-scoped task, or the
+only message-eligible agent in an unscoped personal task. If an unscoped CLI
+has multiple eligible agents, the command fails and asks for an explicit
+assignee instead of guessing. An explicit empty `assigneeAgentIds` or
+`assigneeUserIds` array remains the opt-out for intentionally unassigned work.
+
+Inside a Local Daemon agent session, `sky tasks create` also defaults missing
+`sourceConversationId` and `spaceId` from the session env when available.
+
+`--default-agent` overrides the automatic default. `--default-agent auto`
+injects the space lead agent, while an explicit agent ID selects that agent.
+An explicit `--assignee-agent`/`assigneeAgentIds` or `--assignee-user`/
+`assigneeUserIds` always wins.
+
+When `--project <canonical-project-id>` or `--parent <task-id>` is supplied
+without `--space`, the CLI resolves the inherited Space before choosing the
+default assignee. Project refs still require `--space`; canonical project IDs
+are globally resolvable.
+
+Tags are lightweight free-form keywords. Labels are shared workspace taxonomy
+and are attached by opaque ID; discover existing IDs with
+`sky tasks labels list --json`. Both are optional and repeatable at creation.
+
+Flags: `--title`, `--description`, `--description-format`, `--external-key`,
+`--default-agent`,
+`--priority`, `--parent`, `--space`, `--goal`,
+`--source-conversation`, `--source-message`, `--assignee-agent`
+(repeatable), `--assignee-user` (repeatable), `--due-date`, `--tag`
+(repeatable), `--label-id` (repeatable), `--from-json <file|->`, `--dry-run`,
+`--json`.
+
+### `sky tasks upsert`
+
+Create or update one task by `externalKey`. The lookup is scoped by any
+provided `--space`, `--goal`, and `--parent`, so title changes do
+not create duplicates.
+
+Automatic assignee defaults apply only when the upsert creates a new task.
+Updating an existing task preserves omitted assignment fields, including an
+intentional unassigned state. Pass an explicit assignee or `--default-agent`
+to change/fill assignment during an update.
+
+```bash
+sky tasks upsert --space <space-id> --external-key ws0/root --title "WS0 root"
+sky tasks upsert --space <space-id> --external-key ws0/root --title "WS0 root" --default-agent auto
+sky tasks upsert --space <space-id> --external-key ws0/root --from-json task.json --json
+```
+
+### `sky tasks create-tree`
+
+Create a whole task tree from JSON. The command returns a `mapping` object from
+input `tempId` (or generated path like `0.1`) to the real task id. If a node has
+`externalKey`, or `--external-key-prefix` is provided, that node is upserted
+instead of blindly duplicated.
+
+```bash
+sky tasks create-tree --from-json tree.json --space <space-id> --json
+sky tasks create-tree --from-json tree.json --space <space-id> --default-agent auto
+sky tasks create-tree --from-json tree.json --external-key-prefix recursive-learning/ws0
+sky tasks create-tree --from-json tree.json --dry-run --json
+```
+
+Nodes without assignees inherit their parent node's assignee first, then use
+the same automatic default as `tasks create`. `--default-agent auto` makes the
+space-lead fallback explicit for a tree. Nodes matched by `externalKey` keep
+their existing assignment unless the input explicitly supplies assignees or
+`--default-agent` fills an unassigned task.
+
+Minimal `tree.json`:
+
+```json
+{
+  "root": {
+    "tempId": "root",
+    "title": "Build Harness Self-Improvement initiative",
+    "children": [{ "tempId": "ws0", "title": "WS0 - Activate dark features" }]
+  }
+}
+```
+
+### `sky tasks plan ...`
+
+Create and operate the Implementation Workflow owned by a parent Task. Work
+nodes always reference real direct subtasks; control nodes may add approvals,
+waits, branches and bounded review.
+
+```bash
+sky tasks plan create <task-id> --json
+sky tasks plan show <task-id>
+sky tasks plan add-subtask <task-id> --title "Implement the API" --agent <agent-id>
+sky tasks plan sync <task-id>
+sky tasks plan update <task-id> --from-json plan-update.json --json
+sky tasks plan start <task-id> --start-identity implementation-v1 --json
+sky tasks plan run <task-id> <run-id> --json
+sky tasks plan pause <task-id> <run-id> <node-key>
+sky tasks plan resume <task-id> <run-id> <node-key>
+sky tasks plan retry <task-id> <run-id>
+sky tasks plan reconcile <task-id> <run-id>
+sky tasks plan cancel <task-id> <run-id> --yes
+```
+
+### `sky tasks bulk-update`
+
+Apply partial patches to many tasks. Use `status` in a patch to route that item
+through the canonical move endpoint; other fields use `tasks update`.
+
+```bash
+sky tasks bulk-update --from-json updates.json --json
+sky tasks bulk-update --from-json updates.json --continue-on-error
+```
+
+Accepted JSON shapes:
+
+```json
+{
+  "updates": [
+    { "id": "task-1", "priority": "high", "status": "in_progress" },
+    { "id": "task-2", "data": { "goalId": "goal-1", "tags": ["release"] } }
+  ]
+}
+```
+
+### `sky tasks tree [id]`
+
+Fetch a root task plus descendants and render the hierarchy. With `--goal`,
+fetch tasks linked to a goal and render a forest of root tasks plus subtasks.
+`--json` returns either nested `tree.children[]` for a root task or
+`trees[].children[]` with `object: "goal_task_forest"` for a goal.
+
+```bash
+sky tasks tree <root-task-id>
+sky tasks tree <root-task-id> --limit 1000 --json
+sky tasks tree --goal <goal-id>
+sky tasks tree --goal <goal-id> --json
+```
+
+Flags: `--goal <id>`, `--limit <n>`, `--cursor <cursor>` (goal mode),
+`--no-enrich` (root-task mode), `--json`.
+
+### `sky tasks update [id]`
+
+Partial patch. Assignees can be replaced wholesale (`--assignee-agent`) or
+mutated incrementally (`--add-assignee-agent`, `--remove-assignee-agent`) so
+you don't have to re-send the full list.
+
+```bash
+sky tasks update <task-id> --title "New title"
+sky tasks update --title "New title"
+sky tasks update --task <task-id> --title "New title" --json
+sky tasks update <task-id> --priority high --due-date 2026-05-01
+sky tasks update <task-id> --add-assignee-agent <agent-id>
+sky tasks update <task-id> --remove-assignee-user <user-id>
+sky tasks update <task-id> --from-json patch.json
+```
+
+Flags: `--title`, `--description`, `--priority`, `--due-date`, `--goal`,
+`--assignee-agent`/`--assignee-user` (replace, repeatable),
+`--add-assignee-agent`/`--remove-assignee-agent` (incremental, repeatable),
+`--add-assignee-user`/`--remove-assignee-user` (incremental, repeatable),
+`--tag` (replace, repeatable), `--from-json <file|->`, `--json`.
+
+**Note**: `TaskUpdateParams` in the data-provider does not expose a `status`
+field — use [`sky tasks move [id] --status <status>`](#sky-tasks-move-id---status-status)
+to transition between states like `todo`, `in_progress`, `blocked`, or
+`completed`. `tasks update` handles everything else.
+
+### `sky tasks complete [id]`
+
+Post the canonical `---TASK_OUTPUT---` closeout comment and move the task to a
+terminal status. In a task daemon session, omit the id to complete the current
+task.
+
+```bash
+sky tasks complete --summary "Shipped the fix." --artifacts none --verdict approved --json
+sky tasks complete <task-id> --summary "Shipped the fix." --verdict approved
+sky tasks complete --task <task-id> --status failed --summary "Blocked by missing access" --verdict blocked
+sky tasks complete --from-json task-output.json --json
+```
+
+`--status completed` moves the task to `done`; `--status failed` moves it to
+`failed`. Pass `--no-move` when another runner owns the status transition.
+
+### `sky tasks delete <id>`
+
+Delete a task. Same confirmation behavior as `spaces delete`.
+
+```bash
+sky tasks delete <task-id>
+sky tasks delete <task-id> --yes
+```
+
+### `sky tasks start [id]`
+
+Start execution of a task. The server spawns a conversation and a session,
+then streams progress via the agentic WebSocket (not wrapped by the CLI yet).
+The command returns immediately after starting and prints the conversation
+and session IDs so you can follow up elsewhere.
+
+```bash
+sky tasks start <task-id>
+sky tasks start
+sky tasks start --task <task-id> --json
+sky tasks start <task-id> --skill <skill-id>   # run with a pinned space-skill
+sky tasks start <task-id> --json
+sky tasks start OSK-123 --branch               # create/check out oversky/task/OSK-123
+```
+
+With no explicit task or daemon session context, task commands can infer
+`OSK-123` from the current `oversky/task/OSK-123` branch. Verify that local
+context with `sky tasks current` (it makes no network request).
+
+Sample output:
+
+```
+Started task task-abc123
+Conversation: convo-xyz789
+Session:      session-456
+```
+
+### Continuous execution control
+
+Use these commands when a script or operator starts several agent sessions and
+needs visibility after `tasks start` returns.
+
+```bash
+# What is occupying execution capacity in a space?
+sky spaces capacity <space-id>
+
+# Raise/lower the execution concurrency cap without enabling auto-execute
+sky spaces auto-executor update <space-id> --max-active-tasks 6
+
+# Show active task sessions under a space or root task
+sky tasks active --space <space-id>
+sky tasks active --root <root-task-id>
+sky tasks active
+
+# One-shot operator snapshot: counts, active sessions, recent events, failures
+sky tasks monitor <root-task-id>
+
+# Human-facing polling stream
+sky tasks watch <root-task-id> --descendants --children-only
+
+# Script gate: wait for prerequisites, then continue ready children
+sky tasks wait <task-a> --task <task-b> --until done --timeout 30m
+sky tasks wait --until done --timeout 30m
+sky tasks continue-ready <root-task-id> --max-starts 3
+```
+
+On current servers, `continue-ready` consumes the canonical dependency and
+next-actor projection. The legacy `depends: WS-x.y` parser remains only as a
+compatibility fallback for older servers. It also clamps starts to free space
+capacity unless `--ignore-capacity` is passed.
+
+### `sky tasks interrupt <id>`
+
+Stop a running task. Mirrors the web editor's "Stop execution" affordance —
+posts an interrupt-flagged comment that the agent runtime honors. The
+optional `--reason` text lands in the activity log so reviewers can see
+who stopped what and why.
+
+```bash
+sky tasks interrupt <task-id>
+sky tasks interrupt <task-id> --reason "wrong file"
+```
+
+### Inline anchored comments
+
+Two complementary commands. `comments add` is the low-level primitive —
+it records the anchor row but does NOT touch the description, so the
+caller is responsible for ensuring a matching `<span data-comment-id="…">`
+exists. `comments anchor` is the one-shot helper that does both in a
+single atomic flow.
+
+#### `sky tasks comments anchor` — one-shot find-and-wrap (recommended)
+
+Finds the quote in the current task description, wraps the matched
+occurrence in `<span class="inline-comment" data-comment-id="…">…</span>`,
+PATCHes the description back with optimistic-lock (`expectedVersion`),
+then posts the inline comment with the matching mark id. If the comment
+POST fails, the description is rolled back so the task is never left
+with an orphan span.
+
+```bash
+sky tasks comments anchor <task-id> \
+  --quote "the offending sentence" \
+  --body "Needs rewording"
+
+# Pick a later occurrence when the phrase repeats
+sky tasks comments anchor <task-id> --quote "TODO" --occurrence 2 --body "Pick one"
+
+# Preview the description change without committing
+sky tasks comments anchor <task-id> --quote "…" --body "…" --dry-run
+
+# Pre-mint the mark id (useful when you want to reference it from automation)
+sky tasks comments anchor <task-id> \
+  --quote "…" --body "…" --anchor-mark-id my-mark-1
+```
+
+The quote must live in a **single HTML text run** in the description.
+TipTap-style spans across formatting marks (e.g. `the <em>offending</em>
+sentence`) are rejected with a clear error — the editor would have to
+break the `<em>` mark to wrap them, which would change the document's
+semantics. Workaround: flatten the formatting first with
+`sky tasks update <id> --description …`, then re-run.
+
+> **Important — collab safety.** If a collaborative editing session is
+> open on the same task, the server's description renderer
+> (`CollabDescriptionRenderer`, 2s tick) will overwrite your PATCH with
+> a fresh render from the Y.Doc, dropping the span you injected. The CLI
+> isn't a Yjs peer so it can't speak the same wire protocol. Prefer the
+> web editor when live collaborators are actively typing.
+
+#### `sky tasks comments add --anchor-mark-id / --anchor-quote` (low-level)
+
+Records the anchor row without modifying the description. Useful when you
+already managed the span (e.g. via a web edit session) or you don't need
+the visible inline-comment style — the comment still threads in the
+rail, just without a highlighted phrase.
+
+| Flag                      | Meaning                                                                                               |
+| ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `--anchor-mark-id <id>`   | Mark id that matches the `data-comment-id` span in the description. Must match `[a-zA-Z0-9_-]{1,64}`. |
+| `--anchor-quote "<text>"` | Captured quote shown in the comments rail. Truncated to 500 chars to match the editor.                |
+
+Pass `--anchor-quote` alone and the CLI mints a UUID for the mark id,
+mirroring the web editor's `handleAddInlineComment`. You must still
+apply a matching `data-comment-id` span to the description for the
+in-document chip to render.
+
+```bash
+# Mint markId for me, attach to a quote
+sky tasks comments add <task-id> \
+  --body "This phrase needs rewording" \
+  --anchor-quote "the offending sentence"
+
+# Current task in a daemon task runtime
+sky tasks comments add --body "This phrase needs rewording" --json
+
+# Pre-minted markId (matches a span you already added)
+sky tasks comments add <task-id> \
+  --body "Pre-minted anchor" \
+  --anchor-mark-id my-mark-123 \
+  --anchor-quote "context"
+
+# Threaded reply (anchor on a reply is silently dropped; replies inherit
+# the parent's anchor server-side)
+sky tasks comments add <task-id> \
+  --body "+1" \
+  --parent-comment <root-comment-id>
+```
+
+### `sky tasks dri-run <id>` / `sky tasks dri-plan <id>`
+
+The DRI ("Directly Responsible Individual") card on the task detail page
+exposes two execution modes:
+
+| Web button                                                 | CLI                       |
+| ---------------------------------------------------------- | ------------------------- |
+| **Execute** — run the task via the DRI agent only          | `sky tasks dri-run <id>`  |
+| **Plan** — DRI agent plans subtasks then runs the pipeline | `sky tasks dri-plan <id>` |
+
+Both print the resulting `conversationId` + `sessionId`. Use the regular
+`sky tasks start` (with `--skill` if needed) when you want to run as the
+caller without invoking the space's DRI agent.
+
+### `sky tasks forward <id> --to <group-chat-id>`
+
+Forward a task as an embedded card into one or more group chats. Server
+returns 200 on partial success — failed targets are listed with a precise
+reason (`not_found`, `not_member`, `no_send_permission`, `error`). If
+_every_ target failed the CLI exits with code 6 so scripts notice.
+
+```bash
+sky tasks forward <task-id> --to <group-chat-id>
+sky tasks forward <task-id> --to <gc-a> --to <gc-b> --note "FYI"
+```
+
+### Scheduling: `schedule`, `unschedule`, `retry-schedule`, `pause-schedule`, `resume-schedule`
+
+The web editor's TaskScheduleModal maps to five flat verbs:
+
+```bash
+# One-shot
+sky tasks schedule <task-id> --at 2026-06-01T15:30:00Z
+
+# Recurring (cron is interpreted in --timezone if provided, else UTC)
+sky tasks schedule <task-id> \
+  --at 2026-06-01T09:00:00Z \
+  --cron "0 9 * * 1-5" \
+  --timezone America/Los_Angeles \
+  --max-runs 20
+
+# Clear schedule entirely
+sky tasks unschedule <task-id>
+
+# Re-arm after a stale/failed fire — optionally pin a new first-fire time
+sky tasks retry-schedule <task-id>
+sky tasks retry-schedule <task-id> --at 2026-06-02T15:00:00Z
+
+# Pause / resume a recurring schedule without losing its definition
+sky tasks pause-schedule <task-id>
+sky tasks resume-schedule <task-id>
+```
+
+Pass `--from-json schedule.json` to `schedule` for fields not exposed as
+typed flags (matches the `TaskScheduleParams` shape).
+
+### `sky tasks tags add` / `sky tasks tags remove`
+
+Incremental tag mutation. (`sky tasks update --tag …` is a whole-list
+replacement — use these when you want to _add_ one without clobbering the
+rest.) Tags are lowercased + deduped to match the web editor's behavior.
+
+```bash
+sky tasks tags add <task-id> --tag urgent --tag follow-up
+sky tasks tags remove <task-id> --tag follow-up
+```
+
+### `sky tasks skills pin` / `sky tasks skills unpin`
+
+Pin one or more space-curated skills onto a task (max 5 total — server
+enforces). The skill must already be pinned at the space level
+(`Space.skillIds`); the server rejects unknown ids with 4xx.
+
+```bash
+sky tasks skills pin   <task-id> <skill-id> [<skill-id-2> ...]
+sky tasks skills unpin <task-id> <skill-id> [<skill-id-2> ...]
+```
+
+### `sky tasks actions attach` / `sky tasks actions detach`
+
+Attach agent quick actions onto a task (`Task.attachedActionRefs`, max 50) so
+their prompts are injected as a task-specific playbook on every run. The task
+must belong to a space. Discover refs with
+`sky spaces actions available <space-id>`.
+
+```bash
+sky tasks actions attach <task-id> <agentId>:<actionId> [<ref-2> ...]
+sky tasks actions detach <task-id> <agentId>:<actionId> [<actionId> ...]
+```
+
+### `sky tasks move [id] --status <status>`
+
+Change a task's status. This is the canonical status-transition endpoint —
+`tasks update` does NOT expose a status field (see
+`TaskUpdateParams` in the data-provider), so `tasks move` is how you
+transition between states like `todo`, `in_progress`, `blocked`, `failed`,
+and `done`.
+
+```bash
+sky tasks move <task-id> --status in_progress
+sky tasks move --status in_progress
+sky tasks move --task <task-id> --status done --json
+sky tasks move <task-id> --status done
+sky tasks move <task-id> --status blocked --json
+```
+
+The server validates the status string — invalid values return an error.
+
+## The inspection loop
+
+A useful tour of an OverSky workspace from the CLI:
+
+```bash
+sky spaces list
+sky spaces show <space-id>
+sky goals list --space <space-id>
+sky tasks list --space <space-id> --status in_progress
+sky tasks show <task-id>
+sky tasks start <task-id>                    # kicks off execution
+sky convos show <convo-id>                   # the returned conversation
+sky messages list --convo <convo-id>         # follow the transcript
+```
+
+Pipe any step to `jq` with `--json` for scripting:
+
+```bash
+sky tasks list --space <space-id> --json | jq '.data[] | select(.priority == "high")'
+```
+
+## Task workflow quick-reference
+
+The commands that move a task through its lifecycle, most to least common:
+
+| Action              | Command                                                            |
+| ------------------- | ------------------------------------------------------------------ |
+| Complete task       | `sky tasks complete [id] --summary "..." --verdict approved`       |
+| Change status       | `sky tasks move [id] --status <new-status>`                        |
+| Start execution     | `sky tasks start [id]` (optionally `--skill <id>`)                 |
+| Stop a running task | `sky tasks interrupt <id>`                                         |
+| Run via DRI agent   | `sky tasks dri-run <id>` / `sky tasks dri-plan <id>`               |
+| Schedule a fire     | `sky tasks schedule <id> --at <iso>` (`--cron …` for recurring)    |
+| Pause / resume cron | `sky tasks pause-schedule <id>` / `sky tasks resume-schedule <id>` |
+| Forward to chats    | `sky tasks forward <id> --to <group-chat-id>`                      |
+| Incremental tags    | `sky tasks tags add/remove <id> --tag …`                           |
+| Pin/unpin skills    | `sky tasks skills pin/unpin <id> <skill-id>`                       |
+| Delete              | `sky tasks delete <id>`                                            |
+
+`tasks update` handles every other field (title, description, priority,
+assignees, due date, goal) but explicitly does NOT touch status — use
+`tasks move` for that.
+
+## The `--from-json` pattern
+
+Every `create` and `update` command accepts `--from-json <file-or-dash>` as a
+universal escape hatch for fields not exposed as typed flags. The body is a
+plain JSON object matching the data-provider's `*CreateParams` /
+`*UpdateParams` shape. Typed flags override fields in the JSON on conflict,
+so you can template a base body and tweak it per-invocation:
+
+```bash
+# Template a reusable base
+cat > task-template.json <<'EOF'
+{
+  "spaceId": "space-abc",
+  "priority": "high",
+  "tags": ["release"],
+  "assigneeAgentIds": ["agent-qa"]
+}
+EOF
+
+# Reuse with per-call overrides
+sky tasks create --from-json task-template.json --title "Ship 1.2.0"
+sky tasks create --from-json task-template.json --title "Ship 1.3.0"
+
+# Or stream from another tool
+sky tasks list --json \
+  | jq '.data[0] | {title: "Clone of \(.title)", spaceId, priority, goalId}' \
+  | sky tasks create --from-json -
+```
+
+When a typed flag AND a JSON field collide, the typed flag wins — so you can
+enforce invariants from the command line while the JSON supplies everything
+else.
+
+## Deletion safety
+
+`spaces delete`, `goals delete`, and `tasks delete` all prompt for
+confirmation by default. The prompt is suppressed by `--yes` (or `-y`). When
+stdin is not a TTY — typical for piped input, CI runners, or `nohup` — the
+delete commands refuse to prompt and exit with code 7 unless `--yes` is
+passed. This prevents the CLI from hanging forever waiting on input that
+will never arrive.
+
+## Config file
+
+Credentials and host state live at `~/.sky/config.json`. The directory is
+created with mode `0700` and the file with mode `0600`, so it's readable only
+by your user account.
+
+| Field          | Description                                                  |
+| -------------- | ------------------------------------------------------------ |
+| `baseURL`      | API host (e.g. `https://oversky.ai`)                         |
+| `token`        | JWT bearer token from `/api/auth/login`                      |
+| `refreshToken` | Refresh token for silent rotation (if the server issued one) |
+| `userId`       | Signed-in user ID                                            |
+| `email`        | Signed-in user email, cached for display                     |
+
+Delete the file to fully reset CLI state:
+
+```bash
+rm ~/.sky/config.json
+```
+
+## Architecture notes
+
+The CLI is a thin oclif shell over `@skrr-ai/data-provider`. The only bridge
+code is a Node-native HttpAdapter that satisfies the `HttpAdapter` interface
+the data-provider exposes for non-browser consumers.
+
+- **`src/base-command.ts`** — every command extends `BaseCommand`, which in
+  `init()` loads `~/.sky/config.json`, calls `setBaseURL()` and
+  `setHttpAdapter()` on the data-provider, and exposes `requireAuth()` and
+  `handleApiError()` for subclasses.
+- **`src/lib/node-adapter.ts`** — implements `HttpAdapter` using Node 20's
+  global `fetch`. Injects the bearer token from disk on every request,
+  transparently handles 401 → refresh → retry (mirroring the browser
+  interceptor minus the `window.location` redirect), and surfaces server
+  errors as `Error` instances with `status` and `body` properties.
+- **`src/lib/config.ts`** — read/write the config file with enforced 0600
+  permissions.
+- **`src/lib/format.ts`** — `pad` / `truncate` / `renderTable` helpers for
+  the human-friendly output mode.
+- **`src/commands/**/\*.ts`** — one class per command, auto-discovered by
+oclif from `dist/commands/`(set via`"oclif.commands"`in`package.json`). The `topicSeparator: " "`option enables space-separated
+subcommands like`sky convos list`instead of`sky convos:list`.
+
+### Why not `axios` or `undici`?
+
+Node 20 ships a spec-compliant global `fetch`, so the adapter has zero runtime
+HTTP dependencies. The data-provider's default axios transport is still
+bundled — we just never reach it, because `setHttpAdapter()` in
+`BaseCommand.init()` replaces it on every command.
+
+### Why oclif instead of Commander?
+
+With ~100+ commands realistic, oclif's class-per-file convention, plugin
+system (useful for splitting admin-only commands into a separate package
+later), auto-generated help, shell completion, and auto-update outweigh its
+heavier footprint. Commander would be the right call for a 10–20 command
+internal tool.
+
+## Adding a new command
+
+1. Pick the data-provider function you want to wrap (see
+   `packages/data-provider/src/data-service.ts`).
+2. Create `src/commands/<topic>/<action>.ts` extending `BaseCommand`.
+3. Add `static override flags = { ... }` using `@oclif/core`'s `Flags`.
+4. In `run()`, call `this.requireAuth()` (for authed commands), call the
+   data-provider function inside a try/catch that delegates to
+   `this.handleApiError()`, and emit output via `this.log()` — or
+   `this.log(JSON.stringify(...))` when `--json` is passed.
+5. Run `npm run build` from `cli/`, then `./bin/run.js <topic> <action>`.
+
+See `src/commands/whoami.ts` for the simplest possible template and
+`src/commands/convos/list.ts` for a paginated table renderer.