@skrr-ai/cli 0.1.94 → 0.1.96

package/docs/v1/README.md

@@ -0,0 +1,28 @@
+# skrr developer guide — v1
+
+Build a useful first integration, understand its authority and cost, and recover when a request fails.
+
+This edition was reviewed on **2026-10-10** against CLI **0.1.95**, daemon **0.8.116**, and the public `/v1` source contract. These are source versions, not release attestations. Check your installed CLI with `skrr --version` and its schemas with `skrr commands --schema "<command>"`. Install the CLI from the public npm package; this guide and its runnable example are included in that package and require no private repository access.
+
+| Your goal | Start here |
+| --- | --- |
+| Sign in and create your first Task | [Quickstart](quickstart.md) |
+| Make a read-only HTTP request with a scoped key | [Public API](api.md) |
+| Fix sign-in, errors, quotas, permissions, or a failed upgrade | [Operations and recovery](operations.md) |
+| Understand what changed in this guide | [Changelog](changelog.md) |
+
+The workspace CLI uses the account/workspace `/api` surface. The Managed Agents public API uses `/v1` and Space-scoped API keys. A personal access token for CLI automation is a different credential. Choose the surface before issuing a credential.
+
+The `/v1` API is a beta contract; the `v1` path does not promise an indefinite compatibility window. The TypeScript Managed Agents SDK is an unpublished candidate, so these instructions use standard HTTP and Node's built-in `fetch`. Do not install an unpublished SDK or infer support from an internal architecture proposal.
+
+## Find the guide in an installed package
+
+```bash
+npm root -g
+```
+
+Open `<the printed directory>/@skrr-ai/cli/docs/v1/README.md`. The example is `docs/v1/examples/api-readonly.mjs` alongside this guide. The same files can be distributed to a docs host without private-source links; a public website deployment is a separate release step.
+
+## What has been validated
+
+The example's pagination, structured errors and request IDs, bounded retries, cancellation, deadlines, cursor failures, and credential/origin boundaries are checked using a fake HTTP transport. `check-examples.mjs` also checks all relative links in this guide set. These checks do not create accounts, mint keys, spend model credits, or prove an external person's login on a released binary. Human sign-in, public package installation on each supported OS, and docs-host availability remain release acceptance checks.

package/docs/v1/api.md

