@paxnax/berliner 0.1.0 → 0.2.0

package/dist/output.js

@@ -8,3 +8,21 @@ export function warn(msg) {
 // Same wording as the web's mergeLabel (app/src/web/format.ts).
 const MERGE = { open: "Open", merged: "Merged", closed: "Closed", none: "No PRs" };
 export const mergeLabel = (s) => s.pr_count > 1 ? `${s.merged_count} of ${s.pr_count} merged` : (MERGE[s.merge] ?? s.merge);
+// Same wording as the web's subscriptionLabel (app/src/web/format.ts): "Claude Max x20".
+const VENDOR = { anthropic: "Claude", openai: "OpenAI" };
+const PLAN = {
+    free: "Free",
+    pro: "Pro",
+    max_x5: "Max x5",
+    max_x20: "Max x20",
+    team: "Team",
+    enterprise: "Enterprise",
+    go: "Go",
+    plus: "Plus",
+    pro_more: "Pro More",
+    pro_max: "Pro Max",
+    business: "Business",
+    business_premium: "Business Premium",
+    api: "API",
+};
+export const subscriptionLabel = (s) => `${VENDOR[s.vendor] ?? s.vendor} ${PLAN[s.plan] ?? s.plan}`;

package/dist/prices.js

@@ -0,0 +1,98 @@
+import { mkdir, readFile, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cacheDir } from "./config.js";
+const SOURCE = "https://models.dev/api.json";
+const DAY_MS = 24 * 60 * 60 * 1000;
+async function fetchSource(env) {
+    // BERLINER_PRICES_FILE stands in for models.dev so tests never touch the network. Deliberately undocumented: it's a test seam, not a setting.
+    if (env.BERLINER_PRICES_FILE)
+        return JSON.parse(await readFile(env.BERLINER_PRICES_FILE, "utf8"));
+    // Well inside the hook child's 15-second deadline, so a slow models.dev never costs the report.
+    const res = await fetch(SOURCE, { signal: AbortSignal.timeout(4_000) });
+    if (!res.ok)
+        throw new Error(`${SOURCE} answered ${res.status}`);
+    return res.json();
+}
+// Resellers repeat the first-party ids, so a model's price comes from anthropic, then openai, then the first provider listing it.
+function slim(data) {
+    if (typeof data !== "object" || data === null)
+        throw new Error("unexpected price list");
+    const providers = data;
+    const order = ["anthropic", "openai", ...Object.keys(providers).filter((p) => p !== "anthropic" && p !== "openai")];
+    const prices = {};
+    for (const provider of order) {
+        for (const [id, model] of Object.entries(providers[provider]?.models ?? {})) {
+            const c = model?.cost;
+            if (Object.hasOwn(prices, id) || typeof c?.input !== "number" || typeof c.output !== "number")
+                continue;
+            // shortcut: tiered prices by context size are ignored; upgrade if estimates drift from the tools' own figures.
+            const price = { input: c.input, output: c.output };
+            if (typeof c.cache_read === "number")
+                price.cache_read = c.cache_read;
+            if (typeof c.cache_write === "number")
+                price.cache_write = c.cache_write;
+            prices[id] = price;
+        }
+    }
+    return prices;
+}
+async function readCache(file) {
+    try {
+        const [text, info] = await Promise.all([readFile(file, "utf8"), stat(file)]);
+        const prices = JSON.parse(text);
+        if (typeof prices !== "object" || prices === null || !Object.keys(prices).length)
+            return null;
+        return { prices: prices, fresh: Date.now() - info.mtimeMs < DAY_MS };
+    }
+    catch {
+        return null;
+    }
+}
+// Prices cached for a day. A failed fetch falls back to the cache at any age; null when there is neither.
+export async function loadPrices(env) {
+    const file = join(cacheDir(env), "prices.json");
+    const cached = await readCache(file);
+    if (cached?.fresh)
+        return cached.prices;
+    let prices;
+    try {
+        prices = slim(await fetchSource(env));
+        // A list without a single price is a broken answer: never cached, never used.
+        if (!Object.keys(prices).length)
+            throw new Error("no prices");
+    }
+    catch {
+        // Touched, so the calls of the next day use the stale cache instead of waiting on the source again.
+        if (cached)
+            await utimes(file, new Date(), new Date()).catch(() => { });
+        return cached?.prices ?? null;
+    }
+    // The cache only saves a download; failing to write it is not an error. Renamed into place, so a reader never sees half of it.
+    const temp = `${file}.${process.pid}`;
+    await mkdir(cacheDir(env), { recursive: true })
+        .then(() => writeFile(temp, JSON.stringify(prices)))
+        .then(() => rename(temp, file))
+        .catch(() => rm(temp, { force: true }).catch(() => { }));
+    return prices;
+}
+// A missing cache price is charged at the input price. models.dev's cache_write is the 5-minute rate; Anthropic bills 1-hour
+// cache writes at twice the input price.
+export function estimateCost(tokensByModel, prices) {
+    let costUsd = 0;
+    const unpriced = [];
+    for (const [model, t] of Object.entries(tokensByModel)) {
+        const p = Object.hasOwn(prices, model) ? prices[model] : undefined;
+        if (!p) {
+            unpriced.push(model);
+            continue;
+        }
+        costUsd +=
+            (t.input * p.input +
+                t.output * p.output +
+                t.cacheRead * (p.cache_read ?? p.input) +
+                t.cacheWrite * (p.cache_write ?? p.input) +
+                t.cacheWrite1h * 2 * p.input) /
+                1e6;
+    }
+    return { costUsd, unpriced };
+}

package/dist/setup/connect.js

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { hostname } from "node:os";
+import { CliError, request } from "../client.js";
+// The name the approval page and Settings show for this machine.
+export const machineName = () => hostname()
+    .replace(/\.local$/, "")
+    .slice(0, 64);
+// The token is made here, like Settings' tokens; the server only ever sees its hash and prefix.
+export async function startConnect(cfg, clientName) {
+    const token = `brl_${randomBytes(32).toString("base64url")}`;
+    const body = { client_name: clientName, token_hash: createHash("sha256").update(token).digest("hex"), token_prefix: token.slice(0, 11) };
+    const { json } = await request(cfg, "POST", "/v1/connect", body, { auth: false });
+    return { ...json, token };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function waitForApproval(cfg, id, interval, expiresIn) {
+    const deadline = Date.now() + expiresIn * 1000;
+    for (;;) {
+        await sleep(interval * 1000);
+        try {
+            const { json } = await request(cfg, "GET", `/v1/connect/${id}`, undefined, { auth: false, deadlineMs: 15_000 });
+            if (json.status !== "pending")
+                return json.status;
+        }
+        catch (err) {
+            // A network blip, a rate limit or a server error is no answer: the request stays pending until it expires. A 404 or
+            // another refusal ends the wait.
+            const unanswered = err instanceof CliError && (err.kind === "network" || err.status === 429 || (err.status ?? 0) >= 500);
+            if (!unanswered)
+                throw err;
+        }
+        if (Date.now() >= deadline)
+            return "expired";
+    }
+}
+// Best effort: when no browser opens, the printed URL is enough.
+export function openBrowser(url) {
+    const child = spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], { detached: true, stdio: "ignore" });
+    child.on("error", () => { }); // a missing opener is reported here, not thrown
+    child.unref();
+}

