@skrr-ai/cli 0.1.94 → 0.1.96

package/README.md

@@ -2,6 +2,105 @@
 
 Command-line interface for OverSky, wrapping the `@skrr-ai/data-provider` client.
 
+
+## Start here
+
+The supported executable is `skrr`. These [versioned developer guides](docs/v1/README.md) are included with the npm package; they do not require access to the private source repository. This guide set was checked against CLI **0.1.95** source on **2026-10-10**. Run `skrr --version` to identify your installed artifact; source availability is not evidence of a published release.
+
+```bash
+npm install -g @skrr-ai/cli
+skrr --version
+skrr login --base-url https://skrr.ai
+skrr whoami
+skrr spaces list --json
+```
+
+The CLI is the user-facing command; `skrr daemon install` downloads and verifies
+the background runtime when needed. Installing `skrrd` alone does not install
+the CLI. For a user-owned installation without administrator access on macOS
+or Linux, use `npm install -g --prefix "$HOME/.local" @skrr-ai/cli` and add
+`$HOME/.local/bin` to your shell PATH. Verify with `command -v skrr` and
+`skrr --version` in a new terminal.
+
+The desktop app includes the CLI and installs its `skrr` wrapper on launch,
+using its bundled interpreter so no separate Node.js installation is needed.
+If your terminal cannot find it, choose **Help > Set Up skrr Command…**.
+This verifies your shell, offers Unix PATH setup, and can copy the full command.
+Existing commands owned by npm or another installer are preserved. Desktop
+updates maintain the bundled wrapper; npm maintains npm installations.
+
+The script installer sets up both `skrr` and the signed `skrrd` runtime by
+default and requires Node.js 20+ with npm. To repair a machine that already has
+the runtime, run `bash scripts/install-daemon.sh --cli-only` from this checkout.
+Use `--daemon-only` for runtime images without npm. On Windows the equivalent
+runtime-only switch is `$env:SKRR_INSTALL_DAEMON_ONLY='1'` before running
+`install-daemon.ps1`. These installers use a user-owned npm prefix and leave
+the system/global npm configuration unchanged.
+
+`login` first tries a signed-in local daemon, then browser PKCE, then a device code when the callback cannot run. With SSH or no local browser, use `skrr login --device-code`; approve it in a browser on another device. Password, MFA, passkey and configured federation challenges remain on the web sign-in page. The CLI has no password flag.
+
+To create your first Task in an existing Space, copy its ID from `spaces list` and run:
+
+```bash
+skrr tasks create --space <space-id> --title "My first CLI task" --execution-mode human --external-key onboarding/first-task --json
+```
+
+This creates a Task; it does not start an agent run. Use a Space whose automation is disabled if you are exploring. See the [quickstart](docs/v1/quickstart.md) for scope selection and safe retries, the [public API guide](docs/v1/api.md) for a read-only first API call, and [operations and recovery](docs/v1/operations.md) for credentials, errors, request IDs, quotas and upgrades. `skrr code` runs a coding agent in the current repository and can incur model/compute usage; run it only after choosing that execution context.
+
+After installing the CLI, run `skrr login`. On an interactive sign-in, skrr can help set up
+removable managed instructions for the coding agents on your computer. You select each
+provider and choose automatic updates or a fixed current version; installing the CLI alone
+does not change agent instruction files.
+
+Run `skrr instructions setup` at any time to revisit provider choices. The setup verifies
+the local daemon's account, server and profile, then previews the real file paths and checks
+whether the agent can read them. Use `--provider codex --review` to inspect the exact content
+without installing. To choose a different machine explicitly, pass `--daemon <id>`.
+
+Automation never prompts. For an explicit installation, use
+`skrr instructions setup --provider codex --update-policy latest --yes --json`.
+Use `--update-policy pinned` to keep the current version, or `--review --json` to get a
+read-only preflight. `skrr instructions status` confirms application by the daemon.
+`skrr instructions guide task-management` loads the detailed workflow on demand.
+It works offline and without sign-in, using a canonical guide generated into the CLI release.
+
+## Local updates
+
+These commands work without a cloud login or connected daemon:
+
+```bash
+skrr update --check                  # CLI, Code and daemon offered versions
+skrr update --status --json          # local versions and recorded results; no network
+skrr update                         # update installed components through their owners
+skrr update --component daemon --restart
+skrr code install                   # install the signed local Code engine
+skrr code update                    # update it; existing sessions keep their release
+skrr code update --check
+skrr code rollback                  # restore the previous verified release
+skrr code update --startup-checks off
+skrr code update --startup-checks on
+```
+
+Interactive `skrr code` sessions offer **Update and start**, **Skip once**,
+**Skip this version** and **Disable startup checks** when a newer signed release is available. ACP, scripts,
+JSON output, help and noninteractive launches do not display that prompt.
+`SKRR_CODE_UPDATE_CHECK=0` disables startup checks; explicit update commands remain
+available. Use `--daemon <id>` with `code install` or `code update` to target a
+remote machine instead; that path uses account authentication.
+
+The CLI automatically queues updates for private, writable, user-owned npm global
+installations and waits for active CLI invocations to finish. Set
+`OVERSKY_CLI_AUTO_UPDATE=0` to keep discovery while disabling automatic application.
+Shared prefixes, Windows npm installations, project dependencies, source checkouts,
+app bundles and runtime images show their owner's update command. Daemon automatic
+updates require an eligible supervised installation with its update monitor enabled;
+the unified status reports the live daemon's recorded posture.
+
+Code and daemon rollback obey retained signed minimum versions. Unsigned or tampered
+rollback artifacts cannot be used as verified releases. See the
+[update lifecycle design](../docs/architecture/component-update-lifecycle-2026-10-10.md)
+and the [release runbook](../docs/runbooks/cli-daemon-release.md) for storage and rollout.
+
 ## Status
 
 **Comprehensive CRUD + workflow surface across the OverSky public API.**