@@ -0,0 +1,55 @@
+# Your first Managed Agents API request
+
+[Guide index](README.md) · [CLI quickstart](quickstart.md) · [Recovery](operations.md)
+
+Use the public `/v1` API for Managed Agents, environments, sessions, events and streaming. Use the workspace CLI for Spaces, Projects and Tasks. The credentials for these surfaces are different.
+
+## Create a scoped API key
+
+From your own signed-in terminal, choose a Space you administer and grant only the reads needed for this example:
+
+```bash
+skrr api-keys create --space <space-id> --name "first-read" --scope agents:read --scope sessions:read --scope events:read
+```
+
+The `osk_live_*` or `osk_test_*` secret is shown once. Save it in your secret manager. It is bound to one Space; a key cannot grant broader access than its owner. Current agent listing additionally selects the key creator's published Managed Agents, so an empty list is a successful result even when other workspace agents exist. A `test` prefix is not a promise of free compute or a separate isolated backend.
+
+Provide the secret to the example as `SKRR_API_KEY` through your secret manager or a hidden prompt. Do not put it in a command argument, source file or support transcript. The base URL for this deployment is `https://skrr.ai`; self-hosted deployments must use their own issuing origin.
+
+```bash
+node <installed-package>/docs/v1/examples/api-readonly.mjs
+```
+
+The example only sends `GET /v1/agents?limit=100`, follows `next_cursor` with `after`, and prints a count. It creates no session or agent run. A zero count is normal on a new account. It reports stable HTTP error codes and the `X-Request-Id` header without logging the key. Set `SKRR_API_BASE_URL` only to the origin that issued your key. Non-loopback HTTP, URL credentials, redirects and cross-origin paths are refused.
+
+A read response has this shape:
+
+```json
+{"data":[],"has_more":false,"next_cursor":null}
+```
+
+List limits are endpoint-specific. Agent/session list requests accept `limit` up to 100, default 20, and an opaque `after` cursor. Do not derive cursors from the public agent ID. Read the returned `next_cursor`; the example refuses missing or repeating cursors instead of looping forever.
+
+## Read and reconnect a session
+
+For an existing session, events have monotonically increasing sequence numbers. `GET /v1/sessions/<id>/events?from_seq=0&limit=500` is the recovery surface. The response includes `data`, `from_seq`, `max_seq` and `has_more`. Persist the greatest **processed** event `seq`, not `max_seq` (which can describe events beyond this page). The example exports `readEventPage()` and deliberately leaves event processing and durable checkpointing to the application.
+
+`GET /v1/sessions/<id>/stream?from_seq=<processed-seq>` opens SSE. Reconnect from your durable cursor and deduplicate by session/sequence. Treat malformed data, an unexpected content type, premature EOF, a deadline or cancellation as explicit outcomes. A stopped HTTP stream alone does not prove the agent finished; inspect the session and durable events. Current replay/stream convergence and fleet-wide connection limits are being hardened; do not assume unlimited history in a single connection or an unconditional delivery guarantee.
+
+This guide does not claim a TypeScript SDK candidate has already been published or qualified for your environment. Use your tested SSE parser or a verified SDK release when one is available; do not parse arbitrary transport chunks with `split('\n\n')` alone.
+
+## Writes, quotas and billing
+
+Create agents and environments, then sessions, only after choosing model, tools, runtime continuity and budget. Grant the corresponding write scopes separately. Event POSTs accept an `Idempotency-Key`; retain the same key and body when retrying the same user turn, and choose a new key for a new turn. A request ID is diagnostic correlation, not an idempotency key.
+
+Session creation and run admission can fail for plan, capacity, running-session or session-hours limits before work starts. Authenticated responses can include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `Retry-After`. Respect returned limits instead of hardcoding a plan allowance. The example retries only reads and only up to its configured budget. See [quota and cost](operations.md#quota-and-cost).
+
+## Rotate and revoke
+
+```bash
+skrr api-keys list --space <space-id> --json
+skrr api-keys rotate <key-id> --space <space-id>
+skrr api-keys revoke <key-id> --space <space-id>
+```
+
+Rotation immediately invalidates the previous secret; coordinate client configuration changes. Revocation cannot reveal the secret again. Workspace CLI PATs are managed by `skrr tokens`, independent CLI refresh families by `skrr token`; neither is a substitute for `api-keys`.

package/docs/v1/changelog.md

@@ -0,0 +1,16 @@
+# Developer guide changelog
+
+[Guide index](README.md)
+
+## 2026-10-10 — first versioned guide edition
+
+Source baseline: CLI 0.1.95, daemon 0.8.116. This entry records documentation changes, not an npm or native release.
+
+- Added a first-Task CLI journey and a read-only Managed Agents API journey.
+- Distinguished CLI sessions, PATs, daemon bootstrap credentials and Space-scoped API keys.
+- Corrected legacy password-login, `~/.sky` storage and blanket MFA/federation restrictions.
+- Explained the difference between a CLI per-daemon logout sweep and account-wide session/PAT revocation.
+- Added examples for request IDs, pagination, bounded read retries, cancellation, CLI JSONL semantics and stable-key `create-tree --resume` recovery.
+- Preserved historical architecture reviews with dated current-source pointers.
+
+Before describing this edition as publicly shipped, verify the npm tarball contains these files, install it without private-source access on each supported platform, exercise a real account's login/logout/recovery, and verify the selected docs host serves the same edition. A local mocked example pass is not those acceptance results.

package/docs/v1/check-examples.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/** Offline validation: real example + fake transport, relative-link and documented CLI contracts. */
+import assert from 'node:assert/strict';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createReadClient, PublicApiError } from './examples/api-readonly.mjs';
+
+const root = dirname(fileURLToPath(import.meta.url));
+let checks = 0;
+async function check(name, action) {
+  await action();
+  console.log(`PASS ${name}`);
+  checks++;
+}
+const key = 'osk_test_example_fixture_not_a_secret';
+const json = (body, status = 200, headers = {}) => new Response(JSON.stringify(body), {
+  status, headers: { 'content-type': 'application/json', ...headers },
+});
+
+await check('read-only first success and opaque cursor pagination', async () => {
+  const calls = [];
+  const client = createReadClient({ apiKey: key, fetchImpl: async (url, opts) => {
+    calls.push({ url: String(url), opts });
+    return calls.length === 1
+      ? json({ data: [{ id: 'ag_one' }], has_more: true, next_cursor: 'opaque-cursor' })
+      : json({ data: [{ id: 'ag_two' }], has_more: false, next_cursor: null });
+  } });
+  assert.deepEqual((await client.listAgents()).map(a => a.id), ['ag_one', 'ag_two']);
+  assert.equal(new URL(calls[1].url).searchParams.get('after'), 'opaque-cursor');
+  for (const { opts } of calls) {
+    assert.equal(opts.method, 'GET');
+    assert.equal(opts.redirect, 'error');
+    assert.equal(opts.headers.Authorization, `Bearer ${key}`);
+    assert(opts.signal instanceof AbortSignal);
+  }
+});
+await check('empty account is a successful response', async () => {
+  const client = createReadClient({ apiKey: key, fetchImpl: async () => json({ data: [], has_more: false }) });
+  assert.deepEqual(await client.listAgents(), []);
+});
+await check('structured HTTP error and request ID without raw message', async () => {
+  const client = createReadClient({ apiKey: key, fetchImpl: async () => json(
+    { error: { code: 'key_expired', message: key } }, 401, { 'x-request-id': 'test-request-1' }),
+  });
+  await assert.rejects(client.listAgents(), error => error instanceof PublicApiError &&
+    error.code === 'key_expired' && error.requestId === 'test-request-1' && !error.message.includes(key));
+});
+await check('server-echoed secrets never become diagnostic codes or request IDs', async () => {
+  const client = createReadClient({ apiKey: key, fetchImpl: async () => json(
+    { error: { code: key, message: key } }, 401, { 'x-request-id': key }),
+  });
+  await assert.rejects(client.listAgents(), error => error instanceof PublicApiError &&
+    error.code === 'unexpected_response' && error.requestId === null && !error.message.includes(key));
+});
+await check('429 retry-after honored inside deadline', async () => {
+  let calls = 0;
+  let clock = 0;
+  const waits = [];
+  const client = createReadClient({ apiKey: key, now: () => clock, sleep: async ms => { waits.push(ms); clock += ms; },
+    fetchImpl: async () => ++calls === 1
+      ? json({ error: { code: 'rate_limited' } }, 429, { 'retry-after': '1' })
+      : json({ data: [], has_more: false }),
+  });
+  await client.listAgents();
+  assert.deepEqual(waits, [1000]);
+  assert.equal(calls, 2);
+});
+await check('429 exceeding deadline is surfaced, not retried early', async () => {
+  let calls = 0;
+  const client = createReadClient({ apiKey: key, timeoutMs: 1000,
+    fetchImpl: async () => { calls++; return json({ error: { code: 'rate_limited' } }, 429, { 'retry-after': '60' }); },
+    sleep: async () => assert.fail('must not sleep past deadline'),
+  });
+  await assert.rejects(client.listAgents(), error => error.status === 429);
+  assert.equal(calls, 1);
+});
+await check('transient network retry is bounded', async () => {
+  let calls = 0;
+  const client = createReadClient({ apiKey: key, fetchImpl: async () => { calls++; throw new TypeError('network'); }, sleep: async () => {} });
+  await assert.rejects(client.listAgents(), TypeError);
+  assert.equal(calls, 3);
+});
+await check('cancellation prevents retry', async () => {
+  const controller = new AbortController();
+  let calls = 0;
+  const client = createReadClient({ apiKey: key, fetchImpl: async () => { calls++; controller.abort(); throw controller.signal.reason; } });
+  await assert.rejects(client.listAgents({ signal: controller.signal }), error => error.name === 'AbortError');
+  assert.equal(calls, 1);
+});
+await check('per-request deadline aborts the transport', async () => {
+  const client = createReadClient({ apiKey: key, timeoutMs: 10, fetchImpl: async (_url, { signal }) =>
+    new Promise((_, reject) => {
+      const timer = setTimeout(() => reject(new Error('fixture failed to observe deadline')), 200);
+      signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }, { once: true });
+    }),
+  });
+  await assert.rejects(client.listAgents(), error => error.name === 'TimeoutError');
+});
+await check('repeated/missing cursors and page budget fail explicitly', async () => {
+  for (const cursor of [null, 'same']) {
+    const client = createReadClient({ apiKey: key, fetchImpl: async () => json({ data: [], has_more: true, next_cursor: cursor }) });
+    await assert.rejects(client.listAgents(), /cursor/);
+  }
+  const client = createReadClient({ apiKey: key, fetchImpl: async () => json({ data: [], has_more: true, next_cursor: 'next' }) });
+  await assert.rejects(client.listAgents({ maxPages: 1 }), /budget/);
+});
+await check('incorrect content type fails explicitly', async () => {
+  const client = createReadClient({ apiKey: key, fetchImpl: async () => new Response('<html>login</html>', { headers: { 'content-type': 'text/html' } }) });
+  await assert.rejects(client.listAgents(), /JSON/);
+});
+await check('credential type, issuing origin and redirects stay separate', async () => {
+  assert.throws(() => createReadClient({ apiKey: 'osk_pat_wrong_surface' }), /Space-scoped/);
+  assert.throws(() => createReadClient({ apiKey: key, baseURL: 'http://skrr.ai' }), /HTTPS/);
+  assert.throws(() => createReadClient({ apiKey: key, baseURL: 'https://user:pass@skrr.ai' }), /origin/);
+  assert.throws(() => createReadClient({ apiKey: key, baseURL: 'https://skrr.ai/v1' }), /origin/);
+  const client = createReadClient({ apiKey: key, fetchImpl: async () => assert.fail('no HTTP call expected') });
+  await assert.rejects(client.get('https://other.invalid/v1/agents'), /same-origin/);
+  await assert.rejects(client.get('/v1/../api/user'), /same-origin/);
+});
+await check('event recovery uses processed sequence and encoded session ID', async () => {
+  const client = createReadClient({ apiKey: key, fetchImpl: async url => {
+    assert.equal(url.pathname, '/v1/sessions/session%2Fid/events');
+    assert.equal(url.searchParams.get('from_seq'), '17');
+    return json({ data: [{ seq: 18 }], max_seq: 999, has_more: false });
+  } });
+  const page = await client.readEventPage('session/id', 17);
+  assert.equal(page.data[0].seq, 18);
+  // The guide leaves max_seq unacknowledged: only processed data may be checkpointed.
+  await assert.rejects(client.readEventPage('session', -1), /nonnegative/);
+});
+await check('all packaged guide links resolve', async () => {
+  for (const file of (await readdir(root)).filter(f => f.endsWith('.md'))) {
+    const content = await readFile(resolve(root, file), 'utf8');
+    for (const match of content.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+      const target = match[1];
+      if (/^(https?:|mailto:|#)/.test(target)) continue;
+      const [filePath, anchor] = target.split('#');
+      const resolvedPath = resolve(root, decodeURIComponent(filePath));
+      assert((await stat(resolvedPath)).isFile(), `${file}: ${target}`);
+      if (anchor) {
+        const targetContent = await readFile(resolvedPath, 'utf8');
+        const anchors = [...targetContent.matchAll(/^#{1,6}\s+(.+)$/gm)].map(m => m[1].toLowerCase().replace(/[`*]/g, '').replace(/[^a-z0-9 _-]/g, '').replace(/ /g, '-'));
+        assert(anchors.includes(anchor), `${file}: missing anchor ${target}`);
+      }
+    }
+    assert(!content.includes('oversky.com'), `${file}: stale production domain`);
+    assert(!/skrr login[^\n]*(--password|--email)/.test(content), `${file}: unsupported password login`);
+  }
+});
+await check('documented command names and flags match the installed manifest', async () => {
+  const manifest = JSON.parse(await readFile(resolve(root, '../../oclif.manifest.json'), 'utf8'));
+  let commands = 0;
+  for (const file of (await readdir(root)).filter(f => f.endsWith('.md'))) {
+    const content = await readFile(resolve(root, file), 'utf8');
+    for (const fence of content.matchAll(/```bash\n([\s\S]*?)```/g)) {
+      for (const line of fence[1].split('\n')) {
+        if (!line.startsWith('skrr ')) continue;
+        const words = line.slice(5).match(/"[^"]*"|'[^']*'|[^\s]+/g) ?? [];
+        if (words[0] === '--version') continue;
+        let entry;
+        for (let count = Math.min(words.length, 5); count > 0; count--) {
+          const id = words.slice(0, count).join(':');
+          if (manifest.commands[id]) { entry = manifest.commands[id]; break; }
+        }
+        assert(entry, `${file}: command not in manifest: ${line}`);
+        for (const flag of line.matchAll(/(?:^|\s)--([a-z][a-z0-9-]*)/g)) {
+          if (flag[1] === 'help') continue;
+          assert(Object.hasOwn(entry.flags, flag[1]), `${file}: ${entry.id} has no --${flag[1]}`);
+        }
+        commands++;
+      }
+    }
+  }
+  assert(commands > 0, 'No documented CLI examples were checked.');
+  console.log(`Checked ${commands} command examples against manifest ${manifest.version}.`);
+});
+console.log(`Validated ${checks} offline example and guide contracts; no live acceptance claimed.`);

package/docs/v1/examples/api-readonly.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/** Read-only /v1 example. No dependencies, writes, session creation, or secret logging. */
+import { setTimeout as delay } from 'node:timers/promises';
+import { pathToFileURL } from 'node:url';
+
+export class PublicApiError extends Error {
+  constructor(status, code, requestId) {
+    super(`HTTP ${status}: ${code}`);
+    this.name = 'PublicApiError';
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+  }
+}
+
+export function createReadClient({
+  apiKey,
+  baseURL = 'https://skrr.ai',
+  fetchImpl = fetch,
+  timeoutMs = 20_000,
+  maxRetries = 2,
+  sleep = (ms, signal) => delay(ms, undefined, { signal }),
+  now = Date.now,
+} = {}) {
+  if (typeof apiKey !== 'string' || !/^osk_(live|test)_[A-Za-z0-9_-]+$/.test(apiKey)) {
+    throw new Error('SKRR_API_KEY must be a Space-scoped osk_live_* or osk_test_* key.');
+  }
+  const origin = new URL(baseURL);
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname);
+  if (origin.username || origin.password || origin.search || origin.hash || origin.pathname !== '/') {
+    throw new Error('Use the issuing origin only, without credentials, a path, query or fragment.');
+  }
+  if (origin.protocol !== 'https:' && !(origin.protocol === 'http:' && loopback)) {
+    throw new Error('Use HTTPS; HTTP is permitted only on loopback for local development.');
+  }
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000 ||
+      !Number.isSafeInteger(maxRetries) || maxRetries < 0 || maxRetries > 5) {
+    throw new Error('timeoutMs must be 1–120000; maxRetries must be 0–5.');
+  }
+
+  async function get(path, { signal } = {}) {
+    const url = new URL(path, origin);
+    if (url.origin !== origin.origin || !url.pathname.startsWith('/v1/')) {
+      throw new Error('Only same-origin /v1 read paths are allowed.');
+    }
+    const deadline = now() + timeoutMs;
+    const boundedSignal = signal
+      ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
+      : AbortSignal.timeout(timeoutMs);
+    for (let attempt = 0; ; attempt++) {
+      boundedSignal.throwIfAborted();
+      if (now() >= deadline) throw new Error('Read deadline exceeded.');
+      let response;
+      try {
+        response = await fetchImpl(url, {
+          method: 'GET', redirect: 'error',
+          headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json' },
+          signal: boundedSignal,
+        });
+      } catch (error) {
+        // The example retries only network failures on GET, never writes or canceled reads.
+        if (boundedSignal.aborted || !(error instanceof TypeError) || attempt >= maxRetries) throw error;
+        const wait = 250 * 2 ** attempt;
+        if (now() + wait >= deadline) throw new Error('Read retry would exceed the deadline.');
+        await sleep(wait, boundedSignal);
+        continue;
+      }
+      const contentType = response.headers.get('content-type') ?? '';
+      const body = /\bapplication\/json\b/i.test(contentType) ? await response.json() : null;
+      if (response.ok) {
+        if (!body || typeof body !== 'object') throw new Error('Expected a JSON object response.');
+        return body;
+      }
+      const rawCode = body?.error?.code;
+      const code = typeof rawCode === 'string' && /^[A-Za-z0-9_-]{1,100}$/.test(rawCode) && !rawCode.includes(apiKey)
+        ? rawCode : 'unexpected_response';
+      const rawRequestId = response.headers.get('x-request-id');
+      const requestId = rawRequestId && /^[A-Za-z0-9._:-]{1,200}$/.test(rawRequestId) && !rawRequestId.includes(apiKey) ? rawRequestId : null;
+      const failure = new PublicApiError(response.status, code, requestId);
+      if (![429, 500, 502, 503, 504].includes(response.status) || attempt >= maxRetries) throw failure;
+      const retryAfter = response.headers.get('retry-after');
+      const seconds = retryAfter && /^\d+(\.\d+)?$/.test(retryAfter) ? Number(retryAfter) : null;
+      const date = retryAfter && seconds === null ? Date.parse(retryAfter) : NaN;
+      const wait = seconds !== null ? seconds * 1000
+        : Number.isFinite(date) ? Math.max(0, date - now()) : 250 * 2 ** attempt;
+      if (!Number.isFinite(wait) || now() + wait >= deadline) throw failure;
+      await sleep(wait, boundedSignal);
+    }
+  }
+
+  async function listAgents({ signal, maxPages = 100 } = {}) {
+    if (!Number.isSafeInteger(maxPages) || maxPages < 1) throw new Error('maxPages must be positive.');
+    const agents = [];
+    const cursors = new Set();
+    let after;
+    for (let pageNumber = 0; pageNumber < maxPages; pageNumber++) {
+      const query = new URLSearchParams({ limit: '100' });
+      if (after) query.set('after', after);
+      const page = await get(`/v1/agents?${query}`, { signal });
+      if (!Array.isArray(page.data) || typeof page.has_more !== 'boolean') {
+        throw new Error('Invalid agent page contract.');
+      }
+      agents.push(...page.data);
+      if (!page.has_more) return agents;
+      if (typeof page.next_cursor !== 'string' || !page.next_cursor || cursors.has(page.next_cursor)) {
+        throw new Error('Missing or repeated pagination cursor; refusing an infinite loop.');
+      }
+      cursors.add(page.next_cursor);
+      after = page.next_cursor;
+    }
+    throw new Error('Page budget exhausted; resume with an explicit application checkpoint.');
+  }
+
+  async function readEventPage(sessionId, fromSeq = 0, { signal } = {}) {
+    if (typeof sessionId !== 'string' || !sessionId || !Number.isSafeInteger(fromSeq) || fromSeq < 0) {
+      throw new Error('A session ID and nonnegative safe-integer fromSeq are required.');
+    }
+    return get(`/v1/sessions/${encodeURIComponent(sessionId)}/events?from_seq=${fromSeq}&limit=500`, { signal });
+  }
+
+  return { get, listAgents, readEventPage };
+}
+
+async function main() {
+  const controller = new AbortController();
+  const cancel = () => controller.abort(new Error('Canceled by the caller.'));
+  process.once('SIGINT', cancel);
+  try {
+    const client = createReadClient({ apiKey: process.env.SKRR_API_KEY, baseURL: process.env.SKRR_API_BASE_URL });
+    const agents = await client.listAgents({ signal: controller.signal });
+    console.log(JSON.stringify({ ok: true, agentCount: agents.length }));
+  } catch (error) {
+    // Never log a raw HTTP/network message: it can contain private URLs or payloads.
+    console.error(JSON.stringify({ ok: false, error: {
+      code: error instanceof PublicApiError ? error.code : controller.signal.aborted ? 'canceled' : 'read_failed',
+      ...(error instanceof PublicApiError ? { status: error.status, requestId: error.requestId } : {}),
+    } }));
+    process.exitCode = controller.signal.aborted ? 130 : 1;
+  } finally {
+    process.removeListener('SIGINT', cancel);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();

package/docs/v1/operations.md

@@ -0,0 +1,87 @@
+# Operate and recover an integration
+
+[Guide index](README.md) · [Quickstart](quickstart.md) · [Public API](api.md)
+
+## Authentication and revocation
+
+Configuration defaults to `~/.skrr/cli-config.json`; named profiles use `~/.skrr/profiles/<name>/cli-config.json`. `SKRR_CONFIG_DIR` (preferred) and `OVERSKY_CONFIG_DIR` can set another root. macOS stores CLI sessions in the Keychain under `ai.skrr.cli.<profile>` with a config-root suffix where needed. File storage uses `cli-auth.json` (0600) in that profile's directory. The old `~/.sky/config.json` is a migration input, not the current store.
+
+The session is bound to its issuing server. Use `skrr whoami` to inspect the account, server, profile and token source. Use named profiles for independent deployments; a failed login to a different deployment restores the old URL rather than reusing its credential on the new origin.
+
+| Credential | Purpose | Remove it |
+| --- | --- | --- |
+| CLI refresh family | Human terminal; renews on use | `skrr logout` locally; `skrr token list` / `skrr token revoke <id>` for other CLI families |
+| Daemon credential | Tools on a machine | `skrr revoke-daemon <id>`; revoke associated delegated CLI families too |
+| `osk_pat_*` | CI/automation as the account | `skrr tokens list` / `skrr tokens revoke <id>` |
+| Space `osk_live_*` / `osk_test_*` | Managed Agents `/v1` | `skrr api-keys revoke <id> --space <space-id>` |
+| `osk_ci_*` | Bootstrap a daemon | `skrr revoke-token <id>`; ordinary CLI commands reject it |
+
+`skrr logout` clears its stored CLI session and disables automatic durable adoption until the next login. A separately signed-in daemon may still lend the CLI a short-lived token. `skrr logout --all-devices` additionally sweeps registered daemon resources, not independent browser/device-code CLI families or PATs. Inspect partial-revocation warnings. Account Active Sessions **sign out everywhere** uses a broader server revoke-all operation for refresh families and PATs. `skrrd logout --all-devices` attempts that endpoint too, but it requires an authorized human-scope credential; inspect its response and do not mistake local cleanup after an authorization/network failure for completed remote revocation. Space API keys still have their own management surface.
+
+For CI, create an expiring PAT from a human sign-in and inject it through `SKRR_TOKEN`. Read scope is the default; write scope permits account-authorized workspace changes but not sensitive human-only routes such as creating credentials, payments or account recovery. Accounts with two-factor authentication need fresh verification when creating a PAT. `OVERSKY_TOKEN` wins over `SKRR_TOKEN` if both are set; injected credentials never refresh. Do not share a rotating refresh bundle across jobs.
+
+## Classify the error
+
+Workspace CLI JSON failures expose `ok: false` and `error` with a stable code, message and available details/retryability. Public `/v1` failures expose `{ "error": { "code": "...", "message": "..." } }`. They are different envelopes. Always record the process exit status or HTTP status as well.
+
+| Outcome | Action |
+| --- | --- |
+| `NOT_SIGNED_IN`, `SESSION_REVOKED`, `REFRESH_REUSED` | Verify profile/server, then explicitly sign in; never silently replace a deliberately revoked family |
+| `/v1` `missing_auth`, `invalid_key`, `key_revoked`, `key_expired` | Check the issuing origin and correct credential type; rotate/revoke through the owner account |
+| `insufficient_scope`, `PAT_SCOPE_INSUFFICIENT`, `PAT_HUMAN_ONLY_ROUTE` | Choose the intended surface and authority; do not automatically widen scopes |
+| `STEP_UP_REQUIRED` | Use `skrr step-up` from a human session; a PAT cannot pass a human step-up |
+| HTTP 429 | Respect `Retry-After`, cap retries and inspect quota type |
+| HTTP 503 `not_configured` | Deployment operator action; repeated credential creation cannot configure the service |
+| Network error / 504 on a write | Outcome unknown until readback; reconcile before retrying |
+
+Capture `X-Request-Id` from response headers. Include timestamp with timezone, origin, CLI version, command/endpoint, HTTP/exit status and stable code when reporting an issue. Exclude Authorization, tokens, recovery codes, private prompts and full sensitive payloads. A single timeout does not demonstrate that every service is unavailable.
+
+## Recover an uncertain write
+
+For Tasks, use stable `external-key` values and read the target Space after a failure. Match intended key, scope and payload before considering an item created. Bulk operations can commit some items before a lost response; retain the full input file and reconcile created/existing/failed/unknown per item. Retry only missing items with their original keys. The current candidate CLI adds `--resume` for this recovery:
+
+```bash
+skrr tasks create-tree --from-json tree.json --space <space-id> --external-key-prefix integration/initial-import --resume --json
+```
+
+Use the **unchanged original input**, the same Space/workspace and the same external-key prefix. Do not use `--fresh`, change temp IDs, or alter content-derived keys after an uncertain result. Resume confirms the IDs of existing nodes without patching them and creates only missing nodes; intentionally editing existing Tasks is a separate operation. This flag must exist in your installed artifact (`skrr commands --schema "tasks create-tree"`), not merely in source. If a server supplies a durable operation receipt, retain and query that ID; client reconciliation is not a substitute for a durable server receipt.
+
+For public event writes, preserve `Idempotency-Key` and the same body for the same turn. Do not automatically retry arbitrary POSTs merely because they failed with 5xx. For reads, bounded retry with cancellation and a request deadline is appropriate; the bundled example demonstrates it.
+
+For stream recovery, checkpoint only processed event sequences, reopen from that cursor, deduplicate, and inspect durable state on EOF. A connected socket is not a completion receipt. Persist application state before acknowledging work to your user.
+
+The workspace CLI also has a separate agent-turn stream (this starts work and can consume quota):
+
+```bash
+skrr agents chat <agent-id> --prompt "Summarize the chosen repository" --jsonl
+```
+
+Each stdout line is one JSON event. `text.delta.text` is the cumulative answer despite the event name: take the latest value rather than appending it repeatedly. A `run.result` is a terminal result; `stream.gap` describes missing envelopes, and a lost view is not proof the run failed. Preserve the process exit status: 0 for completed, 1 for a failed terminal result, 75 for lost streaming access, and 130 for actual Ctrl-C detach. Cancellation is requested but must be verified against durable work state. CLI JSONL is a different transport contract from public SSE; this guide's offline checks validate the command/flags, while real reconnect/lifetime qualification belongs to the installed CLI's release checks.
+
+## Quota and cost
+
+Authentication, account authorization, API RPM, model quota, balance, hosted capacity and session-hours admission are different limits. A live/test API-key prefix does not make execution free. Starting an agent, invoking inference or allocating hosted compute can consume quota or credits. Use the account's Balance/usage surface and applicable plan controls before running work; the CLI command named `usage` is command-discovery guidance, not a billing statement. Prices and entitlements are deployment-specific and can change; this guide does not freeze a price list.
+
+Canceling your HTTP request stops the caller waiting; it does not necessarily cancel a durable remote Run. Use the relevant session/task lifecycle command to cancel the work, then verify its terminal state and any runtime lease. Runtime continuity distinguishes one-shot, host-owned, true-resume and restart-with-disk products; a preserved disk alone does not prove a running process survived.
+
+## Permissions and local machine access
+
+Review machine consent, repository scope, harness mode and connector permissions separately. A workspace role does not replace local machine consent. Plan/read-only modes must not mutate; broader modes allow tools to edit or run commands within their effective sandbox. On a personal machine, same-user processes are not separate OS security identities. Do not interpret a policy label or Git worktree as a credential boundary.
+
+Inspect `skrr code --help` and your machine/agent configuration before starting work. An unattended permission request may be denied instead of accepted. A network-enabled sandbox and a write boundary are separate properties. Keep credentials out of agent child processes; delegated agent sessions use session credentials and cannot run human login/logout.
+
+## Upgrade and support
+
+```bash
+skrr --version
+skrr doctor --json
+npm install -g @skrr-ai/cli@latest
+skrr --version
+skrr daemon status
+```
+
+The npm CLI and signed native daemon are separately promoted artifacts. Updating the CLI does not prove a daemon or hosted guest image updated. Let the managed daemon installer/updater verify the pinned signed feed; do not work around verification failures by downloading unsigned binaries. Record the before/after versions and retry a read-only command after upgrading.
+
+For a failed CLI install, inspect Node version, npm prefix/PATH and package/plugin completeness before changing credentials. A missing `dist` in a source checkout requires a build; an architecture-specific dependency copied from another OS is not proof that the public tarball is broken. Keep the failing output and environment so support can distinguish those cases.
+
+Use the product's available support entry point or your deployment administrator and include the redacted evidence above. Do not assume a private GitHub issue link is accessible to an external user. See the [changelog](changelog.md) for this guide's scope and release gates.

package/docs/v1/quickstart.md

@@ -0,0 +1,71 @@
+# First success with skrr
+
+[Guide index](README.md) · [Public API](api.md) · [Recovery](operations.md)
+
+You need Node.js 20+ and an account on [skrr](https://skrr.ai) or your own deployment. The CLI can manage workspaces without installing a local daemon. A daemon is needed when agents execute tools on your own machine.
+
+## Install and choose your account
+
+```bash
+npm install -g @skrr-ai/cli
+skrr --version
+skrr login --base-url https://skrr.ai
+skrr whoami
+```
+
+Sign-in first tries a local daemon already signed in to the same deployment, then browser PKCE, then device code when the callback cannot run. Your web account handles password, MFA, passkey and configured federation. For SSH or a machine without a browser:
+
+```bash
+skrr login --device-code
+```
+
+Approve the displayed URL and code from another device. Ctrl-C cancels. You do not need password flags, and the CLI does not receive your password. If you need an independent browser/device-code family instead of a daemon-brokered one, this flag skips the broker too.
+
+CLI login can offer to install and sign in the local background service. Declining that offer still leaves the CLI signed in. `SKRR_SKIP_DAEMON_HANDOFF=1` skips the optional setup. [Credential storage and revocation](operations.md#authentication-and-revocation) explains what each sign-out actually removes.
+
+Before changing anything, confirm the account, profile, deployment and workspace:
+
+```bash
+skrr context --json
+skrr spaces list --json
+```
+
+Choose an existing Space where you have edit access. For a team workspace, select it explicitly with `--workspace <workspace-id>` on the commands below. Do not rely on an old terminal's default scope.
+
+## Create one Task
+
+Run a dry run first; substitute the chosen Space ID:
+
+```bash
+skrr tasks create --space <space-id> --title "My first CLI task" --execution-mode human --external-key onboarding/first-task --dry-run --json
+```
+
+Then create the Task:
+
+```bash
+skrr tasks create --space <space-id> --title "My first CLI task" --execution-mode human --external-key onboarding/first-task --json
+skrr tasks show <task-id-from-create> --json
+```
+
+`human` avoids assigning a default execution agent. Creation itself does not start an agent Run; a Space's configured automation can react to new tasks, so choose a Space with automation disabled when learning. Reusing a stable `external-key` lets you find the same task after an uncertain response. Use a different key when you intend to create a different Task.
+
+If a write times out, first list/read by that key and inspect the existing Task. A timeout means the response is unknown; it does not prove the write failed. Never retry a large create-tree by assuming that none of its items committed. See [write recovery](operations.md#recover-an-uncertain-write).
+
+## Decide where an agent should run
+
+```bash
+skrr code --help
+skrr daemon status
+```
+
+`skrr code` in a repository starts interactive coding work and can edit files and consume model/compute quota. Choose the agent, machine, repository and permissions before starting it. A personal machine must remain available for its tools; cloud execution requires the appropriate hosted product and plan. A Task, a CLI session, and a machine's daemon session have separate lifecycles.
+
+## Use command discovery
+
+```bash
+skrr commands --json --brief
+skrr commands --schema "tasks create"
+skrr doctor --json
+```
+
+Prefer a schema for your installed version over copied flags from an old review. Machine callers consume JSON stdout and the process exit status; guidance and warnings may still be on stderr. [Operations](operations.md) covers script failures and support evidence.