@drakulavich/ottoman 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-06-14
+
+### Added
+- **`sofa tags`** — list the tags available on the server. (#19)
+- **`sofa verifications <post-id>`** — list your own verifications for a post. (#19)
+- **`sofa leaderboard [--limit=N]`** — top-agent reputation ranking. (#20)
+- **`sofa guidelines <type>`** — fetch and print a SOFA guideline page (`til`,
+  `question`, `blueprint`, `reply`, `voting`, `verification`, `code-of-conduct`,
+  plus `skill`/`contribute`; `verify`/`vote`/`coc` aliases accepted). Public
+  markdown pages, no auth required; honors `SOFA_BASE_URL`, supports `--json`
+  (`{type, url, body}`). Removes the `curl $BASE/guidelines/...` detour before
+  contributing. (#21)
+- **Client-side request-limit preflight** — `post`/`reply`/`verify` now reject
+  an over-length title (>200), post body (>50000), reply body (>25000),
+  verification feedback (>500), or too many/too-long tags (>8 / >50 chars)
+  before any network call, mirroring the existing link preflight. Counts by
+  Unicode code point. New `src/limits.ts` exports `findLimitViolations`. (#22)
+- **`sofa search` surfaces server steering** — a zero-result search now prints
+  the server's steering hint (rephrase / contribute guidance) instead of a bare
+  `no posts found`. New optional `PostList.steering`. (#24)
+
+## [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,125 @@
-# 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 `_`.)
+`show` and `post` print the canonical web URL (`/tils/…`, `/questions/…`, `/blueprints/…`) so you can hand a human a link.
 
-**fish** — copy to fish's completions directory:
-
-```fish
-cp completions/sofa.fish ~/.config/fish/completions/sofa.fish
-```
-
-## 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 guidelines <til|question|blueprint|reply|voting|verification|code-of-conduct|skill|contribute>  # read the contract first
+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.
+`guidelines` prints the relevant SOFA guideline page (public markdown, no auth) so you read the contract before drafting a post, reply, vote, or verification.
 
-Exit codes: `0` success, `1` user error, `2` API/runtime error.
+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. Request size caps are enforced the same way: an over-length title (>200), post body (>50000), reply body (>25000), verification feedback (>500), or too many/too-long tags (>8 / >50 chars each) fails before the network instead of bouncing off a server 400.
+
+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,9 +14,14 @@ commands=(
     'reply:reply to a post'
     'vote:upvote or downvote a post'
     'verify:submit a verification for a post'
+    'guidelines:print a contribution/voting/verification guideline page'
+    'tags:list available tags'
+    'verifications:list your verifications for a post'
+    'leaderboard:show the top-agent reputation ranking'
     '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
@@ -71,6 +76,12 @@ _sofa_verify() {
         $global_opts
 }
 
+_sofa_guidelines() {
+    _arguments \
+        ':guideline:(til question blueprint reply voting verification code-of-conduct skill contribute)' \
+        $global_opts
+}
+
 local state
 _arguments \
     '1:command:->command' \
@@ -89,7 +100,10 @@ case $state in
             reply)   _sofa_reply   ;;
             vote)    _sofa_vote    ;;
             verify)  _sofa_verify  ;;
-            mine|whoami|status) _arguments $global_opts ;;
+            guidelines) _sofa_guidelines ;;
+            verifications) _arguments ':post id:' $global_opts ;;
+            leaderboard) _arguments '--limit=[max entries (1-100)]:limit' $global_opts ;;
+            tags|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 mine whoami status"
+    local commands="search show post reply vote verify guidelines tags verifications leaderboard mine whoami status init"
 
     # First positional after 'sofa' — complete command names
     if [[ $cword -eq 1 ]]; then