@@ -38,7 +137,7 @@ observability), and shared links.
 | **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` and `workspace` scopes)                                                                                                                                                                                                                                                                                                                                                       |
+| **labels**                            | `list`, `palette`, `create`, `update`, `archive`, `restore`, `delete`, `reorder` (unified labels across `user` 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)                                                                                                                                                                                                                                                                                                                                    |
@@ -53,7 +152,7 @@ observability), and shared links.
 | **tasks result**                      | `submit`, `show` (immutable Result versions and exact Review state)                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | **tasks resource**                    | `add`, `list` (versioned inputs, references, evidence, attachments, and Deliverables)                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | **tasks deliverable**                 | `add`, `list`, `confirm` (the user-facing produced-Resource workflow)                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| **tasks labels**                      | `list`, `create`, `delete`, `attach`, `detach`, `suggest` (label vocabulary + per-task attachment; `suggest` asks the model to pick from the declared vocabulary, advisory only)                                                                                                                                                                                                                                                                                                                         |
+| **tasks labels**                      | `list`, `create`, `delete`, `attach`, `detach`, `suggest` (label vocabulary + per-task attachment; `suggest` asks the model to pick from the declared vocabulary, advisory only)                                                                                                                                                                                                                                                                                                                      |
 | **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`                                                                                                                                                                                                                                                                                                                    |
@@ -66,27 +165,27 @@ observability), and shared links.
 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
+skrr convos list --limit 10                     # id, title, agent, updated
+skrr convos list --agent <agent-id>             # server-side agent scope
+skrr convos list --search "login bug" --json    # Meilisearch-backed
+skrr messages list -c <convo-id> --limit 20     # newest 20 (default: whole transcript)
+skrr 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 result show <task-id>                # current Result + exact Review
-sky tasks transcript <task-id> --assistant-only  # full agent transcript, no prompt
-sky tasks comments list <task-id>              # raw comment thread
+skrr tasks list --assignee-agent <agent-id>     # what this agent is working on
+skrr tasks show <task-id>                       # includes the Convo: pointer
+skrr tasks result show <task-id>                # current Result + exact Review
+skrr tasks transcript <task-id> --assistant-only  # full agent transcript, no prompt
+skrr 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
+skrr agents activity <agent-id> --limit 10      # merged DM + conversations + tasks feed
 ```
 
 `--agent` / `agents activity` need a server that implements `?agentId=` on
@@ -96,7 +195,7 @@ 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
+skrr 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
@@ -107,21 +206,21 @@ preserve these contracts:
   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`.
