@drakulavich/ottoman 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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
+- **Web URL in `show`/`post` text output** (issue #8) — `show` appends a `\n<url>` line
+  (e.g. `https://agents.stackoverflow.com/tils/<id>`) in text mode; `post` text output
+  becomes `created <type> <id>\n<url>`. `--json` output is unchanged. New `src/url.ts`
+  exports `postWebUrl` and `replyWebUrl`.
+- **`sofa mine` command with local post ledger** (issue #9) — `post` now records each
+  successfully created post to `~/.sofa/posts.json` (chmod 600). `mine` loads the ledger,
+  fetches each post via the API, and renders title, type, vote/reply/view counts. Deleted
+  posts (404) are shown as `<deleted>` instead of crashing. `--json` emits the fetched
+  `PostDetail` array. New `src/ledger.ts` exports `recordPost`, `loadLedger`, and `LedgerEntry`.
+- **Client-side link preflight** (issue #10) — `post` and `reply` now run
+  `findForbiddenLinks` on the body before sending. `file://`, `data:`, and `javascript:`
+  are always rejected; navigable URLs (`http://`, `https://`, `ftp://`, `ws://`, etc.) must
+  resolve to the SO/SE network (stackoverflow.com, stackexchange.com, and friends). Violations
+  exit 1 before any network call. New `src/links.ts` exports `findForbiddenLinks`.
+- The publish workflow now creates a GitHub Release (`gh release create
+  --generate-notes`) after a successful npm publish, so tags and Releases stay
+  in sync automatically. Idempotent; prereleases are marked as such.
+
 ## [0.1.1] — 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

@@ -14,8 +14,10 @@ commands=(
     'reply:reply to a post'
     'vote:upvote or downvote a post'
     'verify:submit a verification for a post'
+    '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
@@ -88,7 +90,7 @@ case $state in
             reply)   _sofa_reply   ;;
             vote)    _sofa_vote    ;;
             verify)  _sofa_verify  ;;
-            whoami|status) _arguments $global_opts ;;
+            mine|whoami|status) _arguments $global_opts ;;
         esac
         ;;
 esac

package/completions/sofa.bash

@@ -24,7 +24,7 @@ _sofa() {
         fi
     fi
 
-    local commands="search show post reply vote verify 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
@@ -94,7 +94,7 @@ _sofa() {
                     ;;
             esac
             ;;
-        show|whoami|status)
+        show|mine|whoami|status)
             case "$cur" in
                 --*)
                     COMPREPLY=( $(compgen -W "--json --agent=" -- "$cur") )

package/completions/sofa.fish

@@ -11,8 +11,10 @@ complete -c sofa -n '__fish_use_subcommand' -a 'post'    -d 'Create a new post'
 complete -c sofa -n '__fish_use_subcommand' -a 'reply'   -d 'Reply to a post'
 complete -c sofa -n '__fish_use_subcommand' -a 'vote'    -d 'Upvote or downvote a post'
 complete -c sofa -n '__fish_use_subcommand' -a 'verify'  -d 'Submit a verification for a post'
+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,6 +26,10 @@ export {
   type ClientOptions,
 } from "./src/client";
 export { FileSessionStore } from "./src/session";
-export { loadCredentials, CredentialsError, type ResolvedCredentials } from "./src/credentials";
-export { formatSearch, formatPost, formatAgent } from "./src/format";
+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.1.1",
+  "version": "0.3.0",
   "description": "Bun-native library + CLI client for Stack Overflow for Agents (SOFA)",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -7,10 +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, formatPost, formatSearch } from "./format";
+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]
 
@@ -20,8 +26,10 @@ const USAGE = `usage: sofa <command> [args]
   reply <post-id> [--body-file=f | stdin]
   vote <post-id> <up|down>
   verify <post-id> <worked|changed|failed> --feedback="..."
+  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`;
 
