@paxnax/berliner 0.2.1 → 0.4.0

package/README.md

@@ -21,7 +21,7 @@ With Bun, run `bunx --bun @paxnax/berliner@latest setup`. To install only the co
    npx @paxnax/berliner@latest setup
    ```
 
-   It shows what it will do and asks once, then opens your browser so you can approve the connection. After you approve, it saves the token, installs the CLI globally, and installs the agent skill and a reporting hook for each of Claude Code, Codex and OpenCode that it finds. `--yes` skips the question, `--no-install` skips the global install, and `--no-browser` only prints the URL (over SSH, for example). Run `berliner setup` again to update the skill.
+   It shows what it will do and asks once, then opens your browser so you can approve the connection. After you approve, it saves the token, installs the CLI globally, and installs the agent skill and a reporting hook for each of Claude Code, Codex and OpenCode that it finds. `--yes` skips the question, `--no-install` skips the global install, and `--no-browser` only prints the URL (over SSH, for example). Run `berliner upgrade` to update the CLI and the skill to the latest release: it shows its plan and asks first, and a second question (or `--no-skill`) keeps your skill as it is.
 
 3. From then on, the hooks report each session's cost, model, repository, commits and start and end times after every reply. Your agent adds the task, pull requests, coverage and evidence with `berliner report`, as the skill tells it to. Codex runs a new hook only once you trust it: open `codex` once in a terminal and trust the Berliner hook.
 4. On **Settings**, list the subscriptions you pay for. Overview then compares each one with the sessions that ran on it.
@@ -104,6 +104,8 @@ berliner report \
 
 Reporting again with the same `--session-id` replaces the values, adds PR URLs and skips evidence already uploaded. `--plan` is required unless `BERLINER_PLAN` is set.
 
+Evidence is private: only you can see it, signed in. Add `--public` to also make each `--evidence` file, new or already uploaded, viewable by anyone with its link. The report then prints one line per file to paste into a pull request body: a Markdown image (`![caption](https://berliner.app/v1/public/evidence/<id>)`), or the bare URL for a video, which GitHub does not embed from other hosts. With `--json` they are in `evidence.published`. Browsers and GitHub may keep a copy of a public file for up to 5 minutes after you make it private again.
+
 Inside Claude Code, Codex or OpenCode, leave out `--session-id`, `--repo`, `--cost`, `--model` and `--plan`. The CLI fills in the session id, cost and model from the tool's own records and the repository from git, and ignores an explicit `--session-id`, `--cost` or `--model` with one warning. The plan comes from `BERLINER_PLAN` or your subscriptions, as above. A report there without `--title` keeps the existing title; a new session takes the first line of your first prompt, cut to 80 characters.
 
 Other commands:
@@ -114,7 +116,9 @@ Other commands:
 - `berliner session <session-id>`: show one session.
 - `berliner summary [filters]`: totals for the same filters as `sessions`, then one line per subscription.
 - `berliner delete <session-id>`: delete a session, or one item with `--evidence <id>`. Asks to confirm unless `--yes`.
+- `berliner evidence public <id>`: let anyone with the link view one file, and print its public URL and Markdown line. `berliner evidence private <id>` makes it private again. `berliner session` shows the ids, and the URL of each public file.
 - `berliner skill`: print the agent skill (`SKILL.md`) to install in your agent.
+- `berliner upgrade [--yes] [--no-skill]`: install the latest CLI and skill. It shows its plan (the versions, the exact install command and each skill file) and asks before changing anything; a second question, or `--no-skill`, leaves your skill as it is. Your token, config and hooks are never touched.
 - `berliner hook <tool>`: run by the hooks setup installs, with the tool's payload on stdin. It never prints, never fails and never makes the agent wait; errors go to `${XDG_STATE_HOME:-~/.local/state}/berliner/hook.log`.
 
 `report` and `update` exit 0 even when something fails, printing a warning that starts with `berliner:` to stderr, so reporting never breaks an agent's pipeline. Pass `--strict` to make them exit 1 on failure. The other commands exit 1 on failure.

package/dist/args.js

@@ -16,12 +16,14 @@ const config = {
         coverage: { type: "string" },
         pr: { type: "string", multiple: true },
         evidence: { type: "string", multiple: true },
+        public: { type: "boolean" },
         json: { type: "boolean" },
         strict: { type: "boolean" },
         help: { type: "boolean" },
         yes: { type: "boolean" },
         "no-install": { type: "boolean" },
         "no-browser": { type: "boolean" },
+        "no-skill": { type: "boolean" },
         run: { type: "string" },
         ci: { type: "string" },
         merge: { type: "string" },

package/dist/client.js

@@ -9,6 +9,7 @@ export class CliError extends Error {
         this.details = details;
     }
 }
+export const absolute = (cfg, path) => cfg.url.replace(/\/+$/, "") + path;
 export async function request(cfg, method, path, body, opts = {}) {
     const { timeoutMs = 10_000, retries = 3, deadlineMs = 15_000, auth = true } = opts;
     if (auth && !cfg.token)
@@ -22,7 +23,7 @@ export async function request(cfg, method, path, body, opts = {}) {
         const canRetry = () => attempt < retries && Date.now() + backoffMs < deadline;
         let res;
         try {
-            res = await fetch(cfg.url.replace(/\/+$/, "") + path, {
+            res = await fetch(absolute(cfg, path), {
                 method,
                 headers: {
                     ...(auth ? { Authorization: `Bearer ${cfg.token}` } : {}),

package/dist/commands/delete.js

@@ -8,7 +8,7 @@ export async function del(cfg, values, positionals) {
     if (evidenceId) {
         // Evidence ids are global, so the session named on the command line must actually hold this one.
         const { json } = await request(cfg, "GET", `/v1/sessions/${encodeURIComponent(id)}`);
-        if (!json.session.evidence.some((e) => String(e.id) === evidenceId)) {
+        if (!json.session.evidence.some((e) => e.id === evidenceId)) {
             throw new CliError(`evidence ${evidenceId} is not part of session ${id}`, "usage");
         }
     }

package/dist/commands/evidence.js

@@ -0,0 +1,14 @@
+import { absolute, CliError, request } from "../client.js";
+import { embed, print } from "../output.js";
+export async function evidence(cfg, values, positionals) {
+    const [action, id] = positionals;
+    if (positionals.length !== 2 || (action !== "public" && action !== "private")) {
+        throw new CliError("usage: berliner evidence public|private <id> [--json]", "usage");
+    }
+    const { json } = await request(cfg, "PATCH", `/v1/evidence/${encodeURIComponent(id)}`, { public: action === "public" });
+    const e = json.evidence;
+    const url = e.public_url && absolute(cfg, e.public_url);
+    const markdown = url && embed(e, url);
+    const text = !url ? `Evidence ${e.id} is private.` : markdown === url ? url : `${url}\n${markdown}`;
+    print({ data: json, text }, values.json === true);
+}

package/dist/commands/report.js

@@ -17,6 +17,8 @@ export async function report(cfg, values, positionals, env) {
     const missing = required.filter((flag) => values[flag] === undefined && !(flag === "plan" && cfg.plan) && !(tool && (flag === "plan" || flag === "cost")));
     if (missing.length)
         throw new CliError(`missing required flag(s): ${missing.map((f) => `--${f}`).join(", ")}`, "usage");
+    if (values.public && !values.evidence?.length)
+        throw new CliError("--public needs --evidence", "usage");
     const body = { ...sessionBody(values), plan: cfg.plan ?? values.plan };
     const id = values["session-id"];
     const path = `/v1/sessions/${encodeURIComponent(id)}`;
@@ -37,11 +39,14 @@ export async function report(cfg, values, positionals, env) {
             print({ data: json, text }, true);
         return;
     }
-    const result = await uploadEvidence(cfg, id, values.evidence.map(parseEvidence));
+    const result = await uploadEvidence(cfg, id, values.evidence.map(parseEvidence), undefined, values.public === true);
     if (json_)
         print({ data: { ...json, evidence: result }, text }, true);
-    else
+    else {
         console.log(`Evidence: ${result.uploaded} uploaded, ${result.existing} already uploaded, ${result.skipped.length} skipped.`);
+        for (const p of result.published ?? [])
+            console.log(p.markdown);
+    }
     for (const s of result.skipped)
         warn(`${s.path}: ${s.reason}`);
 }

package/dist/commands/session.js

@@ -1,4 +1,4 @@
-import { CliError, request } from "../client.js";
+import { absolute, CliError, request } from "../client.js";
 import { mergeLabel, print } from "../output.js";
 export async function session(cfg, values, positionals) {
     if (positionals.length !== 1)
@@ -28,6 +28,6 @@ export async function session(cfg, values, positionals) {
         lines.push(`  ${p.url}  merge=${p.merge_state} ci=${p.ci_state}${p.tracked ? "" : " (not tracked)"}`);
     lines.push(`Evidence: ${s.evidence.length || "none"}`);
     for (const e of s.evidence)
-        lines.push(`  #${e.id} ${e.kind} ${e.filename}${e.caption ? ` - ${e.caption}` : ""}${e.status === "ready" ? "" : ` (${e.status})`}`);
+        lines.push(`  ${e.id} ${e.kind} ${e.filename}${e.caption ? ` - ${e.caption}` : ""}${e.status === "ready" ? "" : ` (${e.status})`}${e.public_url ? ` public ${absolute(cfg, e.public_url)}` : ""}`);
     print({ data: json, text: lines.join("\n") }, values.json === true);
 }

package/dist/commands/setup.js

@@ -10,17 +10,23 @@ import { describeClaudeHooks, describeCodexHooks, describeOpenCodePlugin, instal
 import { claudeDir, codexDir, detectTools, onPath, opencodeDir, skillTargets } from "../setup/targets.js";
 // The same command the web guide shows.
 const TEST_REPORT = 'berliner report --session-id try-1 --title "First report" --repo you/app --cost 0.10 --model test --plan pro';
-const tilde = (p) => (p.startsWith(`${homedir()}/`) ? `~${p.slice(homedir().length)}` : p);
-export async function confirm(input, output) {
+export const tilde = (p) => (p.startsWith(`${homedir()}/`) ? `~${p.slice(homedir().length)}` : p);
+export async function confirm(input, output, question = "Continue? [Y/n] ") {
     const rl = createInterface({ input, output });
     // Ctrl+C and Ctrl+D reject the question without ending the line; both mean no.
-    const answer = await rl.question("Continue? [Y/n] ").catch(() => {
+    const answer = await rl.question(question).catch(() => {
         output.write("\n");
         return "n";
     });
     rl.close();
     return /^(y|yes)?$/i.test(answer.trim());
 }
+// Pinned to one version, so the command shown is the one run.
+export const installCommand = (version) => [...(process.versions.bun ? ["bun", "add", "-g"] : ["npm", "install", "-g"]), `@paxnax/berliner@${version}`];
+export function showPlan(title, steps) {
+    const plan = steps.flatMap((s, i) => [`  ${i + 1}. ${s.label}`, ...s.detail.map((d) => `       ${d}`)]);
+    console.log(["", title, "", "This will:", ...plan, ""].join("\n"));
+}
 // The login of the saved token, or null when there is none or the server no longer accepts it.
 async function savedLogin(url, token) {
     if (!token)
@@ -47,7 +53,7 @@ export async function setup(env, values) {
     };
     const hooks = tools.filter((t) => t.found).map((t) => ({ ...t, ...hookFiles[t.id] }));
     const version = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
-    const install = [...(process.versions.bun ? ["bun", "add", "-g"] : ["npm", "install", "-g"]), `@paxnax/berliner@${version}`];
+    const install = installCommand(version);
     // The plan is data, built and shown before anything changes.
     const steps = [
         ...(login
@@ -78,8 +84,7 @@ export async function setup(env, values) {
             }),
         },
     ];
-    const plan = steps.flatMap((s, i) => [`  ${i + 1}. ${s.label}`, ...s.detail.map((d) => `       ${d}`)]);
-    console.log(["", "Berliner setup", "", "This will:", ...plan, ""].join("\n"));
+    showPlan("Berliner setup", steps);
     if (!values.yes) {
         if (!process.stdin.isTTY)
             throw new CliError("There is no terminal to ask on. Run setup again with --yes to continue without asking.", "usage");

package/dist/commands/update.js

@@ -10,6 +10,8 @@ export async function update(cfg, values, positionals, env) {
     }
     if (values.evidence?.length)
         throw new CliError("update does not upload evidence; use report --evidence", "usage");
+    if (values.public)
+        throw new CliError("update does not publish evidence; use report --evidence --public, or berliner evidence public <id>", "usage");
     if (tool)
         values = await fromTool(tool, { ...values, "session-id": positionals[0] ?? values["session-id"] }, env, "update");
     const id = tool ? tool.sessionId : positionals[0];

package/dist/commands/upgrade.js

@@ -0,0 +1,116 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { CliError } from "../client.js";
+import { detectTools, skillTargets } from "../setup/targets.js";
+import { confirm, installCommand, showPlan, tilde } from "./setup.js";
+async function latestVersion(env) {
+    const registry = (env.npm_config_registry || "https://registry.npmjs.org").replace(/\/+$/, "");
+    try {
+        const res = await fetch(`${registry}/@paxnax/berliner/latest`);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const { version } = (await res.json());
+        if (typeof version !== "string")
+            throw new Error("no version in the reply");
+        return version;
+    }
+    catch (err) {
+        throw new CliError(`Could not look up the latest berliner on ${registry} (${err.message}). Nothing was changed.`, "network");
+    }
+}
+// The skill text comes from the release being installed, so the plan's "already up to date" and what is written match it.
+function skillOf(version, bundled) {
+    if (bundled)
+        return readFileSync(new URL("../../skill/SKILL.md", import.meta.url), "utf8");
+    // --bun keeps the CLI on Bun: its shebang prefers node when both exist.
+    const [cmd, ...pre] = process.versions.bun ? ["bunx", "--bun"] : ["npx", "--yes"];
+    const run = spawnSync(cmd, [...pre, `@paxnax/berliner@${version}`, "skill"], { encoding: "utf8" });
+    if (run.status !== 0 || !run.stdout)
+        throw new CliError(`Could not read the skill of berliner ${version} (${(run.error?.message ?? run.stderr).trim() || `exited with ${run.status}`}). Nothing was changed.`, "network");
+    return run.stdout;
+}
+// Release versions only (x.y.z): the registry's latest tag never points at a prerelease.
+const newer = (a, b) => {
+    const [x, y] = [a, b].map((v) => v.split("-")[0].split(".").map(Number));
+    const i = x.findIndex((n, j) => n !== y[j]);
+    return i >= 0 && x[i] > y[i];
+};
+const sameAs = (path, text) => {
+    try {
+        return readFileSync(path, "utf8") === text;
+    }
+    catch {
+        return false;
+    }
+};
+// Only the command and the skill: the token, config and hooks are setup's, and stay as they are.
+export async function upgrade(env, values) {
+    const current = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+    const latest = await latestVersion(env);
+    // A CLI ahead of the registry (a local build, a release still propagating) is never taken backwards, nor is its skill.
+    const installing = newer(latest, current);
+    const target = installing ? latest : current;
+    const install = installCommand(latest);
+    const tools = detectTools(env);
+    const targets = values["no-skill"] ? [] : skillTargets(tools, env);
+    const skill = targets.length ? skillOf(target, !installing) : "";
+    let stale = targets.filter((t) => !sameAs(t.path, skill));
+    if (!installing && !stale.length) {
+        console.log(`Already up to date. berliner ${current} is ${current === latest ? "the latest release" : `newer than the latest release (${latest})`}.`);
+        return;
+    }
+    showPlan("Berliner upgrade", [
+        {
+            label: installing
+                ? `Upgrade the berliner command from ${current} to ${latest}:  ${install.join(" ")}`
+                : current === latest
+                    ? `berliner ${current} is already the latest, nothing to install`
+                    : `berliner ${current} is newer than the latest release (${latest}), nothing to install`,
+            detail: [],
+        },
+        values["no-skill"]
+            ? { label: "Leave the Berliner skill as it is (--no-skill)", detail: [] }
+            : {
+                label: `Upgrade the Berliner skill to ${target} for:`,
+                detail: tools.map((tool) => {
+                    const target = targets.find((t) => t.tool === tool.id);
+                    const where = target ? `${tilde(target.path)}${stale.includes(target) ? "" : " (already up to date)"}` : "not found, skipped";
+                    return `${tool.name.padEnd(14)}${where}`;
+                }),
+            },
+    ]);
+    if (!values.yes) {
+        if (!process.stdin.isTTY)
+            throw new CliError("There is no terminal to ask on. Run upgrade again with --yes to continue without asking.", "usage");
+        if (!(await confirm(process.stdin, process.stdout)))
+            throw new CliError("Cancelled. Nothing was changed.", "usage");
+        // Without an install, the skill is all Continue covered.
+        if (installing && stale.length && !(await confirm(process.stdin, process.stdout, "Upgrade the skill too? [Y/n] ")))
+            stale = [];
+        console.log();
+    }
+    if (installing) {
+        const run = spawnSync(install[0], install.slice(1), { encoding: "utf8" });
+        if (run.status !== 0) {
+            console.error(`✗ Could not install the berliner command:\n${(run.error?.message ?? run.stdout + run.stderr).trimEnd()}`);
+            throw new CliError(`The skill was left as it is. Install the command yourself, then run upgrade again:  ${install.join(" ")}`, "usage");
+        }
+        console.log(`✓ Installed berliner ${latest}`);
+    }
+    // A file that can't be written (read-only, say) is reported and skipped, so the other tools still get theirs.
+    let unwritten = false;
+    for (const t of stale) {
+        const what = `${tools.find((tool) => tool.id === t.tool).name} skill`;
+        try {
+            mkdirSync(dirname(t.path), { recursive: true });
+            writeFileSync(t.path, skill);
+            console.log(`✓ ${what}: ${tilde(t.path)}`);
+        }
+        catch (err) {
+            unwritten = true;
+            console.error(`✗ ${what}: ${tilde(t.path)} can't be written (${err.message.split(",")[0]})`);
+        }
+    }
+    console.log(unwritten ? "\nSome files can't be written. Fix the ones marked ✗ above, then run upgrade again." : "\nDone.");
+}

package/dist/index.js

@@ -3,6 +3,7 @@
 import { parse } from "./args.js";
 import { CliError } from "./client.js";
 import { del } from "./commands/delete.js";
+import { evidence } from "./commands/evidence.js";
 import { hook } from "./commands/hook.js";
 import { report } from "./commands/report.js";
 import { session } from "./commands/session.js";
@@ -11,6 +12,7 @@ import { setup } from "./commands/setup.js";
 import { skill } from "./commands/skill.js";
 import { summary } from "./commands/summary.js";
 import { update } from "./commands/update.js";
+import { upgrade } from "./commands/upgrade.js";
 import { readConfig } from "./config.js";
 import { warn } from "./output.js";
 const usage = `Usage: berliner <command> [flags]
@@ -19,7 +21,7 @@ Commands:
   setup                 connect this terminal, install the CLI and skill [--yes --no-install --no-browser]
   report --session-id <id> --title <t> --repo <owner/name> --cost <usd> --model <m> --plan <p>
          [--task --task-url --project --started-at --ended-at --commits --coverage]
-         [--pr <url>[,merge=<state>][,ci=<state>]]... [--evidence <path>[::caption]]... [--json] [--strict]
+         [--pr <url>[,merge=<state>][,ci=<state>]]... [--evidence <path>[::caption]]... [--public] [--json] [--strict]
          inside Claude Code, Codex or OpenCode the session id, cost, model and repo are filled in,
          and the server picks the plan (BERLINER_PLAN overrides it)
   update <session-id>   same flags as report, all optional (no session id inside those tools)
@@ -27,6 +29,9 @@ Commands:
   session <session-id>  [--json]
   summary               same filters as sessions [--json]
   delete <session-id>   [--evidence <id>] [--yes]
+  evidence public <id>  let anyone with the link view one file; prints its URL and Markdown [--json]
+  evidence private <id> make it viewable only by you again [--json]
+  upgrade               install the latest CLI and skill [--yes --no-skill]
   skill                 print the bundled SKILL.md
   hook <tool>           run by the hooks of claude-code, codex or opencode; reads the payload on stdin
 
@@ -34,7 +39,7 @@ Environment: BERLINER_TOKEN, BERLINER_URL, BERLINER_PLAN (replaces --plan)`;
 const args = parse(process.argv.slice(2));
 // Reporting must never fail the agent's own pipeline unless it asks to (anti-goal 1).
 const softFail = (args.command === "report" || args.command === "update") && !args.values.strict;
-const handled = new Set(["setup", "report", "update", "sessions", "session", "summary", "delete", "skill", "hook"]);
+const handled = new Set(["setup", "report", "update", "sessions", "session", "summary", "delete", "evidence", "skill", "hook", "upgrade"]);
 const cfg = () => readConfig(process.env);
 try {
     if (args.values.help)
@@ -58,8 +63,12 @@ try {
         await summary(cfg(), args.values);
     else if (args.command === "delete")
         await del(cfg(), args.values, args.positionals);
+    else if (args.command === "evidence")
+        await evidence(cfg(), args.values, args.positionals);
     else if (args.command === "skill")
         skill();
+    else if (args.command === "upgrade")
+        await upgrade(process.env, args.values);
     else
         throw new CliError(args.command ? `unknown command "${args.command}"` : "missing command", "usage");
 }

package/dist/output.js

@@ -5,6 +5,8 @@ export function print(result, json) {
 export function warn(msg) {
     console.error(`berliner: ${msg.replace(/\s*\n\s*/g, " ")}`);
 }
+// GitHub renders an image from Markdown but not a video from another host, so a video is its bare URL.
+export const embed = (e, url) => e.kind === "video" ? url : `![${(e.caption || e.filename).replace(/[[\]]/g, "\\$&")}](${url})`;
 // 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);

package/dist/upload.js

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { open, stat } from "node:fs/promises";
 import path from "node:path";
-import { CliError, request } from "./client.js";
+import { absolute, CliError, request } from "./client.js";
+import { embed } from "./output.js";
 const TYPES = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -15,23 +16,37 @@ const TYPES = {
 };
 // Evidence uploads are exempt from the 15 s report deadline (ruling R25).
 const LONG = { timeoutMs: 120_000, deadlineMs: 120_000 };
-export async function uploadEvidence(cfg, sessionId, files, budget = LONG) {
-    const result = { uploaded: 0, existing: 0, skipped: [] };
+export async function uploadEvidence(cfg, sessionId, files, budget = LONG, publish = false) {
+    const result = { uploaded: 0, existing: 0, skipped: [], ...(publish ? { published: [] } : {}) };
     let unreachable = null;
     for (const file of files) {
         if (unreachable) {
             result.skipped.push({ path: file.path, reason: unreachable });
             continue;
         }
+        let stage = "";
         try {
-            if (await uploadOne(cfg, sessionId, file, budget))
+            const { created, id } = await uploadOne(cfg, sessionId, file, budget);
+            if (created)
                 result.uploaded++;
             else
                 result.existing++;
+            if (result.published) {
+                stage = "not made public: ";
+                const { json } = await request(cfg, "PATCH", `/v1/evidence/${encodeURIComponent(id)}`, { public: true }, budget);
+                const url = absolute(cfg, json.evidence.public_url);
+                result.published.push({
+                    path: file.path,
+                    id,
+                    url,
+                    // The caption given now, since the server keeps an existing file's first caption.
+                    markdown: embed({ ...json.evidence, caption: file.caption ?? json.evidence.caption }, url),
+                });
+            }
         }
         catch (err) {
             // One bad file never fails the report.
-            const reason = err instanceof Error ? err.message : String(err);
+            const reason = stage + (err instanceof Error ? err.message : String(err));
             result.skipped.push({ path: file.path, reason });
             // The next file would wait out the same budget against the same server (anti-goal 1).
             if (err instanceof CliError && err.kind === "network")
@@ -40,7 +55,7 @@ export async function uploadEvidence(cfg, sessionId, files, budget = LONG) {
     }
     return result;
 }
-// Resolves true when uploaded, false when the server already had the content.
+// created is false when the server already had the content.
 async function uploadOne(cfg, sessionId, file, budget) {
     const contentType = TYPES[path.extname(file.path).toLowerCase()];
     if (!contentType)
@@ -60,9 +75,10 @@ async function uploadOne(cfg, sessionId, file, budget) {
         sha256: hash.digest("hex"),
         caption: file.caption,
     }, budget);
+    const id = json.evidence.id;
     if (json.status === "exists")
-        return false;
-    const base = `/v1/evidence/${json.evidence.id}`;
+        return { created: false, id };
+    const base = `/v1/evidence/${id}`;
     const handle = await open(file.path);
     try {
         const slice = async (start, length) => {
@@ -90,5 +106,5 @@ async function uploadOne(cfg, sessionId, file, budget) {
     finally {
         await handle.close();
     }
-    return true;
+    return { created: true, id };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paxnax/berliner",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Report coding-agent sessions to Berliner",
   "type": "module",
   "engines": {

package/skill/SKILL.md

@@ -50,10 +50,21 @@ Report again with the same `--session-id` whenever something changes.
 - `--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.
+- `--public`: with `--evidence`, also make those files viewable without sign-in. See below.
 - `--task <id>`, `--task-url <url>`, `--project <name>`, `--started-at <ISO>`, `--ended-at <ISO>`.
 
 Quote any value that contains spaces.
 
+## Evidence in a pull request body
+
+Evidence is private by default: only the user can see it, signed in. GitHub can show only public files. To embed screenshots or videos in a PR body, report them with `--public`:
+
+```sh
+berliner report --evidence "./shots/after.png::Login page after the fix" --public
+```
+
+After the evidence line, it prints one line per file: `![Login page after the fix](https://berliner.app/v1/public/evidence/<id>)` for an image, the bare URL for a video. Paste those lines into the PR body as printed. Anyone with a link can view the file, so publish only what belongs in the PR. `berliner evidence private <id>` makes one private again; `berliner evidence public <id>` publishes one already uploaded. `berliner session <id>` lists the ids.
+
 ## Environment
 
 `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`.
@@ -68,7 +79,7 @@ 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.
+- `--json` prints the saved session as JSON, plus an `evidence` field with `uploaded`, `existing` and `skipped` results when `--evidence` was given, and `published` (`path`, `id`, `url`, `markdown`) with `--public`.
 - 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