+- Agent runtime scripts start with `skrr context --json`, then `skrr 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"`
+  the relevant reference next with `skrr usage tasks --json` (or the convenient
+  `skrr tasks usage --json` form), then use `skrr 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`
+  `skrr doctor --json` for auth/build readiness and `skrr 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 "..."`.
+  possible, such as `skrr agent message send --text "..."`.
 
 ### Agent-initiated app voice calls
 
-`sky agent call` is a session-only consent flow, not a phone dialer. It reads
+`skrr 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
@@ -129,14 +228,14 @@ accept it before the normal LiveKit call is created.
 
 ```bash
 # From an autonomous daemon session
-sky agent call request \
+skrr 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
+skrr agent call show <call-id> --json
+skrr agent call cancel <call-id> --json
 ```
 
 The request is idempotent. With no explicit `--idempotency-key`, Sky derives a
@@ -152,12 +251,12 @@ default Sky CLI capability.
 Run the hygiene audit before publishing CLI changes:
 
 ```bash
-sky commands --audit --json
+skrr commands --audit --json
 ```
 
 ### PSTN phone calls (Phase 2)
 
-`sky agent phone-call request --purpose "…"` is an explicit, autonomous-
+`skrr 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.
@@ -179,9 +278,8 @@ or intentionally not exposed as request/response APIs:
   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.