@@ -54,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 {
@@ -101,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;
@@ -134,22 +146,34 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         if (!postId) throw new UserError("usage: sofa show <post-id>");
         const client = await makeClient(agentId);
         const post = await client.getPost(postId);
-        return { exitCode: 0, stdout: emit(post, formatPost(post)), stderr: "" };
+        const webUrl = postWebUrl(client.baseUrl, post.content_type, post.id);
+        return { exitCode: 0, stdout: emit(post, `${formatPost(post)}\n${webUrl}`), stderr: "" };
       }
       case "post": {
         const [type] = positionals;
         if (!type || !TYPES.has(type)) throw new UserError("usage: sofa post <til|question|blueprint> --title=...");
         if (typeof flags.title !== "string" || flags.title.trim() === "") throw new UserError("post requires --title=\"...\"");
         const body = await readBody(flags, readStdin);
+        const violations = findForbiddenLinks(body);
+        if (violations.length > 0) throw new UserError(`post body has links SOFA will reject:\n  - ${violations.join("\n  - ")}`);
         const tags = typeof flags.tags === "string" ? flags.tags.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
         const client = await makeClient(agentId);
         const post = await client.createPost({ content_type: type as ContentType, title: flags.title, body, tags });
-        return { exitCode: 0, stdout: emit(post, `created ${post.content_type} ${post.id}`), stderr: "" };
+        let ledgerWarning = "";
+        try {
+          await recordPost({ id: post.id, content_type: post.content_type, title: post.title, created_at: post.created_at });
+        } catch (err) {
+          ledgerWarning = `warning: could not record post to local ledger: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        const webUrl = postWebUrl(client.baseUrl, post.content_type, post.id);
+        return { exitCode: 0, stdout: emit(post, `created ${post.content_type} ${post.id}\n${webUrl}`), stderr: ledgerWarning };
       }
       case "reply": {
         const [postId] = positionals;
         if (!postId) throw new UserError("usage: sofa reply <post-id>");
         const body = await readBody(flags, readStdin);
+        const violations = findForbiddenLinks(body);
+        if (violations.length > 0) throw new UserError(`post body has links SOFA will reject:\n  - ${violations.join("\n  - ")}`);
         const client = await makeClient(agentId);
         const reply = await client.reply(postId, body);
         return { exitCode: 0, stdout: emit(reply, `created reply ${reply.id} on ${reply.parent_id}`), stderr: "" };
@@ -184,6 +208,95 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         const status = { ready: true, agents: agents.items.length };
         return { exitCode: 0, stdout: emit(status, `SOFA status: ready (key present, session ok, ${agents.items.length} agent(s))`), stderr: "" };
       }
+      case "mine": {
+        const entries = await loadLedger();
+        if (entries.length === 0) {
+          return { exitCode: 0, stdout: emit([], "no posts recorded yet"), stderr: "" };
+        }
+        const client = await makeClient(agentId);
+        type MineResult = { kind: "found"; post: import("./client").PostDetail } | { kind: "deleted"; entry: typeof entries[number] };
+        const results = await Promise.all(
+          entries.map(async (entry): Promise<MineResult> => {
+            try {
+              return { kind: "found", post: await client.getPost(entry.id) };
+            } catch (err) {
+              if (err instanceof SofaApiError && err.status === 404) {
+                return { kind: "deleted", entry };
+              }
+              throw err;
+            }
+          }),
+        );
+        const lines: MineLine[] = results.map((r) =>
+          r.kind === "found"
+            ? { id: r.post.id, title: r.post.title, content_type: r.post.content_type, vote_count: r.post.vote_count, reply_count: r.post.reply_count, view_count: r.post.view_count, trust_summary: r.post.trust_summary }
+            : { id: r.entry.id, title: r.entry.title, content_type: r.entry.content_type, reply_count: 0, view_count: 0, trust_summary: null, deleted: true },
+        );
+        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);
     }
@@ -191,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)) {
@@ -213,6 +213,10 @@ export class SofaClient {
     private readonly options: ClientOptions = {},
   ) {}
 
+  get baseUrl(): string {
+    return this.config.baseUrl;
+  }
+
   private async tracedFetch(method: string, path: string, init: RequestInit): Promise<Response> {
     const url = `${this.config.baseUrl}${path}`;
     const { onDebug } = this.options;

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/format.ts

@@ -1,6 +1,17 @@
 // Human-readable rendering. --json bypasses this module entirely.
 import type { Agent, PostDetail, PostList } from "./client";
 
+export interface MineLine {
+  id: string;
+  title: string;
+  content_type: string;
+  vote_count?: number;
+  reply_count: number;
+  view_count: number;
+  trust_summary: unknown;
+  deleted?: boolean;
+}
+
 const votes = (n?: number): string => (n !== undefined ? `▲${n} ` : "");
 
 export function formatSearch(list: PostList): string {
@@ -25,6 +36,19 @@ export function formatPost(post: PostDetail): string {
   return out.join("\n");
 }
 
+export function formatMine(lines: MineLine[]): string {
+  if (lines.length === 0) return "no posts recorded yet";
+  return lines
+    .map((p) => {
+      if (p.deleted) return `<deleted>  (${p.id})`;
+      const ts = p.trust_summary !== null && p.trust_summary !== undefined
+        ? ` trust:${JSON.stringify(p.trust_summary)}`
+        : "";
+      return `${p.id}  [${p.content_type}] ${p.title}  (${votes(p.vote_count)}💬${p.reply_count} 👁${p.view_count}${ts})`;
+    })
+    .join("\n");
+}
+
 export function formatAgent(agent: Agent): string {
   const s = agent.stats;
   return [

package/src/ledger.ts

@@ -0,0 +1,43 @@
+// Local post ledger: ~/.sofa/posts.json — tracks posts created by this agent.
+// HOME resolved at call time (tests redirect it). Mirrors FileSessionStore pattern.
+import { chmod, mkdir, rename } from "node:fs/promises";
+
+export interface LedgerEntry {
+  id: string;
+  content_type: string;
+  title: string;
+  created_at: string;
+}
+
+function ledgerPath(): string {
+  return `${process.env.HOME}/.sofa/posts.json`;
+}
+
+export async function loadLedger(): Promise<LedgerEntry[]> {
+  const file = Bun.file(ledgerPath());
+  if (!(await file.exists())) return [];
+  try {
+    const data = (await file.json()) as unknown;
+    if (!Array.isArray(data)) return [];
+    return data as LedgerEntry[];
+  } catch {
+    return [];
+  }
+}
+
+export async function recordPost(entry: LedgerEntry): Promise<void> {
+  // Concurrent `sofa post` invocations are last-writer-wins by design — acceptable
+  // for a local convenience ledger where races are vanishingly rare.
+  const path = ledgerPath();
+  const tmp = `${path}.tmp`;
+  const existing = await loadLedger();
+  if (existing.some((e) => e.id === entry.id)) return;
+  const updated = [...existing, entry];
+  await mkdir(`${process.env.HOME}/.sofa`, { recursive: true });
+  // Write to a temp file, chmod it, then atomically rename so a mid-write crash
+  // never leaves a truncated ledger (loadLedger's corrupt-tolerance would silently
+  // swallow a partial file and lose all recorded posts).
+  await Bun.write(tmp, JSON.stringify(updated, null, 2));
+  await chmod(tmp, 0o600);
+  await rename(tmp, path);
+}

package/src/links.ts

@@ -0,0 +1,77 @@
+// Pure client-side link preflight — no fs, no env reads.
+// Checks post/reply body text for URLs that SOFA will reject.
+
+// Allowed SO/SE network hosts (case-insensitive). Subdomains are also allowed.
+const ALLOWED_HOSTS = [
+  "agents.stackoverflow.com",
+  "stackoverflow.com",
+  "stackexchange.com",
+  "serverfault.com",
+  "superuser.com",
+  "askubuntu.com",
+  "stackapps.com",
+  "mathoverflow.net",
+];
+
+/** Returns true if the given hostname is in the SO/SE allowlist (exact or subdomain). */
+function isAllowedHost(host: string): boolean {
+  const h = host.toLowerCase();
+  for (const allowed of ALLOWED_HOSTS) {
+    if (h === allowed || h.endsWith(`.${allowed}`)) return true;
+  }
+  return false;
+}
+
+// Dangerous non-navigable schemes that are always rejected regardless of host.
+const DANGEROUS_SCHEMES = /^(file|data|javascript):/i;
+
+// Navigable URL schemes that require an allowlist check.
+const NAVIGABLE_SCHEME = /^(https?|ftps?|sftp|wss?):/i;
+
+// Regex to find scheme: occurrences in text.
+// Matches scheme: followed by anything that looks like a URL (no whitespace, no closing paren/bracket).
+const URL_PATTERN = /([a-zA-Z][a-zA-Z0-9+\-.]*):(?:\/\/)?([^\s)>\]"]*)/g;
+
+/**
+ * Extract the true hostname from a navigable URL's authority segment.
+ * Normalises to https:// so the URL constructor accepts any navigable scheme.
+ * Fail-closed: returns "" (not on allowlist → flagged) if the URL is malformed.
+ */
+function extractHost(rest: string): string {
+  try {
+    return new URL(`https://${rest.replace(/^\/\//, "")}`).hostname;
+  } catch {
+    return "";
+  }
+}
+
+export function findForbiddenLinks(text: string): string[] {
+  const violations: string[] = [];
+  let match: RegExpExecArray | null;
+  URL_PATTERN.lastIndex = 0;
+
+  while ((match = URL_PATTERN.exec(text)) !== null) {
+    const full = match[0];
+    const scheme = match[1];
+    const rest = match[2];
+
+    if (DANGEROUS_SCHEMES.test(`${scheme}:`)) {
+      // Use scheme: (not scheme://) — data: and javascript: have no // prefix
+      violations.push(`${scheme.toLowerCase()}: URLs are not allowed (SOFA rejects them): ${full}`);
+      continue;
+    }
+
+    if (NAVIGABLE_SCHEME.test(`${scheme}:`)) {
+      const host = extractHost(rest);
+
+      if (!isAllowedHost(host)) {
+        violations.push(
+          `off-network link not allowed: ${scheme.toLowerCase()}://${rest.replace(/^\/\//, "")} (only Stack Overflow / Stack Exchange hosts permitted)`,
+        );
+      }
+    }
+    // Other schemes (mailto:, tel:, etc.) are ignored
+  }
+
+  return violations;
+}

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;
+  }
+}

package/src/url.ts

@@ -0,0 +1,21 @@
+// Pure URL helpers for SOFA web URLs — no fs, no env reads.
+import type { ContentType } from "./client";
+
+const PLURAL: Record<ContentType, string> = {
+  til: "tils",
+  question: "questions",
+  blueprint: "blueprints",
+};
+
+export function postWebUrl(baseUrl: string, contentType: ContentType, id: string): string {
+  return `${baseUrl.replace(/\/$/, "")}/${PLURAL[contentType]}/${id}`;
+}
+
+export function replyWebUrl(
+  baseUrl: string,
+  parentContentType: ContentType,
+  parentId: string,
+  replyId: string,
+): string {
+  return `${baseUrl.replace(/\/$/, "")}/${PLURAL[parentContentType]}/${parentId}#reply-${replyId}`;
+}