nerdsystem 0.0.25 → 0.0.27

package/dist/commands/claude-md-history.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The sha256 of every version of the starter app's CLAUDE.md this project has shipped (line endings as LF).
+ * `nerd upgrade` uses it to tell a CLAUDE.md that is still exactly the platform's text, which it replaces
+ * without ceremony, from one a person or an agent has added to, which it keeps beside the new one.
+ *
+ * When packages/template/CLAUDE.md changes, add the new hash here; a test fails until it is listed.
+ * To print it: `tr -d '\\r' < packages/template/CLAUDE.md | sha256sum`.
+ */
+export declare const KNOWN_CLAUDE_MD: Set<string>;

package/dist/commands/claude-md-history.js

@@ -0,0 +1,18 @@
+/**
+ * The sha256 of every version of the starter app's CLAUDE.md this project has shipped (line endings as LF).
+ * `nerd upgrade` uses it to tell a CLAUDE.md that is still exactly the platform's text, which it replaces
+ * without ceremony, from one a person or an agent has added to, which it keeps beside the new one.
+ *
+ * When packages/template/CLAUDE.md changes, add the new hash here; a test fails until it is listed.
+ * To print it: `tr -d '\\r' < packages/template/CLAUDE.md | sha256sum`.
+ */
+export const KNOWN_CLAUDE_MD = new Set([
+    "02eb1063cb99fca0106b0a3052872a7839782564d285527ac74a08b1ca19b9ed",
+    "30b969614ba066a6faa930d35df67da48c3a692aba66ce009543e7c0d58114ba",
+    "31b9481c380810c87dff5e6a0812274cfb7068a35e11941867ad5bd4b2dc8dbf",
+    "440751d827c9f112f584157ea08495b56c8ff111024cc52177e5aa98b07622b8",
+    "4dc0c5234ad2115e1b932396db2a6efb0329bd93cb4f8ddc9968d978ddd48389",
+    "65f97940d79e9d657bc117d1dbbf13f21e84c578301b20b13c726e00739a305b",
+    "6f21b6478d50bd599bc8833068ffa82bc7ad5434439636a81b5b35d9d8554947",
+    "887cebefb74b2187ccaea027a40074d0cd163c3e6ed6fcdb0edbcbe766c0ccdd",
+]);

package/dist/commands/deploy.d.ts

@@ -11,6 +11,12 @@ export interface BuildOutput {
     compatibilityFlags: string[];
 }
 /** Locates the Vite build output: dist/<worker>/wrangler.json names the entry and the assets dir. */
