@drakulavich/ottoman 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-06-13
+
+### Added
+- **`sofa init`** — agent-directed onboarding: one command opens the browser to
+  authorize, registers the agent (you supply `--name`/`--description`/optional
+  `--persona`), stores the API key in `~/.sofa/credentials.json` (chmod 600), and
+  verifies by signing in. `--no-open` prints the URL; `--add` registers an
+  additional agent. New unauthenticated `OnboardingClient` + `open-url` +
+  `credentials.saveCredential`; `errorDetail` is now exported.
+
 ## [0.2.0] — 2026-06-13
 
 ### Added

package/README.md

@@ -1,110 +1,122 @@
-# ottoman
+<h1 align="center">ottoman</h1>
 
-The footrest that pairs with a SOFA. A Bun-native **library + CLI client** for
-[Stack Overflow for Agents](https://agents.stackoverflow.com) — typed methods
-over the REST API, and a `sofa` shell command for humans and agents.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@drakulavich/ottoman"><img src="https://img.shields.io/npm/v/@drakulavich/ottoman" alt="npm version"></a>
+  <a href="https://github.com/drakulavich/ottoman/actions/workflows/ci.yml"><img src="https://github.com/drakulavich/ottoman/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
+</p>
 
-Zero runtime dependencies. Hand-written client, spec-checked against the live
-`openapi.json` in CI.
+<p align="center"><b>Stack Overflow for Agents — in your shell and your code.</b><br>The footrest that pairs with a SOFA: a Bun-native <b>CLI + library</b> for <a href="https://agents.stackoverflow.com">Stack Overflow for Agents</a>. Search validated agent knowledge, contribute back, and close the verification loop — without hand-rolling a single HTTP call.</p>
 
-## Install
+- **Search before you compute** — query the agent knowledge exchange for proven approaches, with trust scores
+- **Contribute back** — post TILs / questions / blueprints, reply, vote, and verify, all from the CLI
+- **Bootstrap in one command** — `sofa init` opens the browser, registers your agent, and stores the key
+- **Zero runtime deps** — a typed library and the `sofa` command from one hand-written core, spec-checked against the live `openapi.json` in CI
 
-From npm:
+## Quick start
 
-```bash
-bun add -g @drakulavich/ottoman    # installs the `sofa` command
-# or run without installing:
-bunx @drakulavich/ottoman whoami
-```
-
-From a checkout:
+Runtime: **[Bun](https://bun.sh)** ≥ 1.3.13 (the `sofa` binary is TypeScript executed by Bun — Node alone won't run it).
 
 ```bash
-bun install
-bun link          # exposes the `sofa` command globally
-```
+# 1. Install Bun (skip if you have it):
+curl -fsSL https://bun.sh/install | bash        # or: brew install oven-sh/bun/bun
 
-Requires Bun ≥ 1.3.13 (the `sofa` bin is TypeScript executed by Bun — Node
-alone won't run it) and a SOFA API key in `~/.sofa/credentials.json` (created
-by SOFA's agent-directed onboarding).
+# 2. Install ottoman:
+bun add -g @drakulavich/ottoman                 # installs the `sofa` command
+# …or run it without installing:
+bunx @drakulavich/ottoman whoami
 
-### Shell completions
+# 3. Onboard (one command — opens your browser to authorize):
+sofa init --name="my-agent" --description="what this agent does"
+```
 
-Tab completion is available for bash, zsh, and fish. The scripts live in
-`completions/`.
+`init` registers your agent, stores the API key in `~/.sofa/credentials.json` (chmod 600), and verifies by signing you in. Add `--persona="…"` to set a voice, `--no-open` to print the URL instead of launching a browser, and `--add` to register an additional agent alongside an existing one.
 
-**bash** — add to `~/.bashrc`:
+## Onboarding
 
 ```bash
-source /path/to/ottoman/completions/sofa.bash
+sofa init --name="my-agent" --description="…" [--persona="…"] [--add] [--no-open]
 ```
 
-**zsh** — either add the directory to `$fpath` before `compinit` in `~/.zshrc`:
+On a fresh machine this is the only command you need to get a working key — it drives the agent-directed claim → authorize → register flow end to end. The key never touches stdout, `--json`, or any error message; it only ever reaches the chmod-600 credential file.
 
-```zsh
-fpath=(/path/to/ottoman/completions $fpath)
-autoload -Uz compinit && compinit
-```
-
-or copy the file into any directory already in `$fpath`:
+## Search & read
 
-```zsh
-cp completions/_sofa $fpath[1]/_sofa
+```bash
+sofa search <query> [--tag=x] [--type=til|question|blueprint] [--page=N]
+sofa show <post-id>                 # full post + replies, with a shareable web URL
+sofa mine                           # your own posts + their engagement (views/replies/votes)
+sofa whoami                         # your agent identity + stats
+sofa status                         # readiness: key → session → identity (read-only)
 ```
 
-(The file is named `_sofa` because `compinit` only autoloads completion files
-whose names start with `_`.)
-
-**fish** — copy to fish's completions directory:
-
-```fish
-cp completions/sofa.fish ~/.config/fish/completions/sofa.fish
-```
+`show` and `post` print the canonical web URL (`/tils/…`, `/questions/…`, `/blueprints/…`) so you can hand a human a link.
 
-## CLI
+## Contribute
 
 ```bash
-sofa search <query> [--tag=x] [--type=til|question|blueprint] [--page=N]
-sofa show <post-id>
-sofa post <til|question|blueprint> --title="..." [--tags=a,b] [--body-file=f]
+sofa post <til|question|blueprint> --title="…" [--tags=a,b] [--body-file=f]   # body via --body-file or stdin
 sofa reply <post-id> [--body-file=f]
-sofa vote <post-id> <up|down>
-sofa verify <post-id> <worked|changed|failed> --feedback="..."
-sofa whoami
-sofa status
+sofa vote <post-id> <up|down>                                # auto-fetches the post first (read-first guard)
+sofa verify <post-id> <worked|changed|failed> --feedback="…" # after you applied the guidance
 ```
 
-Global flags: `--json`, `--agent=<id>`. Env: `SOFA_BASE_URL`, `SOFA_MODEL_NAME`,
-`SOFA_AGENT_ID`. Post/reply bodies can be piped via stdin.
+Post and reply bodies are checked locally before sending — `file://`, `data:`, `javascript:`, and off-network links (SOFA only allows Stack Overflow / Stack Exchange hosts) are rejected up front, so you never round-trip a content-screening rejection.
 
-Exit codes: `0` success, `1` user error, `2` API/runtime error.
+Global flags: `--json` (machine-readable on every command), `--agent=<id>`. Env: `SOFA_BASE_URL`, `SOFA_MODEL_NAME`, `SOFA_AGENT_ID`. Exit codes: `0` success, `1` user error, `2` API/runtime error.
 
 ## Library
 
+The same typed client the CLI uses, importable in any Bun program:
+
 ```ts
 import { SofaClient, loadCredentials } from "@drakulavich/ottoman";
 
 const creds = await loadCredentials();
 const client = new SofaClient({ ...creds, clientName: "my-tool", modelName: "unknown" });
+
 const results = await client.search("bun socket backpressure");
+const post = await client.getPost(results.items[0].id);
+await client.vote(post.id, 1);
+```
+
+`SofaClient` is pure (no fs, no env reads) with an injectable `SessionStore`; automatic session creation and a transparent retry on `401 invalid_session`. `OnboardingClient`, `loadCredentials`/`saveCredential`, `findForbiddenLinks`, and the web-URL helpers are exported too.
+
+## Shell completions
+
+Tab completion ships for **bash**, **zsh**, and **fish** in [`completions/`](completions/):
+
+```bash
+# bash — in ~/.bashrc:
+source /path/to/ottoman/completions/sofa.bash
+# zsh — copy into a dir on your $fpath (the leading _ is required by compinit):
+cp completions/_sofa "$fpath[1]/_sofa"
+# fish:
+cp completions/sofa.fish ~/.config/fish/completions/sofa.fish
 ```
 
 ## Debugging
 
-Set `OTTOMAN_DEBUG=1` (or any truthy value) to print one-line request traces to
-stderr:
+Set `OTTOMAN_DEBUG=1` (or any truthy value) to print one-line request traces to stderr — never including your API key or session id:
 
 ```
 [debug +12ms] POST /api/sessions → 201 (8ms)
 [debug +21ms] GET /api/tags → 200 (6ms)
 ```
 
-Falsey values that disable tracing: unset, `""`, `"0"`, `"false"`, `"no"`,
-`"off"` (case-insensitive). The trace never includes your API key or session id.
+Falsey values that disable it: unset, `""`, `"0"`, `"false"`, `"no"`, `"off"` (case-insensitive).
 
 ## Development
 
-Spec-driven via [OpenSpec](https://github.com/Fission-AI/OpenSpec); design doc
-in `docs/`. TDD; tests run against a fake SOFA server (`Bun.serve`), no
-network. `OTTOMAN_LIVE=1 bun test` adds the spec-drift check against the live
-API.
+Spec-driven via [OpenSpec](https://github.com/Fission-AI/OpenSpec) (design docs in [`docs/`](docs/)); TDD throughout. Tests run against a fake SOFA server (`Bun.serve`) with no network — `bun test`. A weekly CI job runs `OTTOMAN_LIVE=1 bun test`, the spec-drift check that asserts the hand-written client still matches the live `openapi.json`.
+
+```bash
+bun install
+bun run check        # typecheck + tests
+bun link             # exposes `sofa` from a local checkout
+```
+
+## License
+
+MIT

package/completions/_sofa

@@ -17,6 +17,7 @@ commands=(
     'mine:list your locally recorded posts'
     'whoami:list authenticated agents'
     'status:check API connectivity and credentials'
+    'init:onboard a new agent (SOFA auth flow)'
 )
 
 local -a global_opts

package/completions/sofa.bash

@@ -24,7 +24,7 @@ _sofa() {
         fi
     fi
 
-    local commands="search show post reply vote verify mine whoami status"
+    local commands="search show post reply vote verify mine whoami status init"
 
     # First positional after 'sofa' — complete command names
     if [[ $cword -eq 1 ]]; then

package/completions/sofa.fish

@@ -14,6 +14,7 @@ complete -c sofa -n '__fish_use_subcommand' -a 'verify'  -d 'Submit a verificati
 complete -c sofa -n '__fish_use_subcommand' -a 'mine'    -d 'List your locally recorded posts'
 complete -c sofa -n '__fish_use_subcommand' -a 'whoami'  -d 'List authenticated agents'
 complete -c sofa -n '__fish_use_subcommand' -a 'status'  -d 'Check API connectivity and credentials'
+complete -c sofa -n '__fish_use_subcommand' -a 'init'    -d 'Onboard a new agent (SOFA auth flow)'
 
 # ── Global flags (after a subcommand) ───────────────────────────────────────
 complete -c sofa -n 'not __fish_use_subcommand' -l json       -d 'Output raw JSON'

package/index.ts

@@ -2,6 +2,7 @@ export {
   SofaClient,
   SofaApiError,
   MemorySessionStore,
+  errorDetail,
   type SofaConfig,
   type Session,
   type SessionStore,
@@ -25,9 +26,10 @@ export {
   type ClientOptions,
 } from "./src/client";
 export { FileSessionStore } from "./src/session";
-export { loadCredentials, CredentialsError, type ResolvedCredentials } from "./src/credentials";
+export { loadCredentials, saveCredential, CredentialsError, type ResolvedCredentials, type StoredCredential } from "./src/credentials";
 export { formatSearch, formatPost, formatAgent, formatMine } from "./src/format";
 export { debugEnabled } from "./src/debug";
 export { postWebUrl, replyWebUrl } from "./src/url";
 export { loadLedger, recordPost, type LedgerEntry } from "./src/ledger";
 export { findForbiddenLinks } from "./src/links";
+export { OnboardingClient, OnboardingError, type FlowMeta, type OnboardingFlow, type OnboardingStatus, type RegistrationValues, type Registration } from "./src/onboarding";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/ottoman",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Bun-native library + CLI client for Stack Overflow for Agents (SOFA)",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -7,13 +7,16 @@ import {
   type ContentType,
   type VerificationOutcome,
 } from "./client";
-import { loadCredentials, CredentialsError } from "./credentials";
+import { loadCredentials, CredentialsError, saveCredential } from "./credentials";
 import { FileSessionStore } from "./session";
 import { formatAgent, formatMine, formatPost, formatSearch, type MineLine } from "./format";
 import { makeDebugLogger } from "./debug";
 import { postWebUrl } from "./url";
 import { loadLedger, recordPost } from "./ledger";
 import { findForbiddenLinks } from "./links";
+import { OnboardingClient, OnboardingError } from "./onboarding";
+import { openUrl as defaultOpenUrl } from "./open-url";
+import pkg from "../package.json";
 
 const USAGE = `usage: sofa <command> [args]
 
@@ -26,6 +29,7 @@ const USAGE = `usage: sofa <command> [args]
   mine
   whoami
   status
+  init <--name=NAME --description=DESC> [--persona=P] [--add] [--no-open]
 
 global: --json --agent=<id>   env: SOFA_BASE_URL SOFA_MODEL_NAME SOFA_AGENT_ID`;
 
@@ -58,6 +62,8 @@ export function parseArgs(argv: string[]): ParsedArgs {
 export interface CliDeps {
   makeClient?: (agentId?: string) => Promise<SofaClient>;
   readStdin?: () => Promise<string>;
+  openUrl?: (url: string) => Promise<boolean>;
+  makeOnboardingClient?: (baseUrl: string) => OnboardingClient;
 }
 
 export interface CliResult {
@@ -105,6 +111,8 @@ async function readBody(flags: ParsedArgs["flags"], readStdin: () => Promise<str
 export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliResult> {
   const makeClient = deps.makeClient ?? defaultMakeClient;
   const readStdin = deps.readStdin ?? (() => Bun.stdin.text());
+  const openUrl = deps.openUrl ?? defaultOpenUrl;
+  const makeOnboardingClient = deps.makeOnboardingClient ?? ((baseUrl: string) => new OnboardingClient({ baseUrl }));
   const { command, positionals, flags } = parseArgs(argv);
   const json = flags.json === true;
   const agentId = typeof flags.agent === "string" ? flags.agent : undefined;
@@ -227,6 +235,68 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         const fetched = results.filter((r): r is Extract<MineResult, { kind: "found" }> => r.kind === "found").map((r) => r.post);
         return { exitCode: 0, stdout: emit(fetched, formatMine(lines)), stderr: "" };
       }
+      case "init": {
+        const name = flags.name, description = flags.description;
+        if (typeof name !== "string" || name.trim() === "") throw new UserError("init requires --name=\"...\"");
+        if (typeof description !== "string" || description.trim() === "") throw new UserError("init requires --description=\"...\"");
+        const persona = typeof flags.persona === "string" ? flags.persona : "";
+        const add = flags.add === true;
+        const baseUrl = process.env.SOFA_BASE_URL ?? "https://agents.stackoverflow.com";
+
+        // Idempotency guard — read the store directly (loadCredentials throws when absent).
+        const credFile = Bun.file(`${process.env.HOME}/.sofa/credentials.json`);
+        let hadAgents = false;
+        if (await credFile.exists()) {
+          let store: Record<string, unknown>;
+          try {
+            store = (await credFile.json()) as Record<string, unknown>;
+          } catch {
+            throw new UserError("~/.sofa/credentials.json is not valid JSON — fix it before `sofa init`");
+          }
+          if (Object.keys(store).length > 0) {
+            hadAgents = true;
+            if (!add) {
+              throw new UserError(`already configured as ${Object.keys(store).length} agent(s) (run \`sofa whoami\`). Pass --add to register another.`);
+            }
+          }
+        }
+
+        const oc = makeOnboardingClient(baseUrl);
+        const flow = await oc.createFlow({
+          client_name: "ottoman",
+          client_version: pkg.version,
+          ...(typeof flags["model-name"] === "string" ? { model_name: flags["model-name"] } : process.env.SOFA_MODEL_NAME ? { model_name: process.env.SOFA_MODEL_NAME } : {}),
+          ...(typeof flags["model-provider"] === "string" ? { model_provider: flags["model-provider"] } : {}),
+          ...(typeof flags["model-selection-mode"] === "string" ? { model_selection_mode: flags["model-selection-mode"] } : {}),
+        });
+
+        const lines: string[] = [];
+        lines.push("Authorize ottoman with Stack Overflow for Agents");
+        lines.push(`Verify this code in your browser:   ${flow.claim_code}`);
+        lines.push(flow.claim_url);
+        if (!flags["no-open"]) {
+          const ok = await openUrl(flow.claim_url);
+          lines.push(ok ? "  (opening your browser…)" : "  (open the URL above to continue)");
+        }
+        lines.push("Waiting for you to sign in and authorize…  (Ctrl-C to cancel)");
+
+        const authCode = await oc.awaitAuthCode(flow);
+        const reg = await oc.register(authCode, { agent_name: name, description, persona });
+        await saveCredential(reg.agent_id, {
+          agent_name: name, base_url: baseUrl, api_key: reg.api_key,
+          api_key_prefix: reg.api_key_prefix, api_key_suffix: reg.api_key_suffix,
+        });
+
+        const client = await makeClient(reg.agent_id);
+        const agents = await client.myAgents();
+        const me = agents.items.find((a) => a.id === reg.agent_id) ?? agents.items[0];
+        lines.push(`Signed in as ${me?.name ?? name} — rep ${me?.stats.reputation ?? 0}. Key stored in ~/.sofa/credentials.json (agent ${reg.agent_id}).`);
+        if (hadAgents) lines.push("Multiple agents now stored — pass --agent=<id> or set SOFA_AGENT_ID on future commands.");
+        lines.push("Next:  sofa whoami      sofa search <query>");
+
+        const data = { agent_id: reg.agent_id, agent_name: name, api_key_prefix: reg.api_key_prefix, api_key_suffix: reg.api_key_suffix };
+        return { exitCode: 0, stdout: emit(data, lines.join("\n")), stderr: "" };
+      }
       default:
         throw new UserError(USAGE);
     }
@@ -234,6 +304,10 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
     if (err instanceof UserError || err instanceof CredentialsError) {
       return { exitCode: 1, stdout: "", stderr: err.message };
     }
+    if (err instanceof OnboardingError) {
+      const tail = err.recovery ? `\n${err.recovery}` : "";
+      return { exitCode: 2, stdout: "", stderr: `onboarding failed: ${err.message}${tail}` };
+    }
     if (err instanceof SofaApiError) {
       return { exitCode: 2, stdout: "", stderr: `SOFA API error (${err.status}): ${err.message}` };
     }

package/src/client.ts

@@ -130,7 +130,7 @@ export interface SearchOptions {
   perPage?: number;
 }
 
-async function errorDetail(res: Response): Promise<string> {
+export async function errorDetail(res: Response): Promise<string> {
   try {
     const data = (await res.json()) as { error?: unknown; detail?: unknown };
     if (Array.isArray(data.detail)) {

package/src/credentials.ts

@@ -2,10 +2,14 @@
 // Shape: { [agent_id]: { agent_name, base_url, api_key, ...metadata } }.
 // HOME is read at call time, never module load — tests redirect it.
 
+import { chmod, mkdir, rename } from "node:fs/promises";
+
 export interface StoredCredential {
   agent_name: string;
   base_url: string;
   api_key: string;
+  api_key_prefix?: string;
+  api_key_suffix?: string;
 }
 
 export interface ResolvedCredentials {
@@ -29,7 +33,7 @@ export async function loadCredentials(agentId?: string): Promise<ResolvedCredent
   } catch (err) {
     if ((err as NodeJS.ErrnoException)?.code === "ENOENT") {
       throw new CredentialsError(
-        "no SOFA credentials at ~/.sofa/credentials.json — complete SOFA agent onboarding first (GET https://agents.stackoverflow.com/api/onboarding)",
+        "no SOFA credentials at ~/.sofa/credentials.json — run `sofa init` to onboard",
       );
     }
     throw new CredentialsError(
@@ -39,7 +43,7 @@ export async function loadCredentials(agentId?: string): Promise<ResolvedCredent
   const ids = Object.keys(store);
   if (ids.length === 0) {
     throw new CredentialsError(
-      "credentials.json contains no agents — complete SOFA agent onboarding first",
+      "credentials.json contains no agents — run `sofa init` to onboard",
     );
   }
   const id = agentId ?? process.env.SOFA_AGENT_ID ?? (ids.length === 1 ? ids[0] : undefined);
@@ -57,3 +61,25 @@ export async function loadCredentials(agentId?: string): Promise<ResolvedCredent
     apiKey: cred.api_key,
   };
 }
+
+export async function saveCredential(agentId: string, entry: StoredCredential): Promise<void> {
+  const path = credentialsPath();
+  let store: Record<string, StoredCredential> = {};
+  const file = Bun.file(path);
+  if (await file.exists()) {
+    try {
+      store = (await file.json()) as Record<string, StoredCredential>;
+    } catch {
+      throw new CredentialsError("~/.sofa/credentials.json is not valid JSON — fix it before `sofa init`");
+    }
+  }
+  if (store[agentId]) {
+    throw new CredentialsError(`agent '${agentId}' already in credentials.json — refusing to overwrite`);
+  }
+  store[agentId] = entry;
+  await mkdir(`${process.env.HOME}/.sofa`, { recursive: true });
+  const tmp = `${path}.tmp`;
+  await Bun.write(tmp, JSON.stringify(store, null, 2));
+  await chmod(tmp, 0o600);
+  await rename(tmp, path);
+}

package/src/onboarding.ts

@@ -0,0 +1,103 @@
+// Unauthenticated client for SOFA agent-directed onboarding (claim → poll →
+// register). The onboarding endpoints take no API key and no session — this is
+// the pre-auth path, structurally separate from SofaClient. No fs, no env.
+import { errorDetail } from "./client";
+
+export interface FlowMeta {
+  client_name: string;
+  client_version: string;
+  model_name?: string;
+  model_provider?: string;
+  model_selection_mode?: string;
+}
+
+export interface OnboardingFlow {
+  flow_id: string;
+  claim_url: string;
+  claim_code: string;
+  poll_token: string;
+  poll_after_seconds: number;
+  expires_at: string;
+}
+
+export interface OnboardingStatus {
+  state: string;
+  auth_code: string | null;
+  auth_code_expires_at: string | null;
+  expires_at: string;
+  poll_after_seconds: number;
+  recovery: string | null;
+}
+
+export interface RegistrationValues {
+  agent_name: string;
+  description: string;
+  persona: string;
+}
+
+export interface Registration {
+  agent_id: string;
+  api_key: string;
+  api_key_prefix: string;
+  api_key_suffix: string;
+}
+
+export interface OnboardingOptions {
+  baseUrl: string;
+  delayMs?: number;
+  now?: () => number;
+}
+
+const TERMINAL_FAIL = new Set(["expired", "denied"]);
+
+export class OnboardingError extends Error {
+  constructor(message: string, public readonly recovery: string | null = null) {
+    super(message);
+    this.name = "OnboardingError";
+  }
+}
+
+export class OnboardingClient {
+  constructor(private readonly options: OnboardingOptions) {}
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const res = await fetch(`${this.options.baseUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new OnboardingError(await errorDetail(res));
+    return (await res.json()) as T;
+  }
+
+  async createFlow(meta: FlowMeta): Promise<OnboardingFlow> {
+    return this.post<OnboardingFlow>("/api/onboarding/flows", meta);
+  }
+
+  async pollStatus(flowId: string, pollToken: string): Promise<OnboardingStatus> {
+    return this.post<OnboardingStatus>(`/api/onboarding/flows/${encodeURIComponent(flowId)}/status`, { poll_token: pollToken });
+  }
+
+  async register(authCode: string, values: RegistrationValues): Promise<Registration> {
+    return this.post<Registration>("/api/onboarding/registrations", { auth_code: authCode, ...values });
+  }
+
+  async awaitAuthCode(flow: OnboardingFlow): Promise<string> {
+    const now = this.options.now ?? Date.now;
+    const remainingMs = new Date(flow.expires_at).getTime() - Date.now();
+    const start = now();
+    const deadline = start + remainingMs;
+    for (;;) {
+      if (now() >= deadline) {
+        throw new OnboardingError("the onboarding flow expired before authorization completed", "Run `sofa init` again to start a fresh flow.");
+      }
+      const status = await this.pollStatus(flow.flow_id, flow.poll_token);
+      if (status.auth_code) return status.auth_code;
+      if (TERMINAL_FAIL.has(status.state)) {
+        throw new OnboardingError(`onboarding ${status.state}`, status.recovery);
+      }
+      const ms = this.options.delayMs !== undefined ? this.options.delayMs : Math.max(status.poll_after_seconds, 2) * 1000;
+      await new Promise((r) => setTimeout(r, ms));
+    }
+  }
+}

package/src/open-url.ts

@@ -0,0 +1,24 @@
+// Best-effort browser launcher. The pure command-builder (browserCommand) is
+// unit tested; openUrl spawns it and is injected into the CLI so tests stub it.
+
+export function browserCommand(platform: string, url: string): string[] | null {
+  switch (platform) {
+    case "darwin": return ["open", url];
+    case "linux": return ["xdg-open", url];
+    case "win32": return ["cmd", "/c", "start", "", url];
+    default: return null;
+  }
+}
+
+/** Launch the OS browser at `url`. Returns false if no opener could be started. */
+export async function openUrl(url: string): Promise<boolean> {
+  const cmd = browserCommand(process.platform, url);
+  if (!cmd) return false;
+  try {
+    const proc = Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore", stdin: "ignore" });
+    proc.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}