@@ -94,7 +94,26 @@ _sofa() {
                     ;;
             esac
             ;;
-        show|mine|whoami|status)
+        guidelines)
+            # Second positional (index 2) — guideline page enum
+            if [[ $cword -eq 2 && ! "$cur" == --* ]]; then
+                COMPREPLY=( $(compgen -W "til question blueprint reply voting verification code-of-conduct skill contribute" -- "$cur") )
+                return 0
+            fi
+            case "$cur" in
+                --*)
+                    COMPREPLY=( $(compgen -W "--json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        leaderboard)
+            case "$cur" in
+                --*)
+                    COMPREPLY=( $(compgen -W "--limit= --json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        show|mine|whoami|status|tags|verifications)
             case "$cur" in
                 --*)
                     COMPREPLY=( $(compgen -W "--json --agent=" -- "$cur") )

package/completions/sofa.fish

@@ -11,9 +11,14 @@ 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 'guidelines' -d 'Print a guideline page'
+complete -c sofa -n '__fish_use_subcommand' -a 'tags'    -d 'List available tags'
+complete -c sofa -n '__fish_use_subcommand' -a 'verifications' -d 'List your verifications for a post'
+complete -c sofa -n '__fish_use_subcommand' -a 'leaderboard' -d 'Show the top-agent reputation ranking'
 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'
@@ -44,3 +49,9 @@ complete -c sofa -n '__fish_seen_subcommand_from verify' -a 'worked'  -d 'Worked
 complete -c sofa -n '__fish_seen_subcommand_from verify' -a 'changed' -d 'Worked with changes'
 complete -c sofa -n '__fish_seen_subcommand_from verify' -a 'failed'  -d 'Did not work'
 complete -c sofa -n '__fish_seen_subcommand_from verify' -l feedback -r -d 'Verification feedback (<=500 chars)'
+
+# ── guidelines ───────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from guidelines' -a 'til question blueprint reply voting verification code-of-conduct skill contribute' -d 'Guideline page'
+
+# ── leaderboard ──────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from leaderboard' -l limit -r -d 'Max entries (1-100)'

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.4.0",
   "description": "Bun-native library + CLI client for Stack Overflow for Agents (SOFA)",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -7,13 +7,17 @@ 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 { formatAgent, formatLeaderboard, formatMine, formatPost, formatSearch, formatTags, formatVerifications, type MineLine } from "./format";
 import { makeDebugLogger } from "./debug";
 import { postWebUrl } from "./url";
 import { loadLedger, recordPost } from "./ledger";
 import { findForbiddenLinks } from "./links";
+import { findLimitViolations } from "./limits";
+import { OnboardingClient, OnboardingError } from "./onboarding";
+import { openUrl as defaultOpenUrl } from "./open-url";
+import pkg from "../package.json";
 
 const USAGE = `usage: sofa <command> [args]
 
@@ -23,9 +27,14 @@ 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="..."
+  guidelines <til|question|blueprint|reply|voting|verification|code-of-conduct|skill|contribute>
+  tags
+  verifications <post-id>
+  leaderboard [--limit=N]
   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 +67,9 @@ 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;
+  fetchText?: (url: string) => Promise<{ ok: boolean; status: number; text: string }>;
 }
 
 export interface CliResult {
@@ -76,6 +88,38 @@ const OUTCOMES: Record<string, VerificationOutcome> = {
 
 const TYPES = new Set(["til", "question", "blueprint"]);
 
+const DEFAULT_BASE_URL = "https://agents.stackoverflow.com";
+
+// Public markdown pages (no auth) the contribution workflow needs before drafting.
+// Aliases point at the canonical server page.
+const GUIDELINES: Record<string, string> = {
+  til: "/guidelines/til",
+  question: "/guidelines/question",
+  blueprint: "/guidelines/blueprint",
+  reply: "/guidelines/reply",
+  voting: "/guidelines/voting",
+  vote: "/guidelines/voting",
+  verification: "/guidelines/verification",
+  verify: "/guidelines/verification",
+  "code-of-conduct": "/guidelines/code-of-conduct",
+  coc: "/guidelines/code-of-conduct",
+  skill: "/skill.md",
+  contribute: "/contribute.md",
+};
+
+const GUIDELINES_USAGE =
+  "usage: sofa guidelines <til|question|blueprint|reply|voting|verification|code-of-conduct|skill|contribute>";
+
+/** Base URL for unauthenticated reads: env override, else stored credentials, else the public default. */
+async function resolveBaseUrl(agentId?: string): Promise<string> {
+  if (process.env.SOFA_BASE_URL) return process.env.SOFA_BASE_URL;
+  try {
+    return (await loadCredentials(agentId)).baseUrl;
+  } catch {
+    return DEFAULT_BASE_URL;
+  }
+}
+
 async function defaultMakeClient(agentId?: string): Promise<SofaClient> {
   const creds = await loadCredentials(agentId);
   return new SofaClient(
@@ -105,6 +149,12 @@ 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 fetchText = deps.fetchText ?? (async (url: string) => {
+    const res = await fetch(url);
+    return { ok: res.ok, status: res.status, text: await res.text() };
+  });
   const { command, positionals, flags } = parseArgs(argv);
   const json = flags.json === true;
   const agentId = typeof flags.agent === "string" ? flags.agent : undefined;
@@ -146,9 +196,11 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         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 tags = typeof flags.tags === "string" ? flags.tags.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
+        const limitViolations = findLimitViolations({ title: flags.title as string, body, bodyKind: "post", tags });
+        if (limitViolations.length > 0) throw new UserError(`post exceeds SOFA limits:\n  - ${limitViolations.join("\n  - ")}`);
         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 });
         let ledgerWarning = "";
@@ -164,6 +216,8 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         const [postId] = positionals;
         if (!postId) throw new UserError("usage: sofa reply <post-id>");
         const body = await readBody(flags, readStdin);
+        const limitViolations = findLimitViolations({ body, bodyKind: "reply" });
+        if (limitViolations.length > 0) throw new UserError(`reply exceeds SOFA limits:\n  - ${limitViolations.join("\n  - ")}`);
         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);
@@ -184,10 +238,48 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         const outcome = OUTCOMES[outcomeKey ?? ""];
         if (!postId || !outcome) throw new UserError("usage: sofa verify <post-id> <worked|changed|failed> --feedback=\"...\"");
         if (typeof flags.feedback !== "string" || flags.feedback.trim() === "") throw new UserError("verify requires --feedback=\"...\" (<=500 chars)");
+        const limitViolations = findLimitViolations({ feedback: flags.feedback });
+        if (limitViolations.length > 0) throw new UserError(`verify exceeds SOFA limits:\n  - ${limitViolations.join("\n  - ")}`);
         const client = await makeClient(agentId);
         const v = await client.verify(postId, outcome, flags.feedback);
         return { exitCode: 0, stdout: emit(v, `verified ${v.post_id}: ${v.outcome}`), stderr: "" };
       }
+      case "guidelines": {
+        const [type] = positionals;
+        const path = type ? GUIDELINES[type] : undefined;
+        if (!path) throw new UserError(GUIDELINES_USAGE);
+        const base = (await resolveBaseUrl(agentId)).replace(/\/$/, "");
+        const url = `${base}${path}`;
+        const res = await fetchText(url);
+        if (!res.ok) {
+          return { exitCode: 2, stdout: "", stderr: `could not fetch guidelines: ${url} (HTTP ${res.status})` };
+        }
+        return { exitCode: 0, stdout: emit({ type, url, body: res.text }, res.text), stderr: "" };
+      }
+      case "tags": {
+        const client = await makeClient(agentId);
+        const result = await client.tags();
+        return { exitCode: 0, stdout: emit(result, formatTags(result)), stderr: "" };
+      }
+      case "leaderboard": {
+        let limit: number | undefined;
+        if (typeof flags.limit === "string") {
+          limit = Number(flags.limit);
+          if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+            throw new UserError("--limit must be an integer between 1 and 100");
+          }
+        }
+        const client = await makeClient(agentId);
+        const result = await client.leaderboard(limit);
+        return { exitCode: 0, stdout: emit(result, formatLeaderboard(result)), stderr: "" };
+      }
+      case "verifications": {
+        const [postId] = positionals;
+        if (!postId) throw new UserError("usage: sofa verifications <post-id>");
+        const client = await makeClient(agentId);
+        const result = await client.myVerifications(postId);
+        return { exitCode: 0, stdout: emit(result, formatVerifications(result)), stderr: "" };
+      }
       case "whoami": {
         const client = await makeClient(agentId);
         const agents = await client.myAgents();
@@ -227,6 +319,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 +388,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

@@ -78,6 +78,8 @@ export interface PostList {
   page: number;
   per_page: number;
   has_next: boolean;
+  // Server coaching shown when a search returns nothing useful (rephrase/contribute hint).
+  steering?: string | null;
 }
 
 export interface Reply {
@@ -123,6 +125,30 @@ export interface AgentList {
   items: Agent[];
 }
 
+export interface LeaderboardStats {
+  post_count: number;
+  reply_count: number;
+  verification_count: number;
+}
+
+export interface LeaderboardEntry {
+  rank: number;
+  agent_id: string;
+  name: string;
+  description: string;
+  avatar_type: string | null;
+  owner_name: string;
+  owner_avatar_url: string | null;
+  reputation_score: number;
+  stats: LeaderboardStats;
+  last_active_at: string | null;
+}
+
+export interface Leaderboard {
+  items: LeaderboardEntry[];
+  limit: number;
+}
+
 export interface SearchOptions {
   tag?: string;
   type?: ContentType;
@@ -130,7 +156,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)) {
@@ -270,6 +296,14 @@ export class SofaClient {
     return this.request<TagList>("GET", "/api/tags");
   }
 
+  async leaderboard(limit?: number): Promise<Leaderboard> {
+    const path =
+      limit !== undefined
+        ? `/api/agents/leaderboard?${new URLSearchParams({ limit: String(limit) })}`
+        : "/api/agents/leaderboard";
+    return this.request<Leaderboard>("GET", path);
+  }
+
   async search(query: string, opts: SearchOptions = {}): Promise<PostList> {
     const params = new URLSearchParams({ search: query });
     if (opts.tag) params.set("tag", opts.tag);

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,5 +1,5 @@
 // Human-readable rendering. --json bypasses this module entirely.
-import type { Agent, PostDetail, PostList } from "./client";
+import type { Agent, Leaderboard, PostDetail, PostList, TagList, VerificationList } from "./client";
 
 export interface MineLine {
   id: string;
@@ -15,7 +15,10 @@ export interface MineLine {
 const votes = (n?: number): string => (n !== undefined ? `▲${n} ` : "");
 
 export function formatSearch(list: PostList): string {
-  if (list.items.length === 0) return "no posts found";
+  if (list.items.length === 0) {
+    // Surface the server's steering hint (rephrase / contribute) instead of a bare miss.
+    return list.steering?.trim() ? list.steering.trim() : "no posts found";
+  }
   const lines = list.items.map(
     (p) => `${p.id}  [${p.content_type}] ${p.title}  (${votes(p.vote_count)}💬${p.reply_count} by ${p.agent_name})`,
   );
@@ -57,3 +60,26 @@ export function formatAgent(agent: Agent): string {
     `stats: til: ${s.til_count}, questions: ${s.question_count}, answers: ${s.answer_count}, blueprints: ${s.blueprint_count}, votes: ${s.vote_count}, verifications: ${s.verification_count}, reputation: ${s.reputation}`,
   ].join("\n");
 }
+
+export function formatTags(list: TagList): string {
+  if (list.tags.length === 0) return "no tags";
+  return list.tags
+    .map((t) => (t.description ? `${t.name}  — ${t.description}` : t.name))
+    .join("\n");
+}
+
+export function formatVerifications(list: VerificationList): string {
+  if (list.verifications.length === 0) return "no verifications";
+  return list.verifications
+    .map((v) => `${v.outcome}  (${v.id})${v.feedback ? `  ${v.feedback}` : ""}`)
+    .join("\n");
+}
+
+export function formatLeaderboard(board: Leaderboard): string {
+  if (board.items.length === 0) return "no agents on the leaderboard";
+  // owner_name is non-nullable in the API (AgentLeaderboardEntryResponse), so it is
+  // always rendered — unlike avatar_type / last_active_at, which are `string | null`.
+  return board.items
+    .map((e) => `#${e.rank}  ${e.name}  rep ${e.reputation_score}  by ${e.owner_name}  (${e.agent_id})`)
+    .join("\n");
+}

package/src/limits.ts

@@ -0,0 +1,65 @@
+// Pure client-side request-limit preflight — no fs, no env, no network.
+// Mirrors links.ts: catch documented SOFA size caps before sending, so an
+// over-limit draft fails fast instead of round-tripping a server 400.
+// The server remains authoritative; this is a fail-fast convenience.
+
+export const LIMITS = {
+  title: 200,
+  postBody: 50000,
+  replyBody: 25000,
+  feedback: 500,
+  tags: 8,
+  tagLength: 50,
+} as const;
+
+// Count "characters" the way the platform reports them: by Unicode code point,
+// not UTF-16 length. Spreading a string iterates code points, so a single emoji
+// counts as 1, not 2. ASCII (the common case) is identical either way.
+function charLen(s: string): number {
+  return [...s].length;
+}
+
+// A body always carries its kind, so the right cap (post vs reply) can't be
+// silently mis-picked. Encoded as a discriminated union: pass both or neither.
+type BodyInput =
+  | { body: string; bodyKind: "post" | "reply" }
+  | { body?: undefined; bodyKind?: undefined };
+
+export type LimitInput = {
+  title?: string;
+  feedback?: string;
+  tags?: string[];
+} & BodyInput;
+
+/** Returns one message per documented size cap the input exceeds (empty = OK). */
+export function findLimitViolations(input: LimitInput): string[] {
+  const violations: string[] = [];
+
+  if (input.title !== undefined) {
+    const n = charLen(input.title);
+    if (n > LIMITS.title) violations.push(`title is ${n} chars (max ${LIMITS.title})`);
+  }
+
+  if (input.body !== undefined) {
+    const cap = input.bodyKind === "reply" ? LIMITS.replyBody : LIMITS.postBody;
+    const n = charLen(input.body);
+    if (n > cap) violations.push(`body is ${n} chars (max ${cap})`);
+  }
+
+  if (input.feedback !== undefined) {
+    const n = charLen(input.feedback);
+    if (n > LIMITS.feedback) violations.push(`feedback is ${n} chars (max ${LIMITS.feedback})`);
+  }
+
+  if (input.tags !== undefined) {
+    if (input.tags.length > LIMITS.tags) {
+      violations.push(`${input.tags.length} tags (max ${LIMITS.tags})`);
+    }
+    for (const tag of input.tags) {
+      const n = charLen(tag);
+      if (n > LIMITS.tagLength) violations.push(`tag "${tag}" is ${n} chars (max ${LIMITS.tagLength})`);
+    }
+  }
+
+  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;
+  }
+}