+/**
+ * The Vite plugin copies `.dev.vars` next to the built Worker so a local preview can read it. A deploy
+ * never uploads it, and it is rewritten by every build, so the copy is removed here instead of being
+ * reported on every run with nothing for anyone to do about it. The file in the app's own folder stays.
+ */
+export declare function dropLocalSecretCopies(build: BuildOutput): void;
 export declare function readBuildOutput(root: string): BuildOutput;
 export declare function applyRemoteMigrations(root: string, api: ApiClient): Promise<{
     applied: string[];

package/dist/commands/deploy.js

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { ApiClient } from "../api.js";
 import { findProjectRoot, projectPath, readDevVars, readNerdJson } from "../project.js";
@@ -8,6 +8,7 @@ import { CliError, log, printJson, runOrThrow, table, dashboardUrl, ensureDeps }
 import { runChecks } from "./check.js";
 import { appendLineage, cliVersion, LOCAL_ONLY_NOTE, packProject, readLineage, uploadSnapshot, uploadStopMessage } from "./source.js";
 import { lockedGetPaths } from "../gates/tests.js";
+import { ENV_FILES } from "../gates/text.js";
 import { platformScan } from "./platform-scan.js";
 import { platformReview, printReview } from "./platform-review.js";
 import { BUILD_GATES, gateSummary, knownSecretsFrom, probeDeployment, runGates, skippedProbe, SOURCE_GATES, waitForDeployment } from "../gates/index.js";
@@ -24,6 +25,18 @@ function walk(dir, base = dir) {
     return out;
 }
 /** Locates the Vite build output: dist/<worker>/wrangler.json names the entry and the assets dir. */
+/**
+ * The Vite plugin copies `.dev.vars` next to the built Worker so a local preview can read it. A deploy
+ * never uploads it, and it is rewritten by every build, so the copy is removed here instead of being
+ * reported on every run with nothing for anyone to do about it. The file in the app's own folder stays.
+ */
+export function dropLocalSecretCopies(build) {
+    if (!existsSync(build.workerDir))
+        return;
+    for (const name of readdirSync(build.workerDir))
+        if (ENV_FILES.test(name))
+            rmSync(path.join(build.workerDir, name), { force: true });
+}
 export function readBuildOutput(root) {
     const dist = path.join(root, "dist");
     if (!existsSync(dist))
@@ -76,10 +89,11 @@ async function probeAfterDeploy(root, deployment, url, skip) {
         return skippedProbe("the app had not started answering within 30 seconds; open the URL to check, or run nerd deploy again to probe it");
     return probeDeployment(url, undefined, { lockedGets: lockedGetPaths(root) });
 }
-function printProbe(url, probes) {
+function printProbe(url, probes, ownDomain) {
     if (probes.status === "skip")
         return log.info(`Live URL not probed: ${probes.summary}`);
-    const line = `Probed ${url}: ${probes.status === "pass" ? "all probes passed" : probes.summary}`;
+    // With the owner's domain on the app, the address above is theirs and this one is not: say why it is the one tried.
+    const line = `Probed ${url}${ownDomain ? " (the app's platform address, which keeps answering whatever happens to the domain's DNS)" : ""}: ${probes.status === "pass" ? "all probes passed" : probes.summary}`;
     if (probes.status === "pass")
         log.ok(line);
     else
@@ -224,6 +238,7 @@ export async function deploy(opts) {
         await runOrThrow("npx", ["vite", "build"], { cwd: root, stdoutToStderr: true });
     }
     const build = readBuildOutput(root);
+    dropLocalSecretCopies(build);
     const built = await runGates(BUILD_GATES, { root, build, knownSecrets, log: (l) => log.info(l) }, { stopOnFail: true });
     if (!built.ok)
         throw new CliError(`Blocked by: ${built.failed.map((g) => g.title).join(", ")}.`, 2);
@@ -235,7 +250,7 @@ export async function deploy(opts) {
         const review = wantReview ? await platformReview(api, `${projectPath(nerd)}/sources/${r.source.id}`, reviewPage) : null;
         return printJson({ deployment: r.deployment, url: r.url, customUrl: r.customUrl, migrations: r.migrations, probes: r.probes, source: r.source, sourceSkipped: r.sourceSkipped, lineage: r.lineage.passed, warnings: r.warnings, review });
     }
-    printProbe(r.url, r.probes);
+    printProbe(r.url, r.probes, Boolean(r.customUrl));
     if (r.deployment.status === "live") {
         if (r.deployment.sourceId)
             log.ok(sourceLine(r));
@@ -246,7 +261,10 @@ export async function deploy(opts) {
         log.step("Your app is live. Checking in on its review (now and then nerdsystem reads the code itself, which takes a minute or two; safe to stop waiting)");
         printReview(await platformReview(api, `${projectPath(nerd)}/sources/${r.source.id}`, reviewPage));
     }
-    log.info(`First time? Sign up on your app at ${r.customUrl ?? r.url}, then make yourself admin in the dashboard's Auth tab: ${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/auth`);
+    // Said once, after the app's first deploy, which is when it is news.
+    const earlier = await api.get(projectPath(nerd, "/deployments?limit=2")).catch(() => null);
+    if (earlier && earlier.deployments.length <= 1)
+        log.info(`First time? Sign up on your app at ${r.customUrl ?? r.url}, then make yourself admin in the dashboard's Auth tab: ${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/auth`);
 }
 export async function deployments(opts) {
     const nerd = readNerdJson(findProjectRoot());

package/dist/commands/init.js

@@ -192,4 +192,4 @@ export async function init(dir, args) {
     log.ok(`Ready. Next:\n  cd ${dir}\n  pnpm install\n  nerd dev\n\nThen open the folder in your coding agent and ask it to build the first feature; the nerdsystem skill walks it through.\nDeploys go to ${project.url}`);
 }
 // Kept in sync with packages/sdk/package.json by the release script.
-const SDK_VERSION = "0.0.25";
+const SDK_VERSION = "0.0.27";

package/dist/commands/platform-review.d.ts

@@ -16,6 +16,8 @@ export type ReviewOutcome = {
     platformRead: boolean;
     /** Whose review the findings on file come from. */
     kind: "platform" | "session";
+    /** Findings recorded as real and deliberately left as they are. Counted, not listed: there is nothing to do about them. */
+    leftAsIs: number;
 } | {
     status: "skipped";
     reason: string;

package/dist/commands/platform-review.js

@@ -33,16 +33,22 @@ export async function platformReview(api, sourcePath, dashboard) {
     }
     const kind = review.kind === "session" ? "session" : "platform";
     if (review.status !== "done")
-        return { status: "declined", findings: [], dashboard, platformRead, kind };
+        return { status: "declined", findings: [], dashboard, platformRead, kind, leftAsIs: 0 };
     const findings = [];
+    let leftAsIs = 0;
     for (const f of review.findings ?? []) {
         const rule = typeof f.rule_id === "string" && f.rule_id.startsWith("review/") ? RULES[f.rule_id] : undefined;
         // A type this version of nerd does not know is left out rather than shown with words from elsewhere.
         if (!rule || typeof f.file !== "string" || !/^[\w./@-]{1,200}$/.test(f.file) || !Number.isInteger(f.line))
             continue;
+        // Recorded as deliberately left: not open, and not something to act on after a deploy.
+        if (f.leftAsIs === true) {
+            leftAsIs++;
+            continue;
+        }
         findings.push({ rule_id: f.rule_id, severity: rule.severity, audience: rule.audience, file: f.file, line: f.line, risk: rule.risk, fix: rule.fix });
     }
-    return { status: "done", findings, dashboard, platformRead, kind };
+    return { status: "done", findings, dashboard, platformRead, kind, leftAsIs };
 }
 export function printReview(r) {
     if (r.status === "skipped") {
@@ -54,11 +60,12 @@ export function printReview(r) {
         return;
     }
     const whose = r.platformRead ? "nerdsystem read the code itself after this deploy" : r.kind === "session" ? "from the review this app's agent last reported" : "from nerdsystem's last own read of the code";
+    const left = r.leftAsIs ? `; ${r.leftAsIs} known and left as ${r.leftAsIs === 1 ? "it is" : "they are"}` : "";
     if (!r.findings.length) {
-        log.ok(`Review: nothing open (${whose}). A plain-language summary for the person is at ${r.dashboard}`);
+        log.ok(`Review: nothing open (${whose}${left}). A plain-language summary for the person is at ${r.dashboard}`);
         return;
     }
-    log.warn(`Review: ${r.findings.length} thing(s) open (${whose}). A review is a second opinion and can be wrong, so check each one against the code before changing anything. Say what you did about them in the next \`nerd review report\`.`);
+    log.warn(`Review: ${r.findings.length} thing(s) open (${whose}${left}). A review is a second opinion and can be wrong, so check each one against the code before changing anything. Say what you did about them in the next \`nerd review report\`.`);
     for (const f of r.findings) {
         log.info(`    ${f.severity === "info" ? "·" : "!"} ${f.rule_id} ${f.file}:${f.line}${f.audience === "human" ? "  (for the person to decide)" : ""}`);
         log.info(`      ${f.risk}`);

package/dist/commands/session-review.d.ts

@@ -33,6 +33,8 @@ interface OpenFinding {
     file: string;
     line: number;
     origin: "platform" | "session";
+    /** Recorded earlier as real and deliberately left as it is. */
+    leftAsIs: boolean;
 }
 declare const FORMAT: {
     summary: string;
@@ -43,6 +45,11 @@ declare const FORMAT: {
         file: string;
         line: number;
     }[];
+    leftAsIs: {
+        rule: string;
+        file: string;
+        line: number;
+    }[];
     fixed: {
         rule: string;
         file: string;
@@ -78,6 +85,11 @@ export interface Report {
         file: string;
         line: number;
     }[];
+    leftAsIs: {
+        rule: string;
+        file: string;
+        line: number;
+    }[];
     fixed: {
         rule: string;
         file: string;

package/dist/commands/session-review.js

@@ -79,7 +79,7 @@ async function openFindings(api, base) {
     for (const f of got?.review?.findings ?? []) {
         if (typeof f.rule_id !== "string" || !REVIEW_RULES.includes(f.rule_id) || typeof f.file !== "string" || !SAFE_FILE.test(f.file) || !Number.isInteger(f.line))
             continue;
-        out.push({ rule_id: f.rule_id, file: f.file, line: f.line, origin: f.origin === "session" ? "session" : "platform" });
+        out.push({ rule_id: f.rule_id, file: f.file, line: f.line, origin: f.origin === "session" ? "session" : "platform", leftAsIs: f.leftAsIs === true });
     }
     return out;
 }
@@ -88,6 +88,7 @@ const FORMAT = {
     does: ["Up to six short phrases, each something a person can do in the app today"],
     missing: ["Up to five short phrases, each something the owner asked for or the description promises that is not built yet"],
     findings: [{ rule: "review/<id>", file: "src/server/index.ts", line: 42 }],
+    leftAsIs: [{ rule: "review/<id>", file: "src/server/index.ts", line: 42 }],
     fixed: [{ rule: "review/<id>", file: "src/server/index.ts" }],
     dismissed: [{ rule: "review/<id>", file: "src/server/index.ts" }],
 };
@@ -98,7 +99,7 @@ export function checklistText(c) {
         "This is the review of this app's own code for what tests cannot see. You do it, as part of the work. nerdsystem reads the code itself only now and then, and compares what it finds with what you report here.",
         "",
         "How to do it:",
-        "1. Use a reviewer with fresh eyes when you have one. In Claude Code, hand this whole output to the `nerd-reviewer` subagent that ships with the app (if it is not there yet, any read-only subagent). In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself and read the files again from disk, not from memory.",
+        "1. Use a reviewer with fresh eyes when you have one. In Claude Code, give this output to the `nerd-reviewer` subagent that ships with the app, either pasted or saved to a file it can read (`nerd review checklist > .nerd/checklist.txt`). If the session says that subagent is not found, it was added after the session started: give a read-only subagent the file `.claude/agents/nerd-reviewer.md` as its instructions. In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself and read the files again from disk, not from memory.",
         c.first
             ? "2. No review has been reported from this folder yet, so read all of the app's own code: `src/server` and the database schema first, then `src/client`, plus README.md."
             : c.changed.length
@@ -114,14 +115,14 @@ export function checklistText(c) {
     if (c.open.length) {
         lines.push("Open from earlier reviews. Check each against the code as it is now and answer it in the report:");
         for (const f of c.open)
-            lines.push(`- ${f.rule_id} at ${f.file}:${f.line}${f.origin === "platform" ? "  (from nerdsystem's own read)" : ""}`);
+            lines.push(`- ${f.rule_id} at ${f.file}:${f.line}${f.origin === "platform" ? "  (first raised by nerdsystem's own read)" : ""}${f.leftAsIs ? "  (recorded as left as it is; it stays that way unless you report it differently)" : ""}`);
         lines.push("");
     }
     lines.push("What to look for:");
     for (const r of c.rules) {
         lines.push(`- ${r.rule_id}: ${r.title}${r.audience === "human" ? " [for the person to decide]" : ""}`, `  Look for: ${r.lookFor}`, `  Fix: ${r.fix}`);
     }
-    lines.push("", `The report, written to ${c.reportFile}:`, JSON.stringify(c.format, null, 2), "", "- findings: what is still in the code after your fixes, each with the rule, the file, and the line that shows it. Leave it empty when there is nothing.", "- fixed: what this review found and you then fixed, including findings from the open list above.", "- dismissed: only for a finding from nerdsystem's own read that you checked against the code and that does not apply. The owner sees this as your judgement, so use it when you are sure.", "- A finding from nerdsystem's own read that the report does not mention stays open.", "- summary, does, missing are for the owner and are shown on their dashboard as written. Plain words only.", "", "Report what you found, not what would look good. The report is stored as this agent's own review, it never decides whether a deploy goes out, and a clean report that nerdsystem's own read later contradicts is recorded as a miss.");
+    lines.push("", `The report, written to ${c.reportFile}:`, JSON.stringify(c.format, null, 2), "", "- findings: what is still in the code after your fixes and still needs someone to act or decide, each with the rule, the file, and the line that shows it. Leave it empty when there is nothing. A finding marked [for the person to decide] stays here until they have answered.", "- leftAsIs: what is real and deliberately left as it is, because the person decided so or because the rule's own advice is not to change working code for it. Any finding can go here, whoever first raised it. It is shown to the owner, kept on later reports, and not announced again to each new session.", "- fixed: what this review found and you then fixed, including findings from the open list above. If you fixed only part of one, list what remains under findings (or leftAsIs) at the line that still shows it, and do not list it as fixed.", "- dismissed: only for a finding from nerdsystem's own read that you checked against the code and that does not apply. The owner sees this as your judgement, so use it when you are sure.", "- A finding from nerdsystem's own read that the report does not mention stays open.", "- summary, does, missing are for the owner and are shown on their dashboard as written. Plain words only.", "", "Report what you found, not what would look good. The report is stored as this agent's own review, it never decides whether a deploy goes out, and a clean report that nerdsystem's own read later contradicts is recorded as a miss.");
     return lines.join("\n");
 }
 /** `nerd review checklist`: what the agent reads before it reviews. */
@@ -182,17 +183,22 @@ export function parseReport(text, files, lineCount) {
         }
         return v.map((x) => (x && typeof x === "object" ? x : {}));
     };
-    const findings = [];
-    list("findings").forEach((f, i) => {
-        const where = `findings[${i}]`;
-        const id = rule(f.rule, where);
-        if (typeof f.file !== "string" || !(f.file in files))
-            return void problems.push(`${where}: "${String(f.file).slice(0, 80)}" is not a file a review reads (the app's own code under src/, README.md, package.json), or it does not exist`);
-        if (typeof f.line !== "number" || !Number.isInteger(f.line) || f.line < 1 || f.line > lineCount(f.file))
-            return void problems.push(`${where}: line ${String(f.line)} is not a line of ${f.file}`);
-        if (id)
-            findings.push({ rule: id, file: f.file, line: f.line });
-    });
+    const placed = (key) => {
+        const out = [];
+        list(key).forEach((f, i) => {
+            const where = `${key}[${i}]`;
+            const id = rule(f.rule, where);
+            if (typeof f.file !== "string" || !(f.file in files))
+                return void problems.push(`${where}: "${String(f.file).slice(0, 80)}" is not a file a review reads (the app's own code under src/, README.md, package.json), or it does not exist`);
+            if (typeof f.line !== "number" || !Number.isInteger(f.line) || f.line < 1 || f.line > lineCount(f.file))
+                return void problems.push(`${where}: line ${String(f.line)} is not a line of ${f.file}`);
+            if (id)
+                out.push({ rule: id, file: f.file, line: f.line });
+        });
+        return out;
+    };
+    const findings = placed("findings");
+    const leftAsIs = placed("leftAsIs");
     const notes = (key) => {
         const out = [];
         list(key).forEach((f, i) => {
@@ -222,7 +228,7 @@ export function parseReport(text, files, lineCount) {
         problems.push("summary must be a sentence or two of plain text");
     if (problems.length)
         throw new CliError(`${REPORT_FILE} needs ${problems.length === 1 ? "a correction" : "corrections"} before it can be sent:\n${problems.map((p) => `  - ${p}`).join("\n")}\nFix the file and run \`nerd review report\` again.`);
-    return { findings, fixed, dismissed, ...(typeof r.summary === "string" && r.summary.trim() ? { summary: r.summary.slice(0, 2000) } : {}), ...(does ? { does } : {}), ...(missing ? { missing } : {}) };
+    return { findings, leftAsIs, fixed, dismissed, ...(typeof r.summary === "string" && r.summary.trim() ? { summary: r.summary.slice(0, 2000) } : {}), ...(does ? { does } : {}), ...(missing ? { missing } : {}) };
 }
 /** The name sent with a report. Only an agent this CLI can recognise for certain is named without being told. */
 function agentName(given) {
@@ -253,7 +259,7 @@ export async function reviewReport(opts) {
     if (opts.json)
         return printJson({ accepted: answer.accepted, dropped: answer.dropped, carried: answer.carried, source: saved.source.id, dashboard: page });
     const a = answer.accepted;
-    log.ok(`Review reported for ${nerd.org}/${nerd.project}: ${a.findings} open, ${a.fixed} fixed${a.dismissed ? `, ${a.dismissed} judged not to apply` : ""}.`);
+    log.ok(`Review reported for ${nerd.org}/${nerd.project}: ${a.findings} open, ${a.fixed} fixed${a.leftAsIs ? `, ${a.leftAsIs} left as they are` : ""}${a.dismissed ? `, ${a.dismissed} judged not to apply` : ""}.`);
     if (answer.dropped)
         log.warn(`${answer.dropped} finding(s) were left out because the rule, the file, or the line did not match the stored code.`);
     if (answer.carried)

package/dist/commands/status.d.ts

@@ -19,6 +19,7 @@ export interface Attention {
 /** What is open from the latest review of this app (its agent's own, or the platform's read), mapped through this CLI's own catalog. */
 export declare function reviewItems(api: ApiClient, base: string): Promise<{
     items: AttentionItem[];
+    left: AttentionItem[];
     reviewedAt?: string;
 }>;
 /**

package/dist/commands/status.js

@@ -4,7 +4,7 @@ import { ApiClient } from "../api.js";
 import { RULES } from "../gates/rules.js";
 import { currentVersions, pinned, versionFindings } from "../gates/versions.js";
 import { findProjectRoot, projectPath, readNerdJson } from "../project.js";
-import { log } from "../util.js";
+import { localDay, log } from "../util.js";
 import { cliVersion } from "./source.js";
 const within = (p, ms) => Promise.race([p.catch(() => null), new Promise((r) => setTimeout(() => r(null), ms))]);
 const item = (rule_id, extra = {}) => {
@@ -16,16 +16,18 @@ export async function reviewItems(api, base) {
     const got = await within(api.get(`${base}/review`), 5000);
     const review = got?.review;
     if (!review || review.status !== "done")
-        return { items: [] };
+        return { items: [], left: [] };
     const items = [];
+    // Recorded as real and deliberately left as they are: kept for whoever asks, not announced to every new session.
+    const left = [];
     for (const f of review.findings ?? []) {
         if (typeof f.rule_id !== "string" || !f.rule_id.startsWith("review/") || typeof f.file !== "string" || !/^[\w./@-]{1,200}$/.test(f.file) || !Number.isInteger(f.line))
             continue;
         const it = item(f.rule_id, { where: `${f.file}:${f.line}` });
         if (it)
-            items.push(it);
+            (f.leftAsIs === true ? left : items).push(it);
     }
-    return { items, reviewedAt: review.createdAt };
+    return { items, left, reviewedAt: review.createdAt };
 }
 /**
  * Everything the platform has noticed about this app that someone should act on, gathered in a few
@@ -92,7 +94,7 @@ export function attentionText(a) {
         }
     }
     if (a.reviewedAt)
-        lines.push("", `Findings with a file and a line come from the latest review of this app (${a.reviewedAt.slice(0, 10)}): the one its coding agent reported, or nerdsystem's own read of the code. A review is a second opinion and can be wrong, and code changed since may already have fixed one: read the code at each place before changing anything, and say what you did about each in the next \`nerd review report\`.`);
+        lines.push("", `Findings with a file and a line come from the latest review of this app (${localDay(a.reviewedAt)}): the one its coding agent reported, or nerdsystem's own read of the code. A review is a second opinion and can be wrong, and code changed since may already have fixed one: read the code at each place before changing anything, and say what you did about each in the next \`nerd review report\`.`);
     lines.push("", "Before starting on what the person asked for, tell them about these in one or two plain sentences, with no file names or jargon, and offer to take care of them. If they say yes, fix what is real, run `nerd check`, and deploy. Anything marked for the person to decide, put to them as a plain question and wait for the answer. If they would rather get on with their own request, do that first and remind them once at the end.");
     return lines.join("\n");
 }
@@ -132,9 +134,12 @@ export async function review(opts) {
         log.info("No review of this app yet. Run `nerd review checklist` to do one before the next deploy.");
         return;
     }
+    const leftLines = r.left.length ? ["", "Known and deliberately left as they are (recorded in an earlier review; nothing to do unless the code around them changes):", ...r.left.map((it) => `- ${it.title} (${it.where})`)] : [];
     if (!r.items.length) {
-        log.ok(`Nothing is open from the latest review (${r.reviewedAt.slice(0, 10)}).`);
+        log.ok(`Nothing is open from the latest review (${localDay(r.reviewedAt)}).`);
+        if (leftLines.length)
+            process.stdout.write(`${leftLines.slice(1).join("\n")}\n`);
         return;
     }
-    process.stdout.write(`${attentionText({ app: `${nerd.org}/${nerd.project}`, items: r.items, reviewedAt: r.reviewedAt })}\n`);
+    process.stdout.write(`${attentionText({ app: `${nerd.org}/${nerd.project}`, items: r.items, reviewedAt: r.reviewedAt })}${leftLines.length ? `\n${leftLines.join("\n")}` : ""}\n`);
 }

package/dist/commands/upgrade.js

@@ -1,8 +1,10 @@
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { findProjectRoot } from "../project.js";
 import { log } from "../util.js";
 import { renderAgentFiles } from "./agents.js";
+import { KNOWN_CLAUDE_MD } from "./claude-md-history.js";
 import { templateDir } from "./init.js";
 import { cliVersion } from "./source.js";
 /** Files that are the platform's, not the app's: replaced with the current version every time. */
@@ -75,9 +77,13 @@ export function upgradeProject(root, tpl, version) {
     // purpose, so it is carried over word for word.
     const seeded = oldClaude ? /^(# [^\n]*\n\n[\s\S]*?\n\n)## This app runs on nerdsystem\n/.exec(oldClaude) : null;
     const newClaude = tplClaude !== null && seeded ? seeded[1] + tplClaude.replace(/^# This app runs on nerdsystem\n/, "## This app runs on nerdsystem\n") : tplClaude;
+    // The platform's part of the old file, as the template had it: when that is word for word a version this
+    // project shipped, nobody has added anything, and there is nothing to keep.
+    const oldPlatformText = oldClaude === null ? null : seeded ? oldClaude.slice(seeded[1].length).replace(/^## This app runs on nerdsystem\n/, "# This app runs on nerdsystem\n") : oldClaude;
+    const untouched = oldPlatformText !== null && KNOWN_CLAUDE_MD.has(createHash("sha256").update(oldPlatformText).digest("hex"));
     let keptOld = false;
     if (newClaude !== null && oldClaude !== newClaude) {
-        if (oldClaude !== null && !existsSync(path.join(root, "CLAUDE.previous.md"))) {
+        if (oldClaude !== null && !untouched && !existsSync(path.join(root, "CLAUDE.previous.md"))) {
             renameSync(path.join(root, "CLAUDE.md"), path.join(root, "CLAUDE.previous.md"));
             changed.push("CLAUDE.previous.md");
             keptOld = true;
@@ -113,6 +119,8 @@ export function upgradeProject(root, tpl, version) {
     const next = ["Run `pnpm install`.", "Run `nerd check` and work through what it reports. It names what this app's own code should adopt (for example sign-in for every route, checked input, access tests)."];
     if (startersWritten.includes("test/access.test.ts"))
         next.push("`test/access.test.ts` is the starter's: keep the first test, and rewrite the owner test for this app's own routes. Then set `\"tests\": \"required\"` in nerd.json.");
+    if (changed.includes(".claude/agents/nerd-reviewer.md"))
+        next.push("A reviewer for Claude Code was added or updated at `.claude/agents/nerd-reviewer.md`. Claude Code loads it when a session starts, so a session that was already open will say it is not found: until the next session, give a read-only subagent that file as its instructions.");
     if (keptOld)
         next.push("Your earlier `CLAUDE.md` is now `CLAUDE.previous.md`. Move anything the person added into the new `CLAUDE.md`, then delete the old file.");
     next.push("Tell the person in plain words what changed, then run `nerd deploy` when the check passes.");

package/dist/commands/verify.js

@@ -4,7 +4,7 @@ import { ApiClient } from "../api.js";
 import { BUILD_GATES, gateSummary, knownSecretsFrom, runGates, skippedGates, SOURCE_GATES } from "../gates/index.js";
 import { findProjectRoot, projectPath, readDevVars, readNerdJson } from "../project.js";
 import { CliError, log } from "../util.js";
-import { readBuildOutput } from "./deploy.js";
+import { dropLocalSecretCopies, readBuildOutput } from "./deploy.js";
 /** Suppressions a human approved in the dashboard, so they stop being reported. Best effort. */
 export async function approvedSuppressions(root) {
     try {
@@ -28,6 +28,7 @@ export async function runVerify(root, opts) {
     let stop = source.capped;
     if (opts.withBuild && source.ok && existsSync(path.join(root, "dist"))) {
         const build = readBuildOutput(root);
+        dropLocalSecretCopies(build);
         const built = await runGates(BUILD_GATES.filter((g) => g.name !== "policy"), { ...ctxBase, build }, { stopOnFail: opts.stopOnFail, trackAttempts: false });
         results = [...results, ...built.results];
         failures = [...failures, ...built.failures];

package/dist/gates/design.js

@@ -108,6 +108,9 @@ export function designFindings(root, files, routes, authPath = "/api/auth") {
         for (const p of patterns) {
             if (SYSTEM.has(p.path))
                 continue;
+            // A webhook or a callback is called by another service, never by a screen.
+            if (/\/(webhooks?|callbacks?)(\/|$)/.test(p.path))
+                continue;
             if (endings.some((e) => p.path.endsWith(e)))
                 continue;
             // The route's name passed the same strict pattern as every other route name read from the report.

package/dist/gates/review.js

@@ -3,6 +3,7 @@ import { reviewDue } from "../commands/session-review.js";
 import { reviewItems } from "../commands/status.js";
 import { projectPath, readNerdJson } from "../project.js";
 import { finding } from "./secrets.js";
+import { localDay } from "../util.js";
 import { counts, result, verdict } from "./types.js";
 /**
  * Brings the review of this app into the same list as every other check, so an agent meets it in the
@@ -44,7 +45,7 @@ export const reviewGate = {
         }
         if (due)
             findings.push(finding("session/review-due", { verify: "nerd review report" }));
-        const when = got.reviewedAt?.slice(0, 10);
+        const when = got.reviewedAt ? localDay(got.reviewedAt) : undefined;
         const said = [open ? `${open} open from the review of ${when}; a second opinion that can be wrong, so read the code first` : when ? `Nothing open from the review of ${when}` : "No review yet", ...(due ? [first ? "no review has been reported from this folder: run nerd review checklist" : "code has changed since the last review: run nerd review checklist"] : [])];
         return result(this, verdict(findings), findings.length ? `${counts(findings)}: ${said.join("; ")}` : said.join("; "), findings, t);
     },

package/dist/gates/versions.js

@@ -114,7 +114,9 @@ export const versionsGate = {
             // no package.json: the rules gate says so
         }
         const findings = versionFindings({ cli: installedCli(), sdk, versions, inBuilder: Boolean(ctx.committed) });
-        const summary = findings.length ? findings.map((f) => f.rule_id.split("/")[1]).join(", ") : versions.latest ? `nerd and the SDK are current (${versions.latest})` : "Nothing older than the platform accepts";
+        // The platform's answer is kept for a day, so straight after an update this copy can be newer than the "latest" it remembers.
+        const shown = versions.latest && compareVersions(installedCli(), versions.latest) > 0 ? installedCli() : versions.latest;
+        const summary = findings.length ? findings.map((f) => f.rule_id.split("/")[1]).join(", ") : shown ? `nerd and the SDK are current (${shown})` : "Nothing older than the platform accepts";
         return result(this, verdict(findings), summary, findings, t);
     },
 };

package/dist/util.d.ts

@@ -29,6 +29,8 @@ export declare function runOrThrow(cmd: string, args: string[], opts?: RunOption
 export declare function printJson(value: unknown): void;
 export declare function table(rows: Record<string, unknown>[], columns: string[]): void;
 /** The dashboard that goes with an API origin (https://api.nerdsystem.com -> https://nerdsystem.com). */
+/** The calendar day of a timestamp where the person is, as YYYY-MM-DD. The platform's times are UTC, which is tomorrow for part of every evening in the Americas. */
+export declare function localDay(iso: string): string;
 export declare function dashboardUrl(apiUrl: string): string;
 /** Stops with one sentence instead of npx noise when `pnpm install` has not been run. */
 export declare function ensureDeps(root: string): void;

package/dist/util.js

@@ -49,6 +49,14 @@ export function table(rows, columns) {
         process.stdout.write(`${line(columns.map((c) => String(r[c] ?? "")))}\n`);
 }
 /** The dashboard that goes with an API origin (https://api.nerdsystem.com -> https://nerdsystem.com). */
+/** The calendar day of a timestamp where the person is, as YYYY-MM-DD. The platform's times are UTC, which is tomorrow for part of every evening in the Americas. */
+export function localDay(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso.slice(0, 10);
+    const two = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
+}
 export function dashboardUrl(apiUrl) {
     return apiUrl.replace(/\/$/, "").replace(/^https?:\/\/api\./, "https://");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nerdsystem",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "nerd: start, check, and deploy a web app on nerdsystem from the terminal or a coding agent.",
   "type": "module",
   "bin": {

package/template/.claude/agents/nerd-reviewer.md

@@ -6,7 +6,7 @@ tools: Read, Grep, Glob
 
 You review the source code of a small web app that a coding agent built for someone who cannot read code. The app runs on nerdsystem, where every app has one shape: a React client in `src/client`, a Hono server in `src/server` whose routes live under `/api`, a SQLite database described by the Drizzle schema in `src/server/db/schema.ts`, and sign-in provided by the platform (the signed-in user is `c.var.user`; `requireAuth()` and `requireRole()` guard routes).
 
-You are given the output of `nerd review checklist`: the files to read, the findings still open from earlier reviews, and the kinds of problem to look for. If you were not given it, say so and stop.
+You are given the output of `nerd review checklist`, or the path of a file that holds it: the files to read, the findings still open from earlier reviews, and the kinds of problem to look for. If you were given neither, say so and stop.
 
 ## How to review
 

package/template/.claude/skills/nerdsystem/SKILL.md

@@ -135,8 +135,8 @@ What the tests do not prove: that the feature is the one the person wanted, or t
 Tests show the app does what was checked. They cannot show that the server trusts a price the browser sent, that any signed-in person can approve what only staff should, or that two people can book the same slot. Looking for those is your job, before every deploy that changes the server, the data model, or what a screen does. Nobody else reads each change: nerdsystem reads the code itself only now and then.
 
 1. Run `nerd review checklist`. It prints what to look for (the `review/` rules), the files that changed since the last review, the findings still open from earlier reviews, and the format of the report.
-2. Have it done with fresh eyes. In Claude Code, give the whole checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/` (it only reads; if this session does not have it yet, use any read-only subagent). In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
-3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer.
+2. Have it done with fresh eyes. In Claude Code, give the checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/`, pasted or saved to a file it can read (it only reads). If the session says that subagent is not found, it was added after the session started: give a read-only subagent the file `.claude/agents/nerd-reviewer.md` as its instructions. In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
+3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer. Something real that the person decides to leave, or that the rule itself says is not worth changing working code for, goes in the report as `leftAsIs`: it is shown to them, kept, and not raised again at the start of every session.
 4. Write `.nerd/review.json` as the checklist describes and run `nerd review report`. Then `nerd check` and `nerd deploy`.
 
 The report is stored as your review, and the person sees it in their dashboard under Review together with the plain-language summary you wrote for them, so write that for someone who cannot read code. Report what you found, including what you fixed. When nerdsystem does read the code itself, it compares: a finding from its read stays open until your report says it is still there, fixed, or checked and not applicable, and a clean report it then contradicts is recorded as a miss. Never report a review you did not do, and never use `dismissed` to make a finding go away.

package/template/.cursor/rules/nerdsystem.mdc

@@ -2,7 +2,7 @@
 description: How to build, run, and deploy this app on nerdsystem. Applies to server, database, auth, and deploy work.
 alwaysApply: true
 ---
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (1e4962fc7891); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (0649a59fb02c); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -136,8 +136,8 @@ What the tests do not prove: that the feature is the one the person wanted, or t
 Tests show the app does what was checked. They cannot show that the server trusts a price the browser sent, that any signed-in person can approve what only staff should, or that two people can book the same slot. Looking for those is your job, before every deploy that changes the server, the data model, or what a screen does. Nobody else reads each change: nerdsystem reads the code itself only now and then.
 
 1. Run `nerd review checklist`. It prints what to look for (the `review/` rules), the files that changed since the last review, the findings still open from earlier reviews, and the format of the report.
-2. Have it done with fresh eyes. In Claude Code, give the whole checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/` (it only reads; if this session does not have it yet, use any read-only subagent). In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
-3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer.
+2. Have it done with fresh eyes. In Claude Code, give the checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/`, pasted or saved to a file it can read (it only reads). If the session says that subagent is not found, it was added after the session started: give a read-only subagent the file `.claude/agents/nerd-reviewer.md` as its instructions. In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
+3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer. Something real that the person decides to leave, or that the rule itself says is not worth changing working code for, goes in the report as `leftAsIs`: it is shown to them, kept, and not raised again at the start of every session.
 4. Write `.nerd/review.json` as the checklist describes and run `nerd review report`. Then `nerd check` and `nerd deploy`.
 
 The report is stored as your review, and the person sees it in their dashboard under Review together with the plain-language summary you wrote for them, so write that for someone who cannot read code. Report what you found, including what you fixed. When nerdsystem does read the code itself, it compares: a finding from its read stays open until your report says it is still there, fixed, or checked and not applicable, and a clean report it then contradicts is recorded as a miss. Never report a review you did not do, and never use `dismissed` to make a finding go away.

package/template/.github/copilot-instructions.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (1e4962fc7891); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (0649a59fb02c); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -132,8 +132,8 @@ What the tests do not prove: that the feature is the one the person wanted, or t
 Tests show the app does what was checked. They cannot show that the server trusts a price the browser sent, that any signed-in person can approve what only staff should, or that two people can book the same slot. Looking for those is your job, before every deploy that changes the server, the data model, or what a screen does. Nobody else reads each change: nerdsystem reads the code itself only now and then.
 
 1. Run `nerd review checklist`. It prints what to look for (the `review/` rules), the files that changed since the last review, the findings still open from earlier reviews, and the format of the report.
-2. Have it done with fresh eyes. In Claude Code, give the whole checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/` (it only reads; if this session does not have it yet, use any read-only subagent). In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
-3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer.
+2. Have it done with fresh eyes. In Claude Code, give the checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/`, pasted or saved to a file it can read (it only reads). If the session says that subagent is not found, it was added after the session started: give a read-only subagent the file `.claude/agents/nerd-reviewer.md` as its instructions. In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
+3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer. Something real that the person decides to leave, or that the rule itself says is not worth changing working code for, goes in the report as `leftAsIs`: it is shown to them, kept, and not raised again at the start of every session.
 4. Write `.nerd/review.json` as the checklist describes and run `nerd review report`. Then `nerd check` and `nerd deploy`.
 
 The report is stored as your review, and the person sees it in their dashboard under Review together with the plain-language summary you wrote for them, so write that for someone who cannot read code. Report what you found, including what you fixed. When nerdsystem does read the code itself, it compares: a finding from its read stays open until your report says it is still there, fixed, or checked and not applicable, and a clean report it then contradicts is recorded as a miss. Never report a review you did not do, and never use `dismissed` to make a finding go away.

package/template/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (1e4962fc7891); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (0649a59fb02c); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -132,8 +132,8 @@ What the tests do not prove: that the feature is the one the person wanted, or t
 Tests show the app does what was checked. They cannot show that the server trusts a price the browser sent, that any signed-in person can approve what only staff should, or that two people can book the same slot. Looking for those is your job, before every deploy that changes the server, the data model, or what a screen does. Nobody else reads each change: nerdsystem reads the code itself only now and then.
 
 1. Run `nerd review checklist`. It prints what to look for (the `review/` rules), the files that changed since the last review, the findings still open from earlier reviews, and the format of the report.
-2. Have it done with fresh eyes. In Claude Code, give the whole checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/` (it only reads; if this session does not have it yet, use any read-only subagent). In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
-3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer.
+2. Have it done with fresh eyes. In Claude Code, give the checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/`, pasted or saved to a file it can read (it only reads). If the session says that subagent is not found, it was added after the session started: give a read-only subagent the file `.claude/agents/nerd-reviewer.md` as its instructions. In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
+3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer. Something real that the person decides to leave, or that the rule itself says is not worth changing working code for, goes in the report as `leftAsIs`: it is shown to them, kept, and not raised again at the start of every session.
 4. Write `.nerd/review.json` as the checklist describes and run `nerd review report`. Then `nerd check` and `nerd deploy`.
 
 The report is stored as your review, and the person sees it in their dashboard under Review together with the plain-language summary you wrote for them, so write that for someone who cannot read code. Report what you found, including what you fixed. When nerdsystem does read the code itself, it compares: a finding from its read stays open until your report says it is still there, fixed, or checked and not applicable, and a clean report it then contradicts is recorded as a miss. Never report a review you did not do, and never use `dismissed` to make a finding go away.

package/template/GEMINI.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (1e4962fc7891); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (0649a59fb02c); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -132,8 +132,8 @@ What the tests do not prove: that the feature is the one the person wanted, or t
 Tests show the app does what was checked. They cannot show that the server trusts a price the browser sent, that any signed-in person can approve what only staff should, or that two people can book the same slot. Looking for those is your job, before every deploy that changes the server, the data model, or what a screen does. Nobody else reads each change: nerdsystem reads the code itself only now and then.
 
 1. Run `nerd review checklist`. It prints what to look for (the `review/` rules), the files that changed since the last review, the findings still open from earlier reviews, and the format of the report.
-2. Have it done with fresh eyes. In Claude Code, give the whole checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/` (it only reads; if this session does not have it yet, use any read-only subagent). In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
-3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer.
+2. Have it done with fresh eyes. In Claude Code, give the checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/`, pasted or saved to a file it can read (it only reads). If the session says that subagent is not found, it was added after the session started: give a read-only subagent the file `.claude/agents/nerd-reviewer.md` as its instructions. In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
+3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer. Something real that the person decides to leave, or that the rule itself says is not worth changing working code for, goes in the report as `leftAsIs`: it is shown to them, kept, and not raised again at the start of every session.
 4. Write `.nerd/review.json` as the checklist describes and run `nerd review report`. Then `nerd check` and `nerd deploy`.
 
 The report is stored as your review, and the person sees it in their dashboard under Review together with the plain-language summary you wrote for them, so write that for someone who cannot read code. Report what you found, including what you fixed. When nerdsystem does read the code itself, it compares: a finding from its read stays open until your report says it is still there, fixed, or checked and not applicable, and a clean report it then contradicts is recorded as a miss. Never report a review you did not do, and never use `dismissed` to make a finding go away.