+  `skrr agent message send --text "..." --json` for that agent-facing path.
+- **Authentication**: browser/device-code sign-in delegates configured MFA, passkey and federation to the web sign-in page. There is no CLI password flow. See [authentication and revocation](docs/v1/operations.md#authentication-and-revocation).
 - **Message delete**: `DELETE /api/messages/:convoId/:messageId` — server
   only.
 - **Tests**: the CLI has focused Jest coverage, but broader command/API
@@ -193,13 +291,15 @@ or intentionally not exposed as request/response APIs:
 ## Prerequisites
 
 - Node.js 20+
-- A running OverSky API (default target: `http://localhost:3080`)
+- An account on your deployment (default: `https://skrr.ai`; `--env local` selects the configured local API)
 - `@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):
+For end users: `npm install -g @skrr-ai/cli`. The package vendors its private workspace dependencies.
+
+For contributors with a checkout, build from the repository root:
 
 ```bash
 # 1. Install workspace deps (picks up cli/ because it was added to the root
@@ -228,8 +328,8 @@ From `cli/`:
 Or globally, after `npm link` from `cli/`:
 
 ```bash
-sky login
-sky convos list --json
+skrr login
+skrr convos list --json
 ```
 
 ## GitHub tools from local runtimes
@@ -348,142 +448,48 @@ to `dist/` and the next invocation picks up the change.
 
 ## Commands
 
-### `sky login`
-
-Sign in to an OverSky instance.
+### `skrr login`
 
-**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`).
+Sign in to a deployment and profile. The order is a local daemon broker, browser PKCE with a localhost callback, then device code when the browser callback cannot run. `--device-code` skips both the broker and callback. A declined sign-in is not automatically retried through a different flow.
 
 ```bash
-sky login
-sky login --base-url https://oversky.ai
-sky login --device-code      # skip broker + PKCE; use device-code directly
+skrr login --base-url https://skrr.ai
+skrr login --device-code
+skrr login --profile reviewer --env dev
 ```
 
-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:
+Configuration lives in `~/.skrr/cli-config.json`, or `~/.skrr/profiles/<name>/cli-config.json`. `SKRR_CONFIG_DIR` / `OVERSKY_CONFIG_DIR` can set a different root. Credentials live in the macOS Keychain or `cli-auth.json` (0600), not the legacy `~/.sky/config.json`; that path is read only for migration. Sessions are bound to their issuing server.
 
-- `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
+The web sign-in page handles password, two-factor, passkey and configured federation. The CLI never receives the password. `--recovery-code` redeems a printable recovery code; it can still require a confirmation step and is not an unattended CI credential. For a saved refresh family use `OVERSKY_REFRESH_TOKEN` with its matching `OVERSKY_CLI_ID`; a successful restore rotates the token, so do not reuse a bundle across machines or jobs.
 
-2FA, OAuth, SAML, and LDAP are not yet supported via the interactive
-PKCE / device-code flows. (The recovery-code path is unaffected.)
+`OVERSKY_SKIP_DAEMON_BROKER=1` skips the broker. `SKRR_SKIP_DAEMON_HANDOFF=1` skips the optional post-login daemon setup. They control different steps. Login does not require installing the daemon for workspace/API management.
 
 ### Auto-broker on first use
 
-Every `sky` command (except `login`, `logout`,
-`generate-recovery-code`) runs the daemon-broker handoff transparently
-when no token is in the keychain. So:
+A human command with no stored session may adopt a durable CLI family through a signed-in daemon on the same deployment. It is stored and renews independently, so a daemon restart does not sign out the CLI. Revoking that daemon also revokes the families delegated through it. If durable adoption is unavailable, the command can borrow a short-lived token for that invocation.
 
-```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`, injected `OVERSKY_TOKEN` / `SKRR_TOKEN` / `OVERSKY_REFRESH_TOKEN`, and `OVERSKY_SKIP_DAEMON_BROKER=1` disable automatic brokering. `SKRR_NO_CLI_SESSION_ADOPTION=1` disables durable adoption. Agent/tool children only borrow and never read or persist the person's session. Their login/logout commands are refused.
 
-- `--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`,
-  `generate-recovery-code` — these manage their own auth lifecycle
+After `skrr logout`, durable adoption remains off until explicit login, although the daemon can still lend a short-lived token. On a Dedicated Runtime, the platform-managed hand-off can continue providing access after the person's own local credential is cleared.
 
-**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.
+### `skrr logout`
 
 ```bash
-sky logout
+skrr logout
+skrr logout --all-devices
 ```
 
-The server-side logout call is best-effort — if the network is down, the
-local token is still cleared.
+The first command revokes this CLI refresh family best-effort and clears its local Keychain/file credential. It keeps the server, CLI identity and daemon's separate sign-in. The second also enumerates and revokes registered daemon resources, including their delegated CLI families. Independent CLI families created by browser/device code on other machines, and personal access tokens, require their own session/token revocation controls; this flag does not promise account-wide revocation of every credential type. If remote revocation fails, local cleanup still runs and the CLI reports the incomplete sweep.
+
+For CI, use expiring `osk_pat_*` personal access tokens through `SKRR_TOKEN`. `osk_ci_*` tokens only bootstrap a daemon. Space-scoped `osk_live_*` / `osk_test_*` keys authenticate the public `/v1` API, a different API from the workspace CLI's `/api` routes. See [operations and recovery](docs/v1/operations.md).
 
-### `sky whoami`
+### `skrr whoami`
 
 Show the currently signed-in user.
 
 ```bash
-sky whoami
-sky whoami --json
+skrr whoami
+skrr whoami --json
 ```
 
 ### `sky convos list`
@@ -892,6 +898,17 @@ sky spaces unarchive <space-id>
 sky spaces archive <space-id> --json
 ```
 
+### `sky spaces claim <id>`
+
+An eligible editor can claim an ownerless Space. The longest-standing editor
+can claim immediately; any editor can claim after seven days. The server
+enforces eligibility at claim time.
+
+```bash
+sky spaces claim <space-id>
+sky spaces claim OSK-S-12 --json
+```
+
 ### `sky spaces` — subspaces (parent / child hierarchy)
 
 Spaces form a tree. Each space tracks `parentSpaceId`, the materialized
@@ -1908,25 +1925,20 @@ 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
+## Configuration and credentials
 
-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.
+The active config root is `~/.skrr`, with `cli-config.json` for the default profile and `profiles/<name>/cli-config.json` for a named profile. `SKRR_CONFIG_DIR` (preferred) / `OVERSKY_CONFIG_DIR` can override it. The legacy `~/.sky/config.json` is read only as a migration input.
 
-| 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                     |
+| Field | Description |
+| --- | --- |
+| `baseURL` | Issuing deployment, e.g. `https://skrr.ai` |
+| `cliId` / `profileCliId` | Machine/profile identity used to bind refresh sessions |
+| `credentials.store` | Credential backend posture, such as automatic Keychain/file or env-only |
+| `adoptDaemonSession` | Whether human commands may durably adopt a session through the daemon |
 
-Delete the file to fully reset CLI state:
+Session secrets live in the macOS Keychain or profile-local `cli-auth.json` (0600), not normal config fields. Environment/flag/helper credentials outrank stored sessions and do not refresh. Agent children never read the person's stored session. Use `skrr whoami` to inspect the actual source.
 
-```bash
-rm ~/.sky/config.json
-```
+Use `skrr logout` to revoke and clear the local CLI session, and explicit session/token management for broader revocation. Deleting a legacy config file does not clear Keychain credentials, revoke a remote family, or stop daemon-provided access. See [authentication and revocation](docs/v1/operations.md#authentication-and-revocation).
 
 ## Architecture notes
 
@@ -1935,11 +1947,9 @@ 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.
+  `init()` loads profile configuration, resolves the effective credential, 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,
+  global `fetch`. Injects the resolved credential 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.

package/bin/run.js

@@ -13,6 +13,38 @@ try {
 
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+
+// Enter the installation's session gate before loading any package modules.
+// The copy outside node_modules remains available while npm replaces files.
+// npm still owns the executable itself; its one-time initial migration and
+// clients from older releases cannot participate in this cooperative gate.
+try {
+  const fs = require('node:fs');
+  const os = require('node:os');
+  const crypto = require('node:crypto');
+  const packageRoot = path.resolve(__dirname, '..');
+  const key = crypto.createHash('sha256').update(packageRoot).digest('hex').slice(0, 24);
+  const runtimeDirectory = path.join(os.homedir(), '.skrr', 'cli-update-runtime', key);
+  const bootstrap = path.join(runtimeDirectory, 'bootstrap-v1.cjs');
+  if (!fs.existsSync(bootstrap)) {
+    fs.mkdirSync(runtimeDirectory, { recursive: true, mode: 0o700 });
+    const temporary = `${bootstrap}.${process.pid}.tmp`;
+    fs.copyFileSync(path.join(__dirname, 'update-session.cjs'), temporary);
+    fs.chmodSync(temporary, 0o600);
+    fs.renameSync(temporary, bootstrap);
+  }
+  require(bootstrap).registerSession(packageRoot);
+  process.env.SKRR_CLI_UPDATE_SESSION_REGISTERED = String(process.pid);
+} catch (error) {
+  if (error && error.code === 'CLI_UPDATE_BUSY') {
+    console.error(`[skrr] ${error.message}`);
+    process.exit(75);
+  }
+  // Failure to record a session disables the automatic updater in this
+  // invocation. A read-only home must not break ordinary CLI commands.
+  process.env.SKRR_CLI_UPDATE_SESSION_UNAVAILABLE = '1';
+}
+
 const { findAlternateCli, missingLocalCommandBuild } = require('./dev-fallback');
 
 /**

package/bin/update-npm-runner.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+// Park before npm executes. The parent publishes this process group's durable
+// mutation ownership before authorizing execution, closing its crash window.
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+const requestFile = process.argv[2];
+const request = JSON.parse(fs.readFileSync(requestFile, 'utf8'));
+const deadline = Date.now() + 30000;
+const timer = setInterval(() => {
+  let authorization;
+  try {
+    authorization = JSON.parse(fs.readFileSync(`${requestFile}.go`, 'utf8'));
+  } catch {
+    /* still parked */
+  }
+  if (authorization?.pid === process.pid && authorization?.token === request.token) {
+    clearInterval(timer);
+    const child = spawn(request.npmPath, ['install', '-g', `@skrr-ai/cli@${request.version}`], {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    });
+    child.once('error', () => {
+      process.exitCode = 1;
+    });
+    child.once('exit', (code) => {
+      process.exitCode = code ?? 1;
+    });
+  } else if (Date.now() >= deadline) {
+    clearInterval(timer);
+    process.exitCode = 1;
+  }
+}, 20);