package/dist/setup/hooks.js

@@ -0,0 +1,84 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const entries = (tool, asyncStop) => {
+    const hooks = (extra = {}) => [{ type: "command", command: `berliner hook ${tool}`, ...extra }];
+    return {
+        // Claude Code runs Stop after every reply; async keeps the agent from waiting on it.
+        Stop: { hooks: hooks(asyncStop ? { async: true } : {}) },
+        PreCompact: { hooks: hooks() },
+        SessionEnd: { hooks: hooks() },
+        // Not async: what it prints is the reminder, which the tool adds to the agent's context.
+        SessionStart: { matcher: "compact|clear", hooks: hooks() },
+    };
+};
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const ours = (entry) => isObject(entry) &&
+    Array.isArray(entry.hooks) &&
+    entry.hooks.some((h) => isObject(h) && typeof h.command === "string" && h.command.startsWith("berliner hook "));
+// The file with our entries added to the events that lack one, or null when nothing is missing. "unreadable" when it
+// isn't a JSON object whose hooks we can add to: then it is the user's to fix, and is never rewritten.
+function merged(file, add) {
+    let text = null;
+    let json = {};
+    try {
+        text = readFileSync(file, "utf8");
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        if (text !== null || err.code !== "ENOENT")
+            return "unreadable";
+    }
+    if (!isObject(json))
+        return "unreadable";
+    const hooks = json.hooks ?? {};
+    if (!isObject(hooks))
+        return "unreadable";
+    let changed = false;
+    for (const [event, entry] of Object.entries(add)) {
+        const list = hooks[event] ?? [];
+        if (!Array.isArray(list))
+            return "unreadable";
+        if (list.some(ours))
+            continue;
+        hooks[event] = [...list, entry];
+        changed = true;
+    }
+    if (!changed)
+        return null;
+    const indent = text?.match(/^[ \t]+(?=\S)/m)?.[0] ?? "  ";
+    return `${JSON.stringify({ ...json, hooks }, null, indent)}\n`;
+}
+function install(file, add) {
+    const text = merged(file, add);
+    if (text === "unreadable")
+        return text;
+    if (text === null)
+        return "present";
+    mkdirSync(dirname(file), { recursive: true });
+    // In place, so a settings file that is a symlink stays one.
+    writeFileSync(file, text);
+    return "added";
+}
+const describe = (text) => (text === "unreadable" ? "can't be read, left unchanged" : text === null ? "already installed" : "adds a hook");
+export const installClaudeHooks = (settingsPath) => install(settingsPath, entries("claude-code", true));
+export const describeClaudeHooks = (settingsPath) => describe(merged(settingsPath, entries("claude-code", true)));
+export const installCodexHooks = (hooksPath) => install(hooksPath, entries("codex", false));
+export const describeCodexHooks = (hooksPath) => describe(merged(hooksPath, entries("codex", false)));
+// dist/setup/hooks.js -> ../../opencode/berliner.js (the package's opencode/ directory).
+const plugin = () => readFileSync(new URL("../../opencode/berliner.js", import.meta.url), "utf8");
+const current = (pluginPath) => {
+    try {
+        return readFileSync(pluginPath, "utf8") === plugin();
+    }
+    catch {
+        return false;
+    }
+};
+export function installOpenCodePlugin(pluginPath) {
+    if (current(pluginPath))
+        return "present";
+    mkdirSync(dirname(pluginPath), { recursive: true });
+    writeFileSync(pluginPath, plugin());
+    return "added";
+}
+export const describeOpenCodePlugin = (pluginPath) => (current(pluginPath) ? "already installed" : "adds a hook");

