@paxnax/berliner 0.4.0 → 0.5.0

package/README.md

@@ -21,9 +21,9 @@ 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 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.
+   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, the skill and any Berliner hook an older setup installed 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.
+3. From then on, the hooks report each session's cost, model, repository, commits and start and end times after every reply. They also fill in a ticket from a Linear or Jira URL in your prompts while the session has none, and refresh up to 5 open pull requests the Berliner GitHub App doesn't track with your `gh` (skipped when `gh` is missing or signed out). When a session starts, the hook reminds your agent to name the session and report its ticket. Your agent adds the title, ticket, pull requests, coverage and evidence with `berliner report` and `berliner update`, 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.
 
 Without setup: create an API token on **Settings**, `export BERLINER_TOKEN=brl_...`, and save the output of `berliner skill` where your agent reads skills (for Claude Code, `~/.claude/skills/berliner/SKILL.md`). Your agent then reports each session with `berliner report` and the flags under [Commands](#commands).
@@ -115,10 +115,12 @@ Other commands:
 - `berliner sessions [filters]`: list sessions. Filters: `--repo --model --project --ci --merge --since <N>d` or `--from --to`, plus `--limit` and `--json`.
 - `berliner session <session-id>`: show one session.
 - `berliner summary [filters]`: totals for the same filters as `sessions`, then one line per subscription.
+- `berliner projects [--json]`: the project names in use, then each repository's default project.
+- `berliner project [<name>] [--none] [--repo owner/name] [--json]`: with no name, show this repository's default project; with a name, save it; `--none` saves that the repository has no project. The repository comes from `git remote get-url origin` unless you pass `--repo`. A session's project is its own `--project`, else its repository's default, else its ticket's prefix (`SMTNC-3268` gives `SMTNC`). Until a repository has a default, `report` and `update` print a `Project: none saved` line, which asks your agent to suggest one to you.
 - `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`.
+- `berliner upgrade [--yes] [--no-skill]`: install the latest CLI and skill. It shows its plan (the versions, the exact install command, each skill file and each Berliner hook it updates) and asks before changing anything; a second question, or `--no-skill`, leaves your skill as it is. It brings a Berliner hook an older setup installed up to date, but never adds one; your token and config are never touched.
+- `berliner hook <tool>`: run by the hooks setup installs, with the tool's payload on stdin. It never fails and never makes the agent wait, and prints only the reminder when a session starts; 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.
+`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, including a file that could not be uploaded or made public; the session is still saved. The other commands exit 1 on failure.

package/dist/agents/claude.js

@@ -1,6 +1,6 @@
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
-import { addTokens, jsonl, num, Span } from "./read.js";
+import { addTokens, jsonl, num, Span, ticketUrl } from "./read.js";
 // Subagent transcripts sit next to the session's: <project>/<session-id>/subagents/agent-*.jsonl.
 async function subagentFiles(transcriptPath) {
     const dir = join(transcriptPath.replace(/\.jsonl$/, ""), "subagents");
@@ -24,11 +24,15 @@ export async function readClaudeCode(transcriptPath) {
     const responses = new Map();
     const span = new Span();
     let firstPrompt = null;
+    let taskUrl = null;
     for (const file of [transcriptPath, ...(await subagentFiles(transcriptPath))]) {
         for await (const e of jsonl(file)) {
             span.add(e.timestamp);
-            if (file === transcriptPath)
-                firstPrompt ??= promptText(e);
+            if (file === transcriptPath) {
+                const prompt = promptText(e);
+                firstPrompt ??= prompt;
+                taskUrl ??= ticketUrl(prompt);
+            }
             const m = e.message;
             // Claude Code's own placeholder replies are written as model "<synthetic>" with zero usage.
             if (e.type !== "assistant" || typeof m?.model !== "string" || m.model === "<synthetic>" || !m.usage)
@@ -57,5 +61,5 @@ export async function readClaudeCode(transcriptPath) {
     for (const [id, t] of Object.entries(tokensByModel))
         if (model === null || t.output > tokensByModel[model].output)
             model = id;
-    return { model, tokensByModel, costUsd: null, startedAt: span.first, endedAt: span.last, firstPrompt };
+    return { model, tokensByModel, costUsd: null, startedAt: span.first, endedAt: span.last, firstPrompt, taskUrl };
 }

package/dist/agents/codex.js

@@ -1,4 +1,4 @@
-import { addTokens, jsonl, num, Span } from "./read.js";
+import { addTokens, jsonl, num, Span, ticketUrl } from "./read.js";
 const zero = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cacheWrite1h: 0 };
 // Line shapes as Codex 0.162.1 writes them (codex-rs/protocol). input_tokens includes both cached reads and cache writes,
 // as in Codex's own parsing test (100 input = 40 cached + 60 written); reasoning_output_tokens is part of output_tokens.
@@ -6,6 +6,7 @@ export async function readCodex(rolloutPath) {
     const span = new Span();
     let model = null;
     let firstPrompt = null;
+    let taskUrl = null;
     let latest = zero;
     let latestTotal = 0;
     // A resumed session restarts the running total in the same rollout, so the totals before each restart are carried over.
@@ -17,10 +18,12 @@ export async function readCodex(rolloutPath) {
             model = p.model;
         if (e.type !== "event_msg")
             continue;
-        if (firstPrompt === null && p?.type === "item_completed" && p.item?.type === "UserMessage" && Array.isArray(p.item.content)) {
+        if (p?.type === "item_completed" && p.item?.type === "UserMessage" && Array.isArray(p.item.content)) {
             const text = p.item.content.find((c) => c?.type === "text")?.text;
-            if (typeof text === "string" && text.trim())
-                firstPrompt = text.trim();
+            if (typeof text === "string" && text.trim()) {
+                firstPrompt ??= text.trim();
+                taskUrl ??= ticketUrl(text);
+            }
         }
         const u = p?.type === "token_count" ? p.info?.total_token_usage : undefined;
         if (!u)
@@ -39,5 +42,5 @@ export async function readCodex(rolloutPath) {
         };
     }
     const tokens = addTokens(carried, latest);
-    return { model, tokensByModel: model ? { [model]: tokens } : {}, costUsd: null, startedAt: span.first, endedAt: span.last, firstPrompt };
+    return { model, tokensByModel: model ? { [model]: tokens } : {}, costUsd: null, startedAt: span.first, endedAt: span.last, firstPrompt, taskUrl };
 }

package/dist/agents/opencode.js

@@ -3,7 +3,7 @@ const iso = (ms) => {
     const d = new Date(typeof ms === "number" ? ms : Number.NaN);
     return Number.isNaN(d.getTime()) ? null : d.toISOString();
 };
-// The session has no prompt text, so there is no first prompt.
+// The session has no prompt text, so there is no first prompt and no ticket.
 export function readOpenCode(json) {
     const s = (typeof json === "object" && json !== null ? json : {});
     const model = typeof s.model?.id === "string" ? s.model.id : null;
@@ -23,5 +23,6 @@ export function readOpenCode(json) {
         startedAt: iso(s.time?.created),
         endedAt: iso(s.time?.updated),
         firstPrompt: null,
+        taskUrl: null,
     };
 }

package/dist/agents/read.js

@@ -14,6 +14,9 @@ export async function* jsonl(path) {
             yield value;
     }
 }
+// Full issue URLs only: a bare ID is ambiguous (UTF-8). Cut at the ID, so a slug or query never follows it.
+const TICKET_URL = /https?:\/\/(?:linear\.app\/[\w-]+\/issue|[\w-]+\.atlassian\.net\/browse)\/[A-Za-z][A-Za-z0-9]*-\d+\b/;
+export const ticketUrl = (text) => text?.match(TICKET_URL)?.[0] ?? null;
 export const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
 export const addTokens = (a, b) => ({
     input: a.input + b.input,

package/dist/args.js

@@ -24,6 +24,7 @@ const config = {
         "no-install": { type: "boolean" },
         "no-browser": { type: "boolean" },
         "no-skill": { type: "boolean" },
+        none: { type: "boolean" },
         run: { type: "string" },
         ci: { type: "string" },
         merge: { type: "string" },

package/dist/client.js

@@ -45,10 +45,12 @@ export async function request(cfg, method, path, body, opts = {}) {
             await sleep(backoffMs);
             continue;
         }
-        const json = (await res.json().catch(() => null));
-        if (!res.ok)
-            throw new CliError(errorMessage(method, path, res.status, json), "http", res.status, json?.error?.details);
-        return { status: res.status, json };
+        const json = await res.json().catch(() => null);
+        if (!res.ok) {
+            const err = json;
+            throw new CliError(errorMessage(method, path, res.status, err), "http", res.status, err?.error?.details);
+        }
+        return { status: res.status, json: json };
     }
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/commands/body.js

@@ -2,6 +2,9 @@ import { CliError, request } from "../client.js";
 import { gitFacts } from "../git.js";
 import { warn } from "../output.js";
 import { derivedTitle, sessionFacts } from "./hook.js";
+export const projectHint = (s) => s.repository_project_set === false && s.project_source !== "session"
+    ? `\nProject: none saved for ${s.repository}. Suggest one to the user, then save it with: berliner project "<name>"`
+    : "";
 // Shared by report (PUT) and update (PATCH): unset flags are undefined and drop out of the JSON.
 export function sessionBody(values) {
     return {
@@ -37,14 +40,27 @@ export async function fromTool(tool, values, env, command) {
     const ignored = ["session-id", "cost", "model"].filter((f) => values[f] !== undefined && values[f] !== filled[f]);
     if (ignored.length)
         warn(`ignored ${ignored.map((f) => `--${f}`).join(", ")}: inside ${tool.tool}, this session's own values are used`);
-    if (filled.repo === undefined || (command === "report" && filled.title === undefined)) {
+    // The derived title only names a session the hook hasn't created yet: see patchFirst.
+    if (filled.repo === undefined || filled.title === undefined) {
         const git = await gitFacts(process.cwd(), null);
         filled.repo ??= git.repository ?? undefined;
-        if (command === "report")
-            filled.title ??= derivedTitle(facts?.firstPrompt ?? null, git) ?? undefined;
+        filled.title ??= derivedTitle(facts?.firstPrompt ?? null, git) ?? undefined;
     }
     return filled;
 }
+// Inside a tool: the same fields, minus a derived title, for a session that exists; on a 404 (the first turn, before the hook
+// has reported), the PUT that creates it, at cost 0 while the cost is unknown and on BERLINER_PLAN when no plan is given.
+export async function patchFirst(cfg, path, body, titled, guess) {
+    try {
+        const res = await saveSession(cfg, "PATCH", path, titled ? body : { ...body, title: undefined }, guess);
+        return { ...res, json: { created: false, ...res.json } };
+    }
+    catch (err) {
+        if (!(err instanceof CliError && err.status === 404))
+            throw err;
+        return saveSession(cfg, "PUT", path, { ...body, cost_usd: body.cost_usd ?? 0, plan: body.plan ?? cfg.plan ?? undefined }, guess);
+    }
+}
 function number(values, flag) {
     const raw = values[flag];
     if (raw === undefined)

package/dist/commands/hook.js

@@ -5,15 +5,19 @@ import { basename, join } from "node:path";
 import { findRecord, readClaudeCode, readCodex, readOpenCode, SAFE_ID } from "../agents/index.js";
 import { CliError, request } from "../client.js";
 import { readConfig, stateDir } from "../config.js";
+import { viewPr } from "../gh.js";
 import { gitFacts } from "../git.js";
 import { estimateCost, loadPrices } from "../prices.js";
-const REMINDER = "This session reports to Berliner: run `berliner report` with the task and PRs before your final message.";
+// Same text in the OpenCode plugin (cli/opencode/berliner.js).
+const REMINDER = 'This session reports to Berliner. Once you know the task, name it: berliner update --title "<short title>". When a Linear or Jira ticket comes up, report it: berliner update --task <ID> --task-url <URL>. Before your final message, run berliner report with the PRs.';
 const TOOLS = ["claude-code", "codex", "opencode"];
 const REPORT_EVENTS = ["Stop", "PreCompact", "SessionEnd"];
 const OPENCODE_EVENTS = ["idle", "compacting"];
+const SESSION_STARTS = ["startup", "resume", "compact", "clear"];
 const MAX_PAYLOAD = 1024 * 1024;
 const LOCK_MS = 60_000;
 const DEADLINE_MS = 15_000;
+const MAX_GH = 5;
 export function inTool(env) {
     if (env.CLAUDE_CODE_SESSION_ID)
         return { tool: "claude-code", sessionId: env.CLAUDE_CODE_SESSION_ID };
@@ -81,8 +85,9 @@ async function start(tool, env) {
         id = p.session?.id;
     }
     else {
-        // A compaction or /clear may have lost the task and PRs the agent hasn't reported yet.
-        if (p.hook_event_name === "SessionStart" && (p.source === "compact" || p.source === "clear"))
+        // In the agent's context from the start, whether or not the skill triggers; after a compaction or /clear it may have lost
+        // the task and PRs it hasn't reported yet.
+        if (p.hook_event_name === "SessionStart" && SESSION_STARTS.includes(p.source))
             return console.log(REMINDER);
         if (!REPORT_EVENTS.includes(p.hook_event_name))
             return;
@@ -191,11 +196,15 @@ async function send(tool, file, env) {
         started_at: facts.startedAt ?? undefined,
         ended_at: facts.endedAt ?? undefined,
         repository: git.repository,
+        // The server only fills an empty ticket with these: the agent's own always wins. The URL ends in the ticket's ID.
+        detected_task_id: facts.taskUrl?.split("/").pop(),
+        detected_task_url: facts.taskUrl ?? undefined,
     };
     const cfg = readConfig(env);
     const path = `/v1/sessions/${encodeURIComponent(sessionId)}`;
+    let saved;
     try {
-        await request(cfg, "PATCH", path, body);
+        saved = await request(cfg, "PATCH", path, body);
     }
     catch (err) {
         if (!(err instanceof CliError && err.status === 404))
@@ -205,16 +214,34 @@ async function send(tool, file, env) {
         // session needs a cost: 0 until prices load.
         const create = (plan) => request(cfg, "PUT", path, { ...body, cost_usd: body.cost_usd ?? 0, title: derivedTitle(facts.firstPrompt, git), plan });
         try {
-            await create(cfg.plan ?? undefined);
+            saved = await create(cfg.plan ?? undefined);
         }
         catch (err) {
             // A BERLINER_PLAN the server rejects must not lose the session: the server picks the plan instead.
             if (!(cfg.plan && err instanceof CliError && err.status === 422 && err.details?.fieldErrors?.plan))
                 throw err;
-            await create(undefined);
+            saved = await create(undefined);
             log(env, `${tool} ${sessionId}: BERLINER_PLAN "${cfg.plan}" is not a plan; the server picked the plan`);
         }
     }
+    await refreshPrs(cfg, path, saved.json.session.prs, env, `${tool} ${sessionId}`);
+}
+// Untracked PRs keep their last reported state, so the machine's gh refreshes the open ones; the poller owns tracked PRs.
+// In parallel, 5 seconds each, inside the child's deadline. Only changes are sent.
+async function refreshPrs(cfg, path, prs, env, where) {
+    const open = prs.filter((p) => p.tracked === false && p.merge_state === "open").slice(0, MAX_GH);
+    const seen = await Promise.all(open.map((p) => viewPr(p.url).catch((err) => {
+        // No gh on this machine, or one that isn't signed in (exit code 4), is not an error: logging it would add lines every reply.
+        if (err.code !== "ENOENT" && err.code !== 4)
+            log(env, `${where}: gh pr view ${p.url}: ${err.message}`);
+        return null;
+    })));
+    const changed = open.flatMap((p, i) => {
+        const s = seen[i];
+        return s && (s.merge_state !== p.merge_state || s.ci_state !== p.ci_state) ? [{ url: p.url, ...s }] : [];
+    });
+    if (changed.length)
+        await request(cfg, "PATCH", path, { prs: changed });
 }
 // shortcut: hook.log is never rotated (one short line per skipped or failed report); rotate it if it grows large in practice.
 function log(env, line) {

package/dist/commands/projects.js

@@ -0,0 +1,37 @@
+import { CliError, request } from "../client.js";
+import { gitFacts } from "../git.js";
+import { print } from "../output.js";
+export async function projects(cfg, values) {
+    const { json } = await request(cfg, "GET", "/v1/projects");
+    const lines = json.projects.length ? ["Projects:", ...json.projects.map((p) => `  ${p}`)] : ["No projects yet."];
+    if (json.repositories.length)
+        lines.push("Repository defaults:", ...json.repositories.map((r) => `  ${r.repository}  ${r.project ?? "(none)"}`));
+    print({ data: json, text: lines.join("\n") }, values.json === true);
+}
+// The default project of one repository: shown without a name, saved with one, saved as "no project" with --none.
+export async function project(cfg, values, positionals) {
+    if (positionals.length > 1 || (positionals.length && values.none)) {
+        throw new CliError("usage: berliner project [<name> | --none] [--repo owner/name] [--json]; quote names that contain spaces", "usage");
+    }
+    const repository = values.repo ?? (await gitFacts(process.cwd(), null)).repository;
+    if (!repository)
+        throw new CliError("no GitHub repository here; pass --repo owner/name", "usage");
+    const [owner, name, ...rest] = repository.split("/");
+    if (!owner || !name || rest.length)
+        throw new CliError(`--repo must be owner/name, got "${repository}"`, "usage");
+    if (!positionals.length && !values.none) {
+        const { json } = await request(cfg, "GET", "/v1/projects");
+        // Repositories are matched without case, as the server stores them.
+        const row = json.repositories.find((r) => r.repository.toLowerCase() === repository.toLowerCase());
+        const text = !row
+            ? `No project saved for ${repository}.`
+            : row.project === null
+                ? `${row.repository} has no project.`
+                : `${row.repository}: ${row.project}`;
+        return print({ data: { repository: row?.repository ?? repository, project: row?.project ?? null, saved: row !== undefined }, text }, values.json === true);
+    }
+    const path = `/v1/repositories/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/project`;
+    const { json } = await request(cfg, "PUT", path, { project: values.none ? null : positionals[0] });
+    const text = json.project === null ? `Saved: ${json.repository} has no project.` : `Saved project "${json.project}" for ${json.repository}.`;
+    print({ data: json, text }, values.json === true);
+}

package/dist/commands/report.js

@@ -1,7 +1,7 @@
 import { CliError } from "../client.js";
 import { print, warn } from "../output.js";
 import { uploadEvidence } from "../upload.js";
-import { fromTool, saveSession, sessionBody } from "./body.js";
+import { fromTool, patchFirst, projectHint, saveSession, sessionBody } from "./body.js";
 import { inTool } from "./hook.js";
 const required = ["session-id", "title", "repo", "cost", "model", "plan"];
 export async function report(cfg, values, positionals, env) {
@@ -29,7 +29,7 @@ export async function report(cfg, values, positionals, env) {
         : saveSession(cfg, "PUT", path, body, values.plan));
     const json = dropped.length ? { ...saved, dropped } : saved;
     const { created, session } = json;
-    const text = `Saved session ${session.id} (${created ? "created" : "updated"}). ${session.pr_count} PR(s) linked.`;
+    const text = `Saved session ${session.id} (${created ? "created" : "updated"}). ${session.pr_count} PR(s) linked.${projectHint(session)}`;
     const json_ = values.json === true;
     // Human mode prints the session line before uploads start; --json waits so stdout is one document.
     if (!json_)
@@ -49,19 +49,9 @@ export async function report(cfg, values, positionals, env) {
     }
     for (const s of result.skipped)
         warn(`${s.path}: ${s.reason}`);
-}
-// The same fields, minus a derived title, for a session that exists; on a 404, the PUT that creates it, at cost 0 while the
-// cost is unknown.
-async function patchFirst(cfg, path, body, titled, guess) {
-    try {
-        const res = await saveSession(cfg, "PATCH", path, titled ? body : { ...body, title: undefined }, guess);
-        return { ...res, json: { created: false, ...res.json } };
-    }
-    catch (err) {
-        if (!(err instanceof CliError && err.status === 404))
-            throw err;
-        return saveSession(cfg, "PUT", path, { ...body, cost_usd: body.cost_usd ?? 0 }, guess);
-    }
+    // The session is saved either way; --strict asks for a skipped file to count as a failure.
+    if (values.strict && result.skipped.length)
+        process.exitCode = 1;
 }
 // <path>[::<caption>]
 function parseEvidence(spec) {

package/dist/commands/setup.js

@@ -1,13 +1,13 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { CliError, request } from "../client.js";
 import { configPath, DEFAULT_URL, readConfig, readConfigFile, saveConfig } from "../config.js";
 import { machineName, openBrowser, startConnect, waitForApproval } from "../setup/connect.js";
-import { describeClaudeHooks, describeCodexHooks, describeOpenCodePlugin, installClaudeHooks, installCodexHooks, installOpenCodePlugin, } from "../setup/hooks.js";
-import { claudeDir, codexDir, detectTools, onPath, opencodeDir, skillTargets } from "../setup/targets.js";
+import { describeClaudeHooks, describeCodexHooks, describeOpenCodePlugin, hookPath, installClaudeHooks, installCodexHooks, installOpenCodePlugin, } from "../setup/hooks.js";
+import { detectTools, onPath, 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';
 export const tilde = (p) => (p.startsWith(`${homedir()}/`) ? `~${p.slice(homedir().length)}` : p);
@@ -47,11 +47,11 @@ export async function setup(env, values) {
     const targets = skillTargets(tools, env);
     // One reporting hook per tool found, where the spec's "Hooks" table puts it.
     const hookFiles = {
-        "claude-code": { path: join(claudeDir(env), "settings.json"), describe: describeClaudeHooks, install: installClaudeHooks },
-        codex: { path: join(codexDir(env), "hooks.json"), describe: describeCodexHooks, install: installCodexHooks },
-        opencode: { path: join(opencodeDir(env), "plugins", "berliner.js"), describe: describeOpenCodePlugin, install: installOpenCodePlugin },
+        "claude-code": { describe: describeClaudeHooks, install: installClaudeHooks },
+        codex: { describe: describeCodexHooks, install: installCodexHooks },
+        opencode: { describe: describeOpenCodePlugin, install: installOpenCodePlugin },
     };
-    const hooks = tools.filter((t) => t.found).map((t) => ({ ...t, ...hookFiles[t.id] }));
+    const hooks = tools.filter((t) => t.found).map((t) => ({ ...t, ...hookFiles[t.id], path: hookPath(t.id, env) }));
     const version = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
     const install = installCommand(version);
     // The plan is data, built and shown before anything changes.
@@ -152,7 +152,7 @@ export async function setup(env, values) {
         if (result === "unreadable")
             console.error(`✗ ${h.name} hook: ${tilde(h.path)} can't be read, so it was left unchanged`);
         else
-            console.log(`✓ ${h.name} hook: ${tilde(h.path)}${result === "present" ? " (already installed)" : ""}`);
+            console.log(`✓ ${h.name} hook: ${tilde(h.path)}${result === "present" ? " (already installed)" : result === "updated" ? " (updated)" : ""}`);
         codexAdded ||= h.id === "codex" && result === "added";
     }
     const summary = [

package/dist/commands/update.js

@@ -1,6 +1,6 @@
 import { CliError } from "../client.js";
 import { print } from "../output.js";
-import { fromTool, saveSession, sessionBody } from "./body.js";
+import { fromTool, patchFirst, projectHint, saveSession, sessionBody } from "./body.js";
 import { inTool } from "./hook.js";
 export async function update(cfg, values, positionals, env) {
     const tool = inTool(env);
@@ -12,12 +12,14 @@ export async function update(cfg, values, positionals, env) {
         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");
+    const titled = values.title !== undefined;
     if (tool)
         values = await fromTool(tool, { ...values, "session-id": positionals[0] ?? values["session-id"] }, env, "update");
     const id = tool ? tool.sessionId : positionals[0];
     // A plan is only sent when --plan is passed, so an update never changes it unasked; BERLINER_PLAN then replaces it.
     const body = { ...sessionBody(values), plan: values.plan === undefined ? undefined : (cfg.plan ?? values.plan) };
-    const { json: saved, dropped } = await saveSession(cfg, "PATCH", `/v1/sessions/${encodeURIComponent(id)}`, body, values.plan);
+    const path = `/v1/sessions/${encodeURIComponent(id)}`;
+    const { json: saved, dropped } = await (tool ? patchFirst(cfg, path, body, titled, values.plan) : saveSession(cfg, "PATCH", path, body, values.plan));
     const json = dropped.length ? { ...saved, dropped } : saved;
-    print({ data: json, text: `Updated session ${json.session.id}. ${json.session.pr_count} PR(s) linked.` }, values.json === true);
+    print({ data: json, text: `Updated session ${json.session.id}. ${json.session.pr_count} PR(s) linked.${projectHint(json.session)}` }, values.json === true);
 }

package/dist/commands/upgrade.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { CliError } from "../client.js";
+import { hookPath, updatedHooks } from "../setup/hooks.js";
 import { detectTools, skillTargets } from "../setup/targets.js";
 import { confirm, installCommand, showPlan, tilde } from "./setup.js";
 async function latestVersion(env) {
@@ -44,7 +45,13 @@ const sameAs = (path, text) => {
         return false;
     }
 };
-// Only the command and the skill: the token, config and hooks are setup's, and stay as they are.
+// What a hook gains from this release, for the plan.
+const HOOK_CHANGE = {
+    "claude-code": "the reminder also runs on startup and resume",
+    codex: "the reminder also runs on startup and resume",
+    opencode: "the new reminder",
+};
+// The command, the skill, and Berliner hooks already installed: the token and config are setup's, as is adding a hook.
 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);
@@ -56,7 +63,13 @@ export async function upgrade(env, values) {
     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) {
+    // Computed now, so what is written is what the plan showed.
+    const hooks = tools.flatMap((tool) => {
+        const path = hookPath(tool.id, env);
+        const text = updatedHooks(tool.id, path);
+        return text === null ? [] : [{ ...tool, path, text }];
+    });
+    if (!installing && !stale.length && !hooks.length) {
         console.log(`Already up to date. berliner ${current} is ${current === latest ? "the latest release" : `newer than the latest release (${latest})`}.`);
         return;
     }
@@ -79,6 +92,9 @@ export async function upgrade(env, values) {
                     return `${tool.name.padEnd(14)}${where}`;
                 }),
             },
+        ...(hooks.length
+            ? [{ label: "Update the Berliner hook for:", detail: hooks.map((h) => `${h.name.padEnd(14)}${tilde(h.path)} (${HOOK_CHANGE[h.id]})`) }]
+            : []),
     ]);
     if (!values.yes) {
         if (!process.stdin.isTTY)
@@ -112,5 +128,16 @@ export async function upgrade(env, values) {
             console.error(`✗ ${what}: ${tilde(t.path)} can't be written (${err.message.split(",")[0]})`);
         }
     }
+    for (const h of hooks) {
+        try {
+            // In place, so a settings file that is a symlink stays one.
+            writeFileSync(h.path, h.text);
+            console.log(`✓ ${h.name} hook: ${tilde(h.path)}`);
+        }
+        catch (err) {
+            unwritten = true;
+            console.error(`✗ ${h.name} hook: ${tilde(h.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/gh.js

@@ -0,0 +1,28 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const MERGE = { OPEN: "open", MERGED: "merged", CLOSED: "closed" };
+// CheckRun conclusions and StatusContext states.
+const FAILED = ["FAILURE", "ERROR", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"];
+const PENDING = ["PENDING", "EXPECTED"];
+// `gh pr view --json state,statusCheckRollup` as Berliner's merge and CI states. statusCheckRollup mixes CheckRuns (status,
+// conclusion; conclusion is "" until completed) and commit StatusContexts (state).
+export function prState(view) {
+    const merge_state = MERGE[String(view.state)];
+    if (!merge_state)
+        throw new Error(`unexpected PR state ${JSON.stringify(view.state)}`);
+    const checks = (Array.isArray(view.statusCheckRollup) ? view.statusCheckRollup : []);
+    const ci_state = checks.some((c) => FAILED.includes(c?.conclusion || c?.state))
+        ? "failed"
+        : checks.some((c) => (typeof c?.status === "string" ? c.status !== "COMPLETED" : PENDING.includes(c?.state)))
+            ? "running"
+            : checks.length
+                ? "passed"
+                : "none";
+    return { merge_state, ci_state };
+}
+// The machine's gh, found on PATH; it rejects when gh is missing (code ENOENT), fails or takes over 5 seconds.
+export async function viewPr(url) {
+    const { stdout } = await run("gh", ["pr", "view", url, "--json", "state,statusCheckRollup"], { timeout: 5000 });
+    return prState(JSON.parse(stdout));
+}

package/dist/index.js

@@ -5,6 +5,7 @@ import { CliError } from "./client.js";
 import { del } from "./commands/delete.js";
 import { evidence } from "./commands/evidence.js";
 import { hook } from "./commands/hook.js";
+import { project, projects } from "./commands/projects.js";
 import { report } from "./commands/report.js";
 import { session } from "./commands/session.js";
 import { sessions } from "./commands/sessions.js";
@@ -28,6 +29,9 @@ Commands:
   sessions              [--repo --model --project --ci --merge --since <N>d | --from --to] [--limit <n>] [--json]
   session <session-id>  [--json]
   summary               same filters as sessions [--json]
+  projects              the project names in use, then each repository's default [--json]
+  project [<name>]      show or save this repository's default project; --none saves "no project"
+                        [--none --repo <owner/name> --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]
@@ -39,7 +43,21 @@ 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", "evidence", "skill", "hook", "upgrade"]);
+const handled = new Set([
+    "setup",
+    "report",
+    "update",
+    "sessions",
+    "session",
+    "summary",
+    "projects",
+    "project",
+    "delete",
+    "evidence",
+    "skill",
+    "hook",
+    "upgrade",
+]);
 const cfg = () => readConfig(process.env);
 try {
     if (args.values.help)
@@ -61,6 +79,10 @@ try {
         await session(cfg(), args.values, args.positionals);
     else if (args.command === "summary")
         await summary(cfg(), args.values);
+    else if (args.command === "projects")
+        await projects(cfg(), args.values);
+    else if (args.command === "project")
+        await project(cfg(), args.values, args.positionals);
     else if (args.command === "delete")
         await del(cfg(), args.values, args.positionals);
     else if (args.command === "evidence")

package/dist/setup/hooks.js

@@ -1,5 +1,6 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { claudeDir, codexDir, opencodeDir } from "./targets.js";
 const entries = (tool, asyncStop) => {
     const hooks = (extra = {}) => [{ type: "command", command: `berliner hook ${tool}`, ...extra }];
     return {
@@ -8,16 +9,17 @@ const entries = (tool, asyncStop) => {
         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() },
+        SessionStart: { matcher: "startup|resume|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) {
+// The file with our entries added to the events that lack one (unless addMissing is false) and an older matcher of ours
+// brought up to date in place, or null when nothing changes. "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, addMissing = true) {
     let text = null;
     let json = {};
     try {
@@ -33,37 +35,56 @@ function merged(file, add) {
     const hooks = json.hooks ?? {};
     if (!isObject(hooks))
         return "unreadable";
-    let changed = false;
+    let added = false;
+    let updated = 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;
+        const i = list.findIndex(ours);
+        if (i < 0 && addMissing) {
+            hooks[event] = [...list, entry];
+            added = true;
+        }
+        else if (i >= 0 && entry.matcher !== undefined && list[i].matcher !== entry.matcher) {
+            hooks[event] = list.map((e, j) => (j === i ? { ...e, matcher: entry.matcher } : e));
+            updated = true;
+        }
     }
-    if (!changed)
+    if (!added && !updated)
         return null;
     const indent = text?.match(/^[ \t]+(?=\S)/m)?.[0] ?? "  ";
-    return `${JSON.stringify({ ...json, hooks }, null, indent)}\n`;
+    return { text: `${JSON.stringify({ ...json, hooks }, null, indent)}\n`, added };
 }
 function install(file, add) {
-    const text = merged(file, add);
-    if (text === "unreadable")
-        return text;
-    if (text === null)
+    const result = merged(file, add);
+    if (result === "unreadable")
+        return result;
+    if (result === 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";
+    writeFileSync(file, result.text);
+    return result.added ? "added" : "updated";
 }
-const describe = (text) => (text === "unreadable" ? "can't be read, left unchanged" : text === null ? "already installed" : "adds a hook");
+const describe = (result) => result === "unreadable" ? "can't be read, left unchanged" : result === null ? "already installed" : result.added ? "adds a hook" : "updates the 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)));
+export const hookPath = (tool, env) => tool === "claude-code"
+    ? join(claudeDir(env), "settings.json")
+    : tool === "codex"
+        ? join(codexDir(env), "hooks.json")
+        : join(opencodeDir(env), "plugins", "berliner.js");
+// For upgrade: the hook file's new text when a Berliner hook is installed but older than this release, else null. Hooks that
+// are missing stay missing: adding them is setup's.
+export function updatedHooks(tool, path) {
+    if (tool === "opencode")
+        return existsSync(path) && !current(path) ? plugin() : null;
+    const result = merged(path, entries(tool, tool === "claude-code"), false);
+    return result === "unreadable" ? null : (result?.text ?? null);
+}
 // 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) => {

package/opencode/berliner.js

@@ -16,7 +16,9 @@ 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.";
+// Same text as the CLI's SessionStart reminder (src/commands/hook.ts).
+const REMINDER =
+  'This session reports to Berliner. Once you know the task, name it: berliner update --title "<short title>". When a Linear or Jira ticket comes up, report it: berliner update --task <ID> --task-url <URL>. Before your final message, run berliner report with the PRs.';
 // 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.

package/package.json

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

package/skill/SKILL.md

@@ -1,16 +1,18 @@
 ---
 name: berliner
-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.
+description: Use as soon as you know what the task is, whenever a Linear or Jira ticket comes up, when you commit, open, update, merge or close a pull request, or finish a task, and whenever the user asks you to report to Berliner. Names the session and reports the ticket, project, pull requests, test coverage and screenshots or videos with the berliner CLI.
 ---
 
 # Reporting to Berliner
 
-Berliner records what an autonomous session cost and produced. You report with one command, `berliner report`.
+Berliner records what an autonomous session cost and produced. You report with `berliner report`, and change single fields with `berliner update`.
 
 ## When to report
 
+- As soon as you know the task: name the session (below).
+- Right away when a ticket comes up.
 - 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.
+- Again whenever a PR changes (opened, merged, closed, CI finishes) or you add evidence.
 - Right away when the user asks you to report to Berliner.
 
 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.
@@ -21,14 +23,78 @@ Hooks installed by `berliner setup` already report the session's cost, model, re
 
 | Flag | What to send |
 |---|---|
-| `--title` | A short line naming the task. |
-| `--task`, `--task-url` | The ticket ID and its URL, if there is one. |
+| `--title` | A short line naming the task. See [Name the session](#name-the-session). |
+| `--task`, `--task-url` | The ticket ID and its URL, if there is one. See [Tickets](#tickets). |
 | `--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.
 
+## Name the session
+
+As soon as you know what the task is, name the session:
+
+```sh
+berliner update --title "Fix login redirect loop"
+```
+
+Keep it under about 60 characters, and name the work, not the prompt: "Fix login redirect loop", not "can you look at why login keeps redirecting". Name it again if the task changes. Write the title yourself; don't spawn a subagent for it. Until you do, the session is titled with the first line of the user's first prompt.
+
+Outside Claude Code, Codex and OpenCode, the first `berliner report` creates the session, so pass `--title` there; `berliner update <session-id> --title "..."` renames it later.
+
+## Tickets
+
+When a ticket is mentioned, created, or found in the branch name, report it right away, without waiting for the end of the session:
+
+```sh
+berliner update --task ENG-5521 --task-url https://linear.app/octo/issue/ENG-5521
+```
+
+The hook fills in a ticket from a Linear or Jira URL in the user's prompts, but only while the session has none. A ticket you report always wins, so report the one the work is really for.
+
+## Projects
+
+A project is the body of work the user would report on: maintenance work for a client, a stream of recurring tickets that lives in a tracker project, or a product of the user's own. A session's project is, in order:
+
+1. the session's own `--project`;
+2. the user's saved default for the repository;
+3. the ticket ID's prefix (`SMTNC-3268` gives `SMTNC`).
+
+Send `--project` only for the ticket's tracker project (its Linear project or Jira epic), or a project the user named for this session. Never send a team name: the ticket prefix already covers it, and an explicit team name splits the repository's sessions away from its default.
+
+`report` and `update` print this line when the repository has no saved default:
+
+```text
+Project: none saved for octo/app. Suggest one to the user, then save it with: berliner project "<name>"
+```
+
+In an interactive session, when you see it:
+
+1. Run `berliner projects` and reuse an existing name where one fits. Otherwise suggest the ticket's tracker project, else the repository or org name.
+2. Ask the user once, in one line, without stopping your work: "This looks like part of **Acme maintenance**. Is that right?"
+3. Save their answer with `berliner project "Acme maintenance"`, or `berliner project --none` if they say it has no project. Either way, you are not asked again for that repository.
+
+In a non-interactive session (no user to answer), never ask and never save.
+
+| Command | What it does |
+|---|---|
+| `berliner projects` | The project names in use, then each repository's default. |
+| `berliner project` | This repository's default, or that none is saved. |
+| `berliner project "<name>"` | Saves `<name>` as this repository's default. |
+| `berliner project --none` | Saves that this repository has no project. |
+
+The repository comes from `git remote get-url origin`; `--repo owner/name` names another one.
+
+## Keep PR states current
+
+A PR in a repository without the Berliner GitHub App keeps the state you last reported. So:
+
+- When you merge a PR, or see one merged or closed, report it at once: `berliner update --pr "<url>,merge=merged"` (or `merge=closed`).
+- Before your final message, check each open PR you reported with `gh pr view <url> --json state`, and report any change.
+
+The hook also refreshes open PRs like these with `gh` after every reply, but don't rely on it: `gh` may be missing or signed out.
+
 ## Outside those tools
 
 Without a hook, `report` needs these flags:
@@ -51,7 +117,9 @@ Report again with the same `--session-id` whenever something changes.
 - `--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>`.
+- `--task <id>`, `--task-url <url>`: the ticket. See [Tickets](#tickets).
+- `--project <name>`: only the ticket's tracker project or a project the user named. See [Projects](#projects).
+- `--started-at <ISO>`, `--ended-at <ISO>`.
 
 Quote any value that contains spaces.
 
@@ -63,13 +131,13 @@ Evidence is private by default: only the user can see it, signed in. GitHub can
 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.
+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, and never a capture that shows a password, a token, a cookie or a real customer's data. Before pasting, check that each link opens without signing in: `curl -s -o /dev/null -w '%{http_code}' <url>` prints `200`. `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`.
 
-If the `berliner` command is not found, ask the user to run `npx @paxnax/berliner@latest setup`. Do not try to install it yourself.
+If the `berliner` command is not found, carry on with your work and say in your final message that `npx @paxnax/berliner@latest setup` needs to run. Do not try to install it yourself.
 
 ## Timeouts
 
@@ -77,8 +145,8 @@ The session is saved first, then evidence is uploaded. Allow at least 10 minutes
 
 ## Reading the output
 
-- 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.
+- Success prints what was saved, then an evidence line such as `Evidence: 1 uploaded, 0 already uploaded, 0 skipped.` A `Project: none saved` line asks you for a project: see [Projects](#projects).
+- 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. With `--strict`, any failure exits 1, a skipped file included; the session is still saved. 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, 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.