package/dist/setup/targets.js

@@ -0,0 +1,41 @@
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const claudeDir = (env) => env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+export const codexDir = (env) => env.CODEX_HOME || join(homedir(), ".codex");
+export const opencodeDir = (env) => join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode");
+// The spec's table (docs/superpowers/specs/2026-10-20-onboarding-design.md, "Where each tool looks for skills").
+const TOOLS = [
+    { id: "claude-code", name: "Claude Code", bin: "claude", dir: claudeDir },
+    { id: "codex", name: "Codex", bin: "codex", dir: codexDir },
+    { id: "opencode", name: "OpenCode", bin: "opencode", dir: opencodeDir },
+];
+function isExecutable(file) {
+    try {
+        accessSync(file, constants.X_OK);
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export const onPath = (bin, env) => (env.PATH ?? "").split(":").some((dir) => dir !== "" && isExecutable(join(dir, bin)));
+export function detectTools(env) {
+    return TOOLS.map((t) => ({ id: t.id, name: t.name, found: onPath(t.bin, env) || existsSync(t.dir(env)) }));
+}
+const skillFile = (dir) => join(dir, "skills", "berliner", "SKILL.md");
+// One target per tool found. OpenCode reads ~/.claude/skills and ~/.agents/skills too, so it gets its own copy only when neither is written.
+export function skillTargets(tools, env) {
+    const found = (id) => tools.some((t) => t.id === id && t.found);
+    const targets = [];
+    if (found("claude-code"))
+        targets.push({ tool: "claude-code", path: skillFile(claudeDir(env)) });
+    if (found("codex"))
+        targets.push({ tool: "codex", path: skillFile(join(homedir(), ".agents")) });
+    if (found("opencode")) {
+        const read = [".claude", ".agents"].map((d) => skillFile(join(homedir(), d)));
+        const covering = targets.find((t) => read.includes(t.path));
+        targets.push({ tool: "opencode", path: covering?.path ?? skillFile(opencodeDir(env)) });
+    }
+    return targets.map((t) => ({ ...t, exists: existsSync(t.path) }));
+}

package/opencode/berliner.js

@@ -0,0 +1,124 @@
+// Berliner's OpenCode plugin, installed by `berliner setup` to ${XDG_CONFIG_HOME:-~/.config}/opencode/plugins/berliner.js.
+// It reports each top-level session to Berliner through `berliner hook opencode`, and must never throw into OpenCode or make it wait.
+//
+// Checked against OpenCode 1.18.30 (https://opencode.ai/docs/plugins/ and @opencode-ai/plugin 1.18.30's Hooks type):
+// - a plugin is an exported async function of { client, directory, ... } that returns its hooks;
+// - `event` receives every bus event; session.idle carries properties.sessionID;
+// - `shell.env` runs before the agent's shell tool (with sessionID) and before user terminals (without one);
+// - `experimental.session.compacting` runs before every compaction, manual (/compact) and automatic alike, and adds
+//   output.context to the summary prompt;
+// - client.session.get({ path: { id } }) returns { data } with the server's Session, which holds cost, tokens and model,
+//   so the messages are not needed;
+// - subagents run in child sessions (parentID set), each with its own cost and tokens, and
+//   client.session.children({ path: { id } }) returns { data } with a session's direct children.
+import { spawn } from "node:child_process";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const REMINDER = "This session reports to Berliner: run `berliner report` with the task and PRs before your final message.";
+// The id names a file, so only the characters OpenCode's own ids use.
+const SAFE_ID = /^[\w-]+$/;
+// Bounds a walk up or down the session tree, which subagents keep shallow.
+const MAX_DEPTH = 10;
+
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+const get = async (client, id) => (await client.session.get({ path: { id } }))?.data;
+
+// One agent session is one Berliner session: a subagent's child session belongs to the top-level session above it.
+async function topLevelId(client, id) {
+  let session = await get(client, id);
+  for (let i = 0; session?.parentID && i < MAX_DEPTH; i++) session = await get(client, session.parentID);
+  return session && !session.parentID ? session.id : null;
+}
+
+// The session with its subagents' cost and tokens added in, in the shape the CLI reads. OpenCode 1.18.30 keeps them apart:
+// a session's cost and tokens grow only from its own step-finish parts (packages/core/src/session/projector.ts:310-326,
+// applyUsage on the part's own sessionID, lines 89-109), and a live run with one task-tool subagent gave the parent 0.215
+// and the child 1.05.
+async function withChildren(client, session, depth = 0) {
+  const children = depth < MAX_DEPTH ? (await client.session.children({ path: { id: session.id } }))?.data : null;
+  if (!Array.isArray(children) || children.length === 0) return session;
+  const t = session.tokens;
+  let cost = num(session.cost);
+  const tokens = {
+    input: num(t?.input),
+    output: num(t?.output),
+    reasoning: num(t?.reasoning),
+    cache: { read: num(t?.cache?.read), write: num(t?.cache?.write) },
+  };
+  for (const c of await Promise.all(children.map((child) => withChildren(client, child, depth + 1)))) {
+    cost += num(c.cost);
+    tokens.input += num(c.tokens?.input);
+    tokens.output += num(c.tokens?.output);
+    tokens.reasoning += num(c.tokens?.reasoning);
+    tokens.cache.read += num(c.tokens?.cache?.read);
+    tokens.cache.write += num(c.tokens?.cache?.write);
+  }
+  return { ...session, cost, tokens };
+}
+
+// Saves a top-level session with its subagents' totals where `berliner report` run by the agent finds them: its shell can't
+// reach this client. Returns what it saved, or null for a child session, which the top-level session's totals count.
+async function save(client, sessionID) {
+  if (typeof sessionID !== "string" || !SAFE_ID.test(sessionID)) return null;
+  const found = await get(client, sessionID);
+  if (found?.id !== sessionID || found.parentID) return null;
+  // OpenCode moves time.updated only when a prompt arrives, so the session's last activity is now.
+  const session = { ...(await withChildren(client, found)), time: { ...found.time, updated: Date.now() } };
+  const dir = join(process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "berliner", "opencode");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = join(dir, `${sessionID}.json`);
+  // Renamed into place, so a reader never sees half of it.
+  writeFileSync(`${file}.${process.pid}`, JSON.stringify(session));
+  renameSync(`${file}.${process.pid}`, file);
+  return session;
+}
+
+async function report(client, event, sessionID) {
+  try {
+    const session = await save(client, sessionID);
+    if (!session) return;
+    // Detached and unreferenced: OpenCode never waits on it.
+    const child = spawn("berliner", ["hook", "opencode"], { detached: true, stdio: ["pipe", "ignore", "ignore"] });
+    child.on("error", () => {});
+    child.stdin.on("error", () => {});
+    child.stdin.end(JSON.stringify({ event, session }));
+    child.unref();
+  } catch {
+    // A report that can't be sent is skipped; the next idle sends the latest totals.
+  }
+}
+
+export const BerlinerPlugin = async ({ client }) => ({
+  "shell.env": async (input, output) => {
+    try {
+      if (!input?.sessionID) return;
+      output.env.OPENCODE_SESSION_ID = input.sessionID;
+      // A subagent's shell gets the top-level session, so a `berliner report` the agent runs there doesn't split it off.
+      const top = await topLevelId(client, input.sessionID);
+      if (!top) return;
+      output.env.OPENCODE_SESSION_ID = top;
+      // So that report finds the totals before the session's first idle. Not reported from here: that waits for idle.
+      await save(client, top);
+    } catch {
+      // Never fail the agent's shell.
+    }
+  },
+  event: async (input) => {
+    try {
+      if (input?.event?.type === "session.idle") void report(client, "idle", input.event.properties?.sessionID);
+    } catch {
+      // Never fail OpenCode's event bus.
+    }
+  },
+  "experimental.session.compacting": async (input, output) => {
+    try {
+      // The summary carries it, so the agent still reports the task and PRs after compaction.
+      output.context.push(REMINDER);
+    } catch {
+      // Never fail the compaction.
+    }
+    void report(client, "compacting", input?.sessionID);
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paxnax/berliner",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Report coding-agent sessions to Berliner",
   "type": "module",
   "engines": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "opencode",
     "skill"
   ],
   "scripts": {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: berliner
-description: Use at the end of an autonomous coding session, and again whenever its PRs or results change, to report cost, model, plan, PRs, commits, test coverage and screenshots or videos to Berliner with the berliner CLI.
+description: Use when you commit, open or update a pull request, or finish a task, and whenever the user asks you to report to Berliner. Reports the task, pull requests, test coverage and screenshots or videos with the berliner CLI.
 ---
 
 # Reporting to Berliner
@@ -9,10 +9,29 @@ Berliner records what an autonomous session cost and produced. You report with o
 
 ## When to report
 
-- Once, at the end of the session.
-- Again with the **same `--session-id`** if anything changes afterwards (a PR is opened or merged, CI finishes, you add evidence). The new values replace the old ones, PR URLs are added to the list, and evidence already uploaded is skipped. It never double-counts.
+- Before your final message, whenever you committed, opened or updated a pull request, or finished a task.
+- Again whenever a PR changes (opened, merged, CI finishes) or you add evidence.
+- Right away when the user asks you to report to Berliner.
 
-## Required values and where each comes from
+Reporting again is safe. The new values replace the old ones, PR URLs are added to the list, and evidence already uploaded is skipped. It never double-counts.
+
+## Inside Claude Code, Codex or OpenCode
+
+Hooks installed by `berliner setup` already report the session's cost, model, repository and commits after every reply. Send only what you know and the hooks don't:
+
+| Flag | What to send |
+|---|---|
+| `--title` | A short line naming the task. |
+| `--task`, `--task-url` | The ticket ID and its URL, if there is one. |
+| `--pr` | Every pull request, one flag each. |
+| `--coverage` | Percent, from the test run's coverage summary. |
+| `--evidence` | Each screenshot or video. |
+
+Do not pass `--session-id`, `--cost` or `--model`: the CLI fills them in from the tool's own records, and an explicit value is ignored with a warning. `--repo` and `--plan` are not needed either: the plan comes from the user's `BERLINER_PLAN`, or from their subscriptions in Settings. A report without `--title` keeps the session's existing title. `berliner update` ignores a session ID here.
+
+## Outside those tools
+
+Without a hook, `report` needs these flags:
 
 | Flag | Source |
 |---|---|
@@ -21,11 +40,13 @@ Berliner records what an autonomous session cost and produced. You report with o
 | `--repo` | `owner/name`, from `git remote get-url origin`. |
 | `--cost` | Estimated USD. Your harness's reported session cost if it shows one, otherwise estimate from token usage at the model's API prices. |
 | `--model` | The primary model ID you ran on. |
-| `--plan` | One of `free`, `pro`, `max_x5`, `max_x20`, `team`, `enterprise`, `api`. |
+| `--plan` | Your best guess at the plan you run on. Claude: `free`, `pro`, `max_x5`, `max_x20`, `team`, `enterprise`. OpenAI (Codex): `free`, `go`, `plus`, `pro`, `pro_more`, `pro_max`, `business`, `business_premium`. Billed per token: `api`. Always pass it: when the user has set `BERLINER_PLAN`, that value replaces yours. |
+
+Report again with the same `--session-id` whenever something changes.
 
 ## Optional values
 
-- `--commits <n>`: `git rev-list --count <base>..HEAD`
+- `--commits <n>` (outside the tools; the hooks count them): `git rev-list --count <base>..HEAD`
 - `--coverage <percent>`: from the test run's coverage summary.
 - `--pr <url>[,merge=<open|merged|closed>][,ci=<pending|running|passed|failed|none>]`: repeat per PR. URL from `gh pr view --json url`.
 - `--evidence <path>[::caption]`: repeat per screenshot or video.
@@ -35,7 +56,9 @@ Quote any value that contains spaces.
 
 ## Environment
 
-`BERLINER_TOKEN` must be set (an API token from the Settings page at https://berliner.app). `BERLINER_URL` overrides the server address.
+`berliner setup` stores the API token in a config file, so `BERLINER_TOKEN` is only needed to override it (a token from the Settings page at https://berliner.app). `BERLINER_URL` overrides the server address. `BERLINER_PLAN`, when the user sets it, replaces any `--plan`.
+
+If the `berliner` command is not found, ask the user to run `npx @paxnax/berliner@latest setup`. Do not try to install it yourself.
 
 ## Timeouts
 
@@ -46,9 +69,23 @@ The session is saved first, then evidence is uploaded. Allow at least 10 minutes
 - Success prints what was saved, then an evidence line such as `Evidence: 1 uploaded, 0 already uploaded, 0 skipped.`
 - A line starting `berliner:` on stderr is a warning: the report may be incomplete (server unreachable, a file skipped). The command still exits 0, so it never fails your work (`--strict` makes failures exit 1). Re-run the same command; it is safe to repeat.
 - `--json` prints the saved session as JSON, plus an `evidence` field with `uploaded`, `existing` and `skipped` results when `--evidence` was given.
-- To change a field later without resending everything, use `berliner update <session-id> --commits 5`.
+- To change a field later without resending everything, use `berliner update --commits 5` inside the tools, or `berliner update <session-id> --commits 5` outside them.
+
+## Examples
+
+Inside Claude Code, Codex or OpenCode:
+
+```sh
+berliner report \
+  --title "Fix recurring event off-by-one" \
+  --task TEC-5521 \
+  --task-url https://linear.app/octo/issue/TEC-5521 \
+  --coverage 87.5 \
+  --pr "https://github.com/octo/app/pull/42,ci=running" \
+  --evidence "./shots/after.png::Calendar after the fix"
+```
 
-## Example
+Anywhere else:
 
 ```sh
 berliner report \