nerdsystem 0.0.19 → 0.0.21

package/dist/cli.js

@@ -8,6 +8,7 @@ import { doctor } from "./commands/doctor.js";
 import { cron, health, rollback, secretList, secretRemove, secretSet, transfer, waitlist } from "./commands/ops.js";
 import { adminHelp, adminSuspend, adminUnsuspend } from "./commands/admin.js";
 import { agentsSync } from "./commands/agents.js";
+import { upgrade } from "./commands/upgrade.js";
 import { billingPortal, billingShow, billingUpgrade } from "./commands/billing.js";
 import { auditExport, clientsCreate, clientsList, clientsRelease, domainsAdd, domainsList, domainsRemove, logs, membersInvite, membersList, membersRemove } from "./commands/org.js";
 import { buildsList, buildsShow, buildsTrigger } from "./commands/builds.js";
@@ -57,6 +58,7 @@ const HELP = `nerd: start, check, and deploy a web app on nerdsystem
   nerd builds show <id>               Build details and log
   nerd builds trigger [--branch b] [--commit sha]
   nerd agents sync                    Regenerate AGENTS.md, Cursor, Copilot, Gemini files from the skill
+  nerd upgrade                        Bring this app up to the current SDK, agent instructions, and test harness
   nerd billing [--org slug]           Plan, limits, and usage for the org
   nerd billing upgrade --plan pro|studio [--annual]   Start checkout
   nerd billing portal                 Manage cards, invoices, and plan
@@ -133,6 +135,10 @@ export async function main(argv) {
             const { values } = parse({ "skip-build": BOOL, "skip-probe": BOOL, force: BOOL, note: STR });
             return deploy(values);
         }
+        case "upgrade": {
+            const { values } = parse({}, false);
+            return upgrade({ json: Boolean(values.json) });
+        }
         case "save": {
             const { values } = parse({}, false);
             return save({ json: Boolean(values.json) });

package/dist/commands/deploy.js

@@ -9,6 +9,7 @@ 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 { 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";
 const MODULE_EXT = new Set([".js", ".mjs", ".wasm"]);
 function walk(dir, base = dir) {
@@ -224,8 +225,13 @@ export async function deploy(opts) {
     if (!built.ok)
         throw new CliError(`Blocked by: ${built.failed.map((g) => g.title).join(", ")}.`, 2);
     const r = await shipBuild({ root, nerd, api, build, results: [...gates.results, ...built.results], opts });
-    if (opts.json)
-        return printJson({ deployment: r.deployment, url: r.url, migrations: r.migrations, probes: r.probes, source: r.source, sourceSkipped: r.sourceSkipped, lineage: r.lineage.passed, warnings: r.warnings });
+    // The app is live at this point. The model review reads the stored code and is advice for the next change.
+    const reviewPage = `${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/review`;
+    const wantReview = r.deployment.status === "live" && Boolean(r.source);
+    if (opts.json) {
+        const review = wantReview ? await platformReview(api, `${projectPath(nerd)}/sources/${r.source.id}`, reviewPage) : null;
+        return printJson({ deployment: r.deployment, url: r.url, 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);
     if (r.deployment.status === "live") {
         if (r.deployment.sourceId)
@@ -233,6 +239,10 @@ export async function deploy(opts) {
         else
             log.warn(sourceLine(r));
     }
+    if (wantReview) {
+        log.step("Your app is live. Asking for a model review of how it is put together (up to 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.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) {

package/dist/commands/init.d.ts

@@ -1,4 +1,5 @@
 import { type Project } from "../api.js";
+export declare function templateDir(): string;
 /** Creates the remote project and writes nerd.json. Shared by init and link. */
 export declare function linkProject(root: string, args: {
     org?: string;

package/dist/commands/init.js

@@ -6,7 +6,7 @@ import { ApiClient } from "../api.js";
 import { projectPath, writeNerdJson } from "../project.js";
 import { CliError, log, printJson } from "../util.js";
 const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$/;
-function templateDir() {
+export function templateDir() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
         process.env.NERD_TEMPLATE_DIR,
@@ -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.19";
+const SDK_VERSION = "0.0.21";

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

@@ -0,0 +1,29 @@
+import type { ApiClient } from "../api.js";
+export interface ReviewFindingOut {
+    rule_id: string;
+    severity: "block" | "warn" | "info";
+    audience: "agent" | "human";
+    file: string;
+    line: number;
+    risk: string;
+    fix: string;
+}
+export type ReviewOutcome = {
+    status: "done" | "declined";
+    findings: ReviewFindingOut[];
+    dashboard: string;
+} | {
+    status: "skipped";
+    reason: string;
+};
+/**
+ * After a deploy is live, asks the platform for the model's review of the stored code and waits for it.
+ *
+ * Only the findings come back into the terminal, and only as a rule id with a file and a line: the words
+ * printed are this CLI's own catalog, looked up by id, so nothing the model wrote is ever put in front of
+ * the agent reading this output. The model's plain-language summary is for the person and stays in the
+ * dashboard. Any failure, limit, or missing configuration is a skip with a reason; a review never changes
+ * whether the deploy succeeded.
+ */
+export declare function platformReview(api: ApiClient, sourcePath: string, dashboard: string): Promise<ReviewOutcome>;
+export declare function printReview(r: ReviewOutcome): void;

package/dist/commands/platform-review.js

@@ -0,0 +1,58 @@
+import { RULES } from "../gates/rules.js";
+import { CliError, log } from "../util.js";
+/**
+ * After a deploy is live, asks the platform for the model's review of the stored code and waits for it.
+ *
+ * Only the findings come back into the terminal, and only as a rule id with a file and a line: the words
+ * printed are this CLI's own catalog, looked up by id, so nothing the model wrote is ever put in front of
+ * the agent reading this output. The model's plain-language summary is for the person and stays in the
+ * dashboard. Any failure, limit, or missing configuration is a skip with a reason; a review never changes
+ * whether the deploy succeeded.
+ */
+export async function platformReview(api, sourcePath, dashboard) {
+    if (process.env.NERD_NO_REVIEW)
+        return { status: "skipped", reason: "turned off with NERD_NO_REVIEW" };
+    let review;
+    try {
+        review = (await api.post(`${sourcePath}/review`)).review;
+    }
+    catch (err) {
+        const status = err instanceof CliError ? err.status : undefined;
+        // The 402's wording is the platform's own (plan and allowance), safe to repeat.
+        if (status === 402 && err instanceof Error)
+            return { status: "skipped", reason: err.message.replace(/\s*\[[^\]]*\]\s*$/, "") };
+        return { status: "skipped", reason: status === 503 ? "the model review is not available on this platform yet" : "the review could not be completed this time" };
+    }
+    if (review.status !== "done")
+        return { status: "declined", findings: [], dashboard };
+    const findings = [];
+    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;
+        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 };
+}
+export function printReview(r) {
+    if (r.status === "skipped") {
+        log.info(`Model review: not run (${r.reason}).`);
+        return;
+    }
+    if (r.status === "declined") {
+        log.info("Model review: the reviewer gave no answer for this app.");
+        return;
+    }
+    if (!r.findings.length) {
+        log.ok(`Model review: nothing to raise. A plain-language summary for the person is at ${r.dashboard}`);
+        return;
+    }
+    log.warn(`Model review: ${r.findings.length} thing(s) to look at. This is a second opinion from a model reading the code, so check each one against the code before changing anything; it can be wrong.`);
+    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}`);
+        log.info(`      Fix: ${f.fix}`);
+    }
+    log.info(`A plain-language summary for the person is at ${r.dashboard}`);
+}

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,16 @@
+export interface UpgradeResult {
+    from: string | null;
+    to: string;
+    changed: string[];
+    next: string[];
+}
+/**
+ * Brings an existing app up to the current platform: the SDK version, the instructions the agent reads,
+ * and the test harness. It replaces only what the platform owns and never touches the app's own code;
+ * what the app's code should adopt is then reported by `nerd check`, as findings the agent works through.
+ * Nothing is installed, deployed, or sent anywhere.
+ */
+export declare function upgradeProject(root: string, tpl: string, version: string): UpgradeResult;
+export declare function upgrade(opts: {
+    json: boolean;
+}): Promise<void>;

package/dist/commands/upgrade.js

@@ -0,0 +1,114 @@
+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 { 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. */
+const OURS = [".claude/skills/nerdsystem/SKILL.md", "test/setup.ts", "test/global-setup.ts", "vitest.config.ts"];
+/** Files an app is expected to change: written only when the app has none. */
+const STARTERS = [
+    ["test/access.test.ts", "test/access.test.ts"],
+    ["pnpm-workspace.app.yaml", "pnpm-workspace.yaml"],
+];
+/**
+ * Brings an existing app up to the current platform: the SDK version, the instructions the agent reads,
+ * and the test harness. It replaces only what the platform owns and never touches the app's own code;
+ * what the app's code should adopt is then reported by `nerd check`, as findings the agent works through.
+ * Nothing is installed, deployed, or sent anywhere.
+ */
+export function upgradeProject(root, tpl, version) {
+    const changed = [];
+    const read = (p) => (existsSync(p) ? readFileSync(p, "utf8") : null);
+    const write = (rel, content) => {
+        const p = path.join(root, rel);
+        if (read(p) === content)
+            return;
+        mkdirSync(path.dirname(p), { recursive: true });
+        writeFileSync(p, content);
+        changed.push(rel);
+    };
+    const pkgPath = path.join(root, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const tplPkg = JSON.parse(readFileSync(path.join(tpl, "package.json"), "utf8"));
+    const before = JSON.stringify(pkg);
+    const current = pkg.dependencies?.["@nerdsystem/sdk"];
+    const from = /(\d+\.\d+\.\d+)/.exec(current ?? "")?.[1] ?? null;
+    pkg.dependencies ??= {};
+    pkg.devDependencies ??= {};
+    pkg.scripts ??= {};
+    // A workspace or file link is someone developing the platform itself; leave it alone.
+    if (!current || !/^(workspace|file|link):/.test(current))
+        pkg.dependencies["@nerdsystem/sdk"] = `^${version}`;
+    if (!pkg.dependencies.zod && tplPkg.dependencies?.zod)
+        pkg.dependencies.zod = tplPkg.dependencies.zod;
+    if (!pkg.devDependencies.vitest && tplPkg.devDependencies?.vitest)
+        pkg.devDependencies.vitest = tplPkg.devDependencies.vitest;
+    if (!pkg.scripts.test)
+        pkg.scripts.test = "vitest run";
+    if (JSON.stringify(pkg) !== before) {
+        writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+        changed.push("package.json");
+    }
+    for (const rel of OURS) {
+        const content = read(path.join(tpl, rel));
+        if (content !== null)
+            write(rel, content);
+    }
+    const startersWritten = [];
+    for (const [fromRel, toRel] of STARTERS) {
+        const content = read(path.join(tpl, fromRel));
+        if (content !== null && !existsSync(path.join(root, toRel))) {
+            write(toRel, content);
+            startersWritten.push(toRel);
+        }
+    }
+    // CLAUDE.md is the platform's text, but people and agents add notes to it. A changed one is kept beside the new one.
+    // Line endings are made the same first: a checkout on Windows may carry CRLF, and the heading match below
+    // and the "is it already current" comparison must not depend on that.
+    const lf = (t) => (t === null ? null : t.replace(/\r\n/g, "\n"));
+    const tplClaude = lf(read(path.join(tpl, "CLAUDE.md")));
+    const oldClaude = lf(read(path.join(root, "CLAUDE.md")));
+    // `nerd init` puts the app's name and the owner's description above the platform's text and demotes the
+    // platform's heading. That opening is the owner's, and it is what the model review reads as the app's
+    // 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;
+    let keptOld = false;
+    if (newClaude !== null && oldClaude !== newClaude) {
+        if (oldClaude !== null && !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;
+        }
+        write("CLAUDE.md", newClaude);
+    }
+    // The files other agents read are generated from the skill that was just replaced.
+    for (const [rel, content] of Object.entries(renderAgentFiles(root).files))
+        write(rel, content);
+    const ignore = read(path.join(root, ".gitignore")) ?? "";
+    if (!/^\.nerd\/?$/m.test(ignore))
+        write(".gitignore", `${ignore}${ignore.endsWith("\n") || !ignore ? "" : "\n"}.nerd/\n`);
+    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 (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.");
+    return { from, to: version, changed, next };
+}
+export async function upgrade(opts) {
+    const root = findProjectRoot();
+    const r = upgradeProject(root, templateDir(), cliVersion());
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        return;
+    }
+    if (!r.changed.length)
+        log.ok(`Already current with nerd ${r.to}. Nothing was changed.`);
+    else
+        log.ok(`Updated ${r.changed.length} file(s) for nerd ${r.to}${r.from && r.from !== r.to ? ` (the app was on SDK ${r.from})` : ""}: ${r.changed.join(", ")}`);
+    log.info("Your app's own code was not touched. Next:");
+    r.next.forEach((n, i) => log.info(`  ${i + 1}. ${n}`));
+}

package/dist/gates/design.d.ts

@@ -0,0 +1,20 @@
+import { type SourceFile } from "./fs.js";
+import { type Finding, type Gate } from "./types.js";
+/** The app's routes as the last test run saw them (exact, from the running app), or null without a report. */
+export declare function declaredRoutes(root: string): {
+    method: string;
+    path: string;
+}[] | null;
+/** Every "/api/..." the client names: a plain string, or a template whose ${...} parts stand for one segment each. */
+export declare function clientCalls(files: SourceFile[]): {
+    file: string;
+    line: number;
+    path: string;
+}[];
+/** The literal endings of addresses the client builds from a variable: "`${base}/ticks`" gives "/ticks". */
+export declare function clientEndings(files: SourceFile[]): string[];
+export declare function designFindings(root: string, files: SourceFile[], routes: {
+    method: string;
+    path: string;
+}[] | null, authPath?: string): Finding[];
+export declare const designGate: Gate;

package/dist/gates/design.js

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { lineOf, sourceFiles } from "./fs.js";
+import { finding } from "./secrets.js";
+import { counts, result, verdict } from "./types.js";
+/**
+ * How the app is put together: the things that work today, pass every test, and still go wrong later.
+ * A screen calling a route that is not there, a list that returns every row forever, money stored as a
+ * fraction, a table nothing uses. None of it can be seen from the screen, and the person who owns the
+ * app cannot read the code.
+ *
+ * Every check here leans on the one shape every app has (routes under src/server, the Drizzle schema in
+ * src/server/db/schema.ts, the client under src/client), which is what makes plain text analysis precise
+ * enough to be worth reading. All of it is advice: it never blocks a deploy. Findings carry a file and a
+ * line and words from the catalog only; nothing from the app's code is repeated to the agent.
+ */
+const CODE = /\.(ts|tsx|js|jsx|mjs)$/;
+const LONG_FILE_LINES = 400;
+/** Blanks out comments, keeping every character position. */
+function withoutComments(text) {
+    return text.replace(/\/\*[\s\S]*?\*\/|(^|[^:"'`\\])\/\/[^\n]*/g, (m) => m.replace(/[^\n]/g, " "));
+}
+/** "/api/todos/:id" → a pattern; ":id" and "*" match one or more characters of a segment. */
+function routePattern(p) {
+    return new RegExp(`^${p.split("/").map((seg) => (seg.startsWith(":") ? "[^/]+" : seg === "*" ? ".*" : seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))).join("/")}/?$`);
+}
+/** The app's routes as the last test run saw them (exact, from the running app), or null without a report. */
+export function declaredRoutes(root) {
+    try {
+        const report = JSON.parse(readFileSync(path.join(root, ".nerd/access-report.json"), "utf8"));
+        if (!Array.isArray(report.routes))
+            return null;
+        const out = [];
+        for (const r of report.routes) {
+            const m = typeof r === "string" ? /^(GET|POST|PUT|PATCH|DELETE) (\/[A-Za-z0-9/:_.*-]{0,120})$/.exec(r) : null;
+            if (m)
+                out.push({ method: m[1], path: m[2] });
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every "/api/..." the client names: a plain string, or a template whose ${...} parts stand for one segment each. */
+export function clientCalls(files) {
+    const out = [];
+    const re = /(["'`])(\/api\/[^"'`\s?#]*)/g;
+    for (const f of files) {
+        if (!f.rel.startsWith("src/client/") || !CODE.test(f.rel))
+            continue;
+        const text = withoutComments(f.text);
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(text))) {
+            // A template part becomes a made-up segment; a path that is nothing but a prefix ("/api/") is someone building a URL, not a call.
+            const p = m[2].replace(/\$\{[^}]*\}/g, "x").replace(/\/$/, "");
+            if (p.split("/").length >= 3 && p !== "/api")
+                out.push({ file: f.rel, line: lineOf(text, m.index), path: p });
+        }
+    }
+    return out;
+}
+/** The literal endings of addresses the client builds from a variable: "`${base}/ticks`" gives "/ticks". */
+export function clientEndings(files) {
+    const out = new Set();
+    const re = /\$\{[^}]+\}((?:\/[A-Za-z0-9_-]+)+)\/?[`"'?]/g;
+    for (const f of files) {
+        if (!f.rel.startsWith("src/client/") || !CODE.test(f.rel))
+            continue;
+        const text = withoutComments(f.text);
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(text)))
+            out.add(m[1]);
+    }
+    return [...out];
+}
+/** Tables in the schema: name of the export, where it starts, and its text. */
+function tables(schema) {
+    const out = [];
+    const re = /export\s+const\s+(\w+)\s*=\s*sqliteTable\s*\(/g;
+    let m;
+    while ((m = re.exec(schema))) {
+        // Up to the next table or the end: good enough to ask what one table contains.
+        const next = schema.slice(m.index + 1).search(/export\s+const\s+\w+\s*=\s*sqliteTable\s*\(/);
+        out.push({ name: m[1], index: m.index, body: schema.slice(m.index, next < 0 ? undefined : m.index + 1 + next) });
+    }
+    return out;
+}
+export function designFindings(root, files, routes, authPath = "/api/auth") {
+    const findings = [];
+    const add = (rule, file, line) => findings.push(finding(rule, { file, ...(line ? { line } : {}), fingerprint: `${rule}:${file}:${line ?? 0}` }));
+    // 1 and 2. What the screens call against what the server has.
+    if (routes) {
+        const patterns = routes.map((r) => ({ ...r, re: routePattern(r.path) }));
+        const calls = clientCalls(files);
+        for (const c of calls) {
+            if (c.path === authPath || c.path.startsWith(`${authPath}/`))
+                continue;
+            if (!patterns.some((p) => p.re.test(c.path)))
+                add("design/unknown-route", c.file, c.line);
+        }
+        const SYSTEM = new Set(["/api/health", "/api/cron", "/api/admin/ping"]);
+        // A screen may build the address from a variable (`${base}/ticks`). The ending it names counts as a use of
+        // any route that ends the same way, so only routes no screen mentions in any form are reported.
+        const endings = clientEndings(files);
+        for (const p of patterns) {
+            if (SYSTEM.has(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.
+            if (!calls.some((c) => p.re.test(c.path)))
+                findings.push(finding("design/unused-route", { file: "src/server", fix: `Nothing under src/client calls ${p.method} ${p.path}. If a screen was meant to use it, connect it; if it is left over, remove the route and its tests. If something outside the app calls it on purpose, leave it and tell the person it exists.`, fingerprint: `design/unused-route:${p.method} ${p.path}` }));
+        }
+    }
+    // 3. A list with no end. Each statement from .select( to .all() that never says .limit(.
+    for (const f of files) {
+        if (!f.rel.startsWith("src/server/") || !CODE.test(f.rel))
+            continue;
+        const text = withoutComments(f.text);
+        const re = /\.select\s*\(/g;
+        let m;
+        while ((m = re.exec(text))) {
+            const end = text.indexOf(";", m.index);
+            const stmt = text.slice(m.index, end < 0 ? m.index + 600 : end);
+            if (/\.all\s*\(\s*\)/.test(stmt) && !/\.limit\s*\(/.test(stmt))
+                add("design/unbounded-list", f.rel, lineOf(text, m.index));
+        }
+    }
+    // 4, 5, 6. The data model.
+    const schemaFile = files.find((f) => f.rel === "src/server/db/schema.ts");
+    if (schemaFile) {
+        const schema = withoutComments(schemaFile.text);
+        const serverText = files.filter((f) => f.rel.startsWith("src/server/") && f.rel !== schemaFile.rel && CODE.test(f.rel)).map((f) => withoutComments(f.text)).join("\n");
+        for (const t of tables(schema)) {
+            const line = lineOf(schema, t.index);
+            const money = /\b(\w*(price|amount|cost|total|balance|fee|salary|payment)\w*)\s*:\s*real\s*\(/i.exec(t.body);
+            if (money)
+                add("design/money-as-fraction", schemaFile.rel, lineOf(schema, t.index + money.index));
+            if (/\buserId\s*:/.test(t.body) && !/index\s*\([^)]*\)\s*\.on\s*\([^)]*\buserId\b/.test(t.body) && !/\buserId\s*:[^,\n]*\.(primaryKey|unique)\s*\(/.test(t.body))
+                add("design/no-index-on-owner", schemaFile.rel, line);
+            if (!new RegExp(`\\bschema\\.${t.name}\\b|\\b${t.name}\\b`).test(serverText))
+                add("design/unused-table", schemaFile.rel, line);
+        }
+    }
+    // 7 and 8. Files an agent will struggle to change safely, and words left for later.
+    for (const f of files) {
+        if (!f.rel.startsWith("src/") || !CODE.test(f.rel))
+            continue;
+        if (f.text.split("\n").length > LONG_FILE_LINES)
+            add("design/long-file", f.rel);
+        const text = f.text;
+        // The markers are capitals only: a to-do app says "todo" on every other line.
+        const todo = /\b(TODO|FIXME|XXX)\b[:( ]|[Ll]orem ipsum|[Cc]oming soon/.exec(text);
+        if (todo)
+            add("design/unfinished", f.rel, lineOf(text, todo.index));
+    }
+    return findings;
+}
+export const designGate = {
+    name: "design",
+    title: "How the app is put together",
+    blocking: false,
+    rulePrefixes: ["design/"],
+    async run(ctx) {
+        const t = Date.now();
+        if (!existsSync(path.join(ctx.root, "src/server")))
+            return result(this, "skip", "No src/server folder", [], t);
+        const routes = declaredRoutes(ctx.root);
+        const findings = designFindings(ctx.root, sourceFiles(ctx.root), routes);
+        const note = routes ? "" : " (screens were not matched to routes: that needs the app's access tests)";
+        return result(this, verdict(findings), findings.length ? `${counts(findings)}${note}` : `Nothing to raise${note}`, findings, t);
+    },
+};

package/dist/gates/index.js

@@ -3,7 +3,9 @@ import { depsGate, piiGate, policyGate, rulesGate, typecheckGate } from "./code.
 import { gitleaksGate, semgrepGate } from "./tools.js";
 import { suppressionsGate } from "./suppressions.js";
 import { staticGate } from "./static.js";
+import { designGate } from "./design.js";
 import { testsGate } from "./tests.js";
+import { versionsGate } from "./versions.js";
 import { applyAttempts, MAX_ATTEMPTS } from "./attempts.js";
 export { gateSummary, skippedGates } from "./types.js";
 export { RULES, ruleFor } from "./rules.js";
@@ -11,7 +13,7 @@ export { mask } from "./secrets.js";
 export { MAX_ATTEMPTS, readAttempts } from "./attempts.js";
 export { probeDeployment, skippedProbe, waitForDeployment } from "./smoke.js";
 /** Gates that run on source, before the build. Suppressions first so a human sees them before anything else. */
-export const SOURCE_GATES = [suppressionsGate, secretsGate, gitleaksGate, depsGate, rulesGate, staticGate, semgrepGate, policyGate, piiGate, typecheckGate, testsGate];
+export const SOURCE_GATES = [suppressionsGate, secretsGate, gitleaksGate, depsGate, rulesGate, versionsGate, staticGate, semgrepGate, policyGate, piiGate, typecheckGate, testsGate, designGate];
 /** Gates that need the built output. */
 export const BUILD_GATES = [bundleGate, policyGate];
 function selectGates(gates, onlyRules) {

package/dist/gates/rules.d.ts

@@ -13,6 +13,8 @@ export interface RuleDef {
         wrong: string;
         right: string;
     };
+    /** For the `review/` rules only: what the model reviewer is told to look for. Written by us, like everything else here. */
+    when?: string;
 }
 export declare const RULES: Record<string, RuleDef>;
 /** Fallback for scanner rule ids not in the catalog (semgrep and gitleaks have their own). */

package/dist/gates/rules.js

@@ -36,6 +36,29 @@ export const RULES = {
     "rules/advisory": { title: "Platform advisory", severity: "warn", audience: "agent", risk: "Not blocking, but the project is missing something the platform expects.", fix: "Follow the instruction in the finding." },
     "rules/shape": { title: "Not in the nerdsystem shape", severity: "warn", audience: "human", risk: "Every app on nerdsystem is one shape: a Vite client, a Hono server on @nerdsystem/sdk, SQLite on D1, and a bucket. This repository is not in that shape. A clean scan says nothing about whether it would deploy here.", fix: "Start a project with `nerd init` and have the agent port the screens into it. The server and the login are rebuilt on the platform's sign-in and database. The compare pages on nerdsystem.com say what carries over." },
     "typecheck/error": { title: "TypeScript error", severity: "block", audience: "agent", risk: "The code would not compile reliably; the build may fail or behave unexpectedly.", fix: "Fix the type error at the file and line shown. Run `npx tsc -b` for the full message." },
+    "review/trusts-client-value": { title: "The server trusts a value the browser sent", severity: "warn", audience: "agent", when: "A route uses a price, total, discount, role, status, owner, or permission taken from the request body or query to make a decision or to store it, where the server should look the value up or compute it itself.", risk: "Anyone can change what their browser sends, so they can set their own price, role, or status.", fix: "At the file and line shown, stop using the value from the request. Look it up from the database or compute it on the server, and keep only the identifiers the person is allowed to choose." },
+    "review/missing-permission-rule": { title: "Signed-in people can do something only some should", severity: "warn", audience: "agent", when: "A route is limited to signed-in users, and the data is scoped correctly, but the action itself should be limited further by the app's own logic and is not: for example any user can approve, confirm, publish, refund, or change something that only its owner, a staff member, or an admin should.", risk: "A normal user can perform an action meant for the owner or for staff.", fix: "Decide who may do this and enforce it on the server at the file and line shown: `requireRole(...)` for staff actions, or a check that the signed-in user is the one the row belongs to. Ask the person who should be allowed if it is not obvious, and add a test for it." },
+    "review/no-duplicate-guard": { title: "Nothing stops the same thing happening twice", severity: "warn", audience: "agent", when: "The feature has something that must be unique or limited (one booking per slot, one vote per person, one membership per user and group, stock that can run out) and neither the database nor the route prevents a second one, including when two requests arrive at the same moment.", risk: "Two people can take the same slot, or one person can do twice what should happen once, and the data ends up contradicting itself.", fix: "Add a unique index for the combination that must not repeat (then `pnpm db:generate`), and have the route answer 409 with a clear message when it is taken. A check in code alone is not enough when two requests arrive together." },
+    "review/dead-end": { title: "Something can be started but not finished or undone", severity: "warn", audience: "agent", when: "A person can create or begin something through the app and there is no way in the app to complete, change, cancel, or remove it, where the feature plainly needs one.", risk: "People get stuck with something they cannot fix, and the owner has to change the database by hand.", fix: "Add the missing step (edit, cancel, delete, or complete) as a locked route with its tests and a control on the screen, or tell the person it is not there yet so they can decide." },
+    "review/unhandled-state": { title: "A screen has no answer for empty, slow, or failed", severity: "info", audience: "agent", when: "A screen loads or saves data and shows nothing useful while it loads, when there is nothing to show yet, or when the request fails; a failed save looks the same as a successful one.", risk: "People see a blank page or believe something saved when it did not.", fix: "At the file and line shown, add the three states: a short message while loading, a plain sentence and a next step when there is nothing yet, and a visible message when a request fails." },
+    "review/destructive-without-confirm": { title: "Something is deleted with one click and no way back", severity: "info", audience: "agent", when: "A delete or other irreversible action runs immediately from a single click or tap, with no confirmation and no undo.", risk: "A slip of the finger destroys someone's work.", fix: "Ask for confirmation in words that say what will be lost, or keep the row and mark it deleted so it can be restored." },
+    "review/promised-but-missing": { title: "The app does not do something its description says it does", severity: "warn", audience: "human", when: "The app's own description (the opening lines of README.md) states a capability, and nothing in the code provides it. Only for capabilities stated plainly in the description, not ones you imagine it should have.", risk: "The person who asked for the app may believe it does something it does not.", fix: "Tell the person, in plain words, which part of what they asked for is not built yet, and ask whether they want it now. Do not build it without asking." },
+    "review/logic-in-the-browser-only": { title: "A rule is enforced only on the screen", severity: "warn", audience: "agent", when: "A limit, validation, or permission exists in the client code (a hidden button, a disabled field, a check before sending) and the matching route on the server does not enforce it.", risk: "The screen is a convenience. Anyone can call the server directly and skip the rule.", fix: "Enforce the same rule in the route on the server at the file and line shown, and keep the screen's version only as a courtesy." },
+    "review/duplicated-logic": { title: "The same logic is written in several places", severity: "info", audience: "agent", when: "The same non-trivial rule or calculation (a price, an eligibility check, a status transition) is written out in two or more places that would have to change together.", risk: "The next change updates one copy and not the others, and the app starts disagreeing with itself.", fix: "Move the rule into one function the next time you change it, and have every caller use that. Do not reorganise working code only for this." },
+    "review/inconsistent-pattern": { title: "The same job is done in different ways", severity: "info", audience: "agent", when: "Similar routes or screens in the app solve the same problem in clearly different ways (some check ownership one way and some another, some validate input with the schema helper and some by hand, some return errors in a different shape).", risk: "The odd one out is usually the one with the bug, and every future change has to work out which way is right.", fix: "Pick the way the rest of the app and the platform's instructions use, and bring the odd one into line." },
+    "review/time-without-zone": { title: "Dates or times that will mean different things to different people", severity: "info", audience: "agent", when: "The feature depends on dates or times of day (bookings, reminders, deadlines, opening hours) and stores or compares them without a clear time zone, or mixes local time with UTC.", risk: "A booking or reminder lands an hour or a day off for someone in another time zone or across a clock change.", fix: "Store instants in UTC as ISO strings, store the place's time zone where one matters, and convert only when showing a time to a person." },
+    "review/collects-more-than-needed": { title: "The app stores personal details it does not use", severity: "info", audience: "human", when: "The app asks for or stores personal information (date of birth, address, phone number, identity numbers, health details) that no feature in the code uses.", risk: "Personal data you hold is data you have to protect and may have to hand over or delete on request.", fix: "Tell the person which details are collected and not used, and ask whether to stop collecting them. Removing a column that holds data is their decision." },
+    "design/unknown-route": { title: "A screen calls a route the server does not have", severity: "warn", audience: "agent", risk: "That part of the app fails for everyone who uses it, with an error only they see.", fix: "At the file and line shown, the client asks for a path no route answers. Add the route on the server (locked, with its tests), or correct the path to the route that was meant." },
+    "design/unused-route": { title: "A route no screen uses", severity: "info", audience: "agent", risk: "Code nobody reaches still has to be kept safe and correct, and usually means a feature was half removed or half built.", fix: "Connect it to the screen that was meant to use it, or remove the route and its tests." },
+    "design/unbounded-list": { title: "A list that returns every row", severity: "warn", audience: "agent", risk: "It works with ten rows. With ten thousand the page is slow or fails, and nothing warns anyone on the way there.", fix: "Add `.limit(...)` to the query (200 is a reasonable page) and, where the list can grow, a way to ask for the next page.", example: { wrong: "db.select().from(schema.notes).where(eq(schema.notes.userId, id)).all()", right: "db.select().from(schema.notes).where(eq(schema.notes.userId, id)).orderBy(desc(schema.notes.createdAt)).limit(200).all()" } },
+    "design/money-as-fraction": { title: "Money stored as a fraction", severity: "warn", audience: "agent", risk: "Fractions cannot hold amounts like 0.10 exactly, so totals drift by a cent and never match a receipt.", fix: "Store money as a whole number of the smallest unit (cents) in an `integer` column, and format it only when showing it. Changing an existing column is a migration: tell the person before you do it.", example: { wrong: 'price: real("price")', right: 'priceCents: integer("price_cents").notNull()' } },
+    "design/no-index-on-owner": { title: "A table of users' rows with no index on the owner", severity: "warn", audience: "agent", risk: "Every page that lists someone's rows reads the whole table to find them, which gets slower for every user as the app grows.", fix: "Add an index on the owner column in the table's definition, then `pnpm db:generate` for the migration.", example: { wrong: 'sqliteTable("notes", { userId: text("user_id").notNull() })', right: 'sqliteTable("notes", { userId: text("user_id").notNull() }, (t) => [index("notes_user_idx").on(t.userId)])' } },
+    "design/unused-table": { title: "A table nothing uses", severity: "warn", audience: "agent", risk: "A table left over from the starter or from a removed feature confuses the next change and may still hold people's data.", fix: "If the feature is gone, remove the table from the schema and write a migration that drops it; tell the person first if it may hold data they want. If it is meant to be used, connect it." },
+    "design/long-file": { title: "A very long file", severity: "info", audience: "agent", risk: "Changes to a file this long are more likely to break something elsewhere in it, for a person or an agent.", fix: "Split it along its natural parts (one screen, one group of routes per file) the next time you change it. Do not reorganise working code just for this." },
+    "design/unfinished": { title: "Something marked as unfinished", severity: "info", audience: "agent", risk: "A note to finish something later, or placeholder text, is about to go live.", fix: "Finish it, remove it, or tell the person it is not done yet so they can decide." },
+    "versions/cli-outdated": { title: "The nerd command is behind", severity: "warn", audience: "agent", risk: "An older nerd runs fewer checks and may not know about newer platform features.", fix: "Run `npm install -g nerdsystem@latest`." },
+    "versions/sdk-outdated": { title: "The app's SDK is behind", severity: "warn", audience: "agent", risk: "The app is missing fixes and safeguards that newer versions of the platform's library and instructions carry.", fix: "Run `nerd upgrade`, then `pnpm install` and `nerd check`." },
+    "versions/sdk-unsupported": { title: "The app's SDK is too old for the platform", severity: "block", audience: "agent", risk: "This version of the platform's library lacks something the platform now depends on to keep apps safe, so it is no longer accepted.", fix: "Run `nerd upgrade`, then `pnpm install` and `nerd check`." },
     "code/raw-sql": { title: "SQL built from values", severity: "block", audience: "agent", risk: "A value from a request placed straight into SQL lets a visitor rewrite the query and read or delete other people's data.", fix: "Use the Drizzle query builder, or bind values as parameters (`.prepare(\"... where id = ?\").bind(id)`). Never put a variable inside the SQL text.", example: { wrong: "c.env.DB.prepare(`select * from notes where id = ${id}`)", right: "db(c.env.DB).select().from(schema.notes).where(eq(schema.notes.id, id))" } },
     "code/eval": { title: "eval or new Function", severity: "block", audience: "agent", risk: "Running text as code lets anyone who can influence that text run their own code in the app.", fix: "Remove it. Parse data with JSON.parse and choose behaviour with ordinary code." },
     "code/password-in-app": { title: "Password handling in app code", severity: "block", audience: "agent", risk: "Storing or comparing passwords yourself is unnecessary here and easy to get wrong.", fix: "Remove it. Sign-in is provided by the platform: read the signed-in user from `c.var.user` and protect routes with `requireAuth()`.", example: { wrong: "if (user.password === body.password) { ... }", right: "app.get(\"/api/me\", requireAuth(), (c) => c.json(c.var.user));" } },

package/dist/gates/versions.d.ts

@@ -0,0 +1,32 @@
+import { type Finding, type Gate } from "./types.js";
+export interface Versions {
+    latest: string | null;
+    minSdk: string;
+}
+/** -1, 0, or 1; anything that is not three numbers compares as equal, so a strange value never produces a finding. */
+export declare function compareVersions(a: string, b: string): number;
+/** The first x.y.z in a dependency range: "^0.0.13" → "0.0.13". Null for workspace:, file:, and tags. */
+export declare function pinned(range: string | undefined): string | null;
+/**
+ * What the platform says is current, asked at most once a day and remembered in between. Never throws
+ * and never takes long: without an answer there is simply nothing to say about versions.
+ */
+export declare function currentVersions(opts?: {
+    apiUrl?: string;
+    now?: number;
+    fetchImpl?: typeof fetch;
+    cache?: string;
+}): Promise<Versions | null>;
+/** The findings for a given state of the world. Separate from the gate so it can be tested without a network. */
+export declare function versionFindings(input: {
+    cli: string;
+    sdk: string | null;
+    versions: Versions;
+    inBuilder?: boolean;
+}): Finding[];
+/**
+ * Says when the `nerd` command or the app's SDK has fallen behind. Advice only, with one exception:
+ * an SDK older than the platform still accepts blocks the deploy, because that floor is only raised
+ * for a safety reason. Version numbers in the text come from the platform, never from the app.
+ */
+export declare const versionsGate: Gate;

package/dist/gates/versions.js

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { finding } from "./secrets.js";
+import { result, verdict } from "./types.js";
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+const DAY = 24 * 60 * 60 * 1000;
+/** -1, 0, or 1; anything that is not three numbers compares as equal, so a strange value never produces a finding. */
+export function compareVersions(a, b) {
+    const x = SEMVER.exec(a);
+    const y = SEMVER.exec(b);
+    if (!x || !y)
+        return 0;
+    for (let i = 1; i <= 3; i++) {
+        const d = Number(x[i]) - Number(y[i]);
+        if (d)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** The first x.y.z in a dependency range: "^0.0.13" → "0.0.13". Null for workspace:, file:, and tags. */
+export function pinned(range) {
+    const m = /(\d+\.\d+\.\d+)/.exec(range ?? "");
+    return m && !/^(workspace|file|link|npm):/.test(range ?? "") ? m[1] : null;
+}
+function cacheFile() {
+    return path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "nerdsystem", "versions.json");
+}
+/**
+ * What the platform says is current, asked at most once a day and remembered in between. Never throws
+ * and never takes long: without an answer there is simply nothing to say about versions.
+ */
+export async function currentVersions(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const file = opts.cache ?? cacheFile();
+    try {
+        if (existsSync(file)) {
+            const c = JSON.parse(readFileSync(file, "utf8"));
+            if (now - c.checkedAt < DAY && typeof c.minSdk === "string")
+                return { latest: c.latest, minSdk: c.minSdk };
+        }
+    }
+    catch {
+        // unreadable cache: ask again
+    }
+    try {
+        const base = (opts.apiUrl ?? process.env.NERD_API_URL ?? "https://api.nerdsystem.com").replace(/\/$/, "");
+        const res = await (opts.fetchImpl ?? fetch)(`${base}/public/versions`, { signal: AbortSignal.timeout(4000) });
+        if (!res.ok)
+            return null;
+        const v = (await res.json());
+        if (typeof v.minSdk !== "string" || !SEMVER.test(v.minSdk))
+            return null;
+        const out = { latest: typeof v.latest === "string" && SEMVER.test(v.latest) ? v.latest : null, minSdk: v.minSdk };
+        try {
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, `${JSON.stringify({ ...out, checkedAt: now })}\n`);
+        }
+        catch {
+            // a read-only home is fine; it just asks again next time
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+function installedCli() {
+    return createRequire(import.meta.url)("../../package.json").version;
+}
+/** The findings for a given state of the world. Separate from the gate so it can be tested without a network. */
+export function versionFindings(input) {
+    const { cli, sdk, versions } = input;
+    const out = [];
+    if (sdk && compareVersions(sdk, versions.minSdk) < 0) {
+        out.push(finding("versions/sdk-unsupported", { file: "package.json", fix: `Run \`nerd upgrade\`, then \`pnpm install\` and \`nerd check\`. This app is on @nerdsystem/sdk ${sdk}; the platform needs ${versions.minSdk} or newer.` }));
+    }
+    const latest = versions.latest;
+    if (!latest)
+        return out;
+    // The builder's own copy of the command is the platform's business, not the app's.
+    if (!input.inBuilder && compareVersions(cli, latest) < 0) {
+        out.push(finding("versions/cli-outdated", { fix: `Run \`npm install -g nerdsystem@latest\` (nerd ${cli} is installed; ${latest} is current), then run \`nerd check\` again. If the global install is refused, use \`npx nerdsystem@latest\` in place of \`nerd\`.` }));
+    }
+    if (sdk && compareVersions(sdk, latest) < 0 && compareVersions(sdk, versions.minSdk) >= 0) {
+        out.push(finding("versions/sdk-outdated", { file: "package.json", fix: `Run \`nerd upgrade\` (this app is on @nerdsystem/sdk ${sdk}; ${latest} is current), then \`pnpm install\` and \`nerd check\`, and follow what the check reports. Tell the person what changed before deploying.` }));
+    }
+    return out;
+}
+/**
+ * Says when the `nerd` command or the app's SDK has fallen behind. Advice only, with one exception:
+ * an SDK older than the platform still accepts blocks the deploy, because that floor is only raised
+ * for a safety reason. Version numbers in the text come from the platform, never from the app.
+ */
+export const versionsGate = {
+    name: "versions",
+    title: "Up to date",
+    blocking: true,
+    rulePrefixes: ["versions/"],
+    async run(ctx) {
+        const t = Date.now();
+        if (process.env.NERD_NO_VERSION_CHECK)
+            return result(this, "skip", "Version check turned off", [], t);
+        const versions = await currentVersions();
+        if (!versions)
+            return result(this, "skip", "Could not ask the platform what is current", [], t);
+        let sdk = null;
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(ctx.root, "package.json"), "utf8"));
+            sdk = pinned(pkg.dependencies?.["@nerdsystem/sdk"]);
+        }
+        catch {
+            // 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";
+        return result(this, verdict(findings), summary, findings, t);
+    },
+};

package/package.json

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

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

@@ -39,7 +39,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 
@@ -164,6 +166,10 @@ Without MCP, `nerd check --json` returns the same shape, and `nerd check --rule
 - SQL built from values, `eval` or `new Function`, and password handling in server code (the `code/` rules; they block). It also flags, without blocking: tokens signed in app code, HTML built from data, redirects and fetches to an address from the request, `Math.random` for a secret, a body read without `readBody`, and an app that has not turned on `public` in `createNerdApp`.
 - A failing test, a missing access sweep, or a route with an id that no second user was tried against (the `tests/` rules above).
 
+It also reviews how the app is put together and reports, as advice that never blocks (the `design/` rules): a screen calling a route the server does not have, a route no screen uses, a list query with no `.limit(...)`, money in a `real` column (use whole cents in an `integer`), a table with a `userId` and no index on it, a table nothing uses, a file over 400 lines, and `TODO` or placeholder text. Fix these as you go: give every list a limit and every user-owned table an index when you write them, and remove the starter's `todos` table, route, and tests once the app's own feature replaces them. When a fix would change or drop a column that may hold people's data, tell the person first.
+
+After a deploy is live, `nerd deploy` asks the platform for a model review of the stored code and prints what it found (the `review/` rules): a value trusted from the browser, an action more people can do than should, nothing stopping the same thing happening twice, something that can be started and not finished, a rule enforced only on the screen, and a few more. It is a second opinion and can be wrong: read the code at the file and line before changing anything, fix the ones that are real, and say which you did not act on and why. Findings marked "for the person to decide" are theirs: put the question to them in plain words and wait. The person's own summary of the review is in the dashboard under Review; point them to it. Free plans include a few reviews a month, so a deploy may say it was not run.
+
 ## Scheduled jobs and email
 
 - **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.

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 (f814c3a452ab); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (df4afc8243ef); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -40,7 +40,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 
@@ -165,6 +167,10 @@ Without MCP, `nerd check --json` returns the same shape, and `nerd check --rule
 - SQL built from values, `eval` or `new Function`, and password handling in server code (the `code/` rules; they block). It also flags, without blocking: tokens signed in app code, HTML built from data, redirects and fetches to an address from the request, `Math.random` for a secret, a body read without `readBody`, and an app that has not turned on `public` in `createNerdApp`.
 - A failing test, a missing access sweep, or a route with an id that no second user was tried against (the `tests/` rules above).
 
+It also reviews how the app is put together and reports, as advice that never blocks (the `design/` rules): a screen calling a route the server does not have, a route no screen uses, a list query with no `.limit(...)`, money in a `real` column (use whole cents in an `integer`), a table with a `userId` and no index on it, a table nothing uses, a file over 400 lines, and `TODO` or placeholder text. Fix these as you go: give every list a limit and every user-owned table an index when you write them, and remove the starter's `todos` table, route, and tests once the app's own feature replaces them. When a fix would change or drop a column that may hold people's data, tell the person first.
+
+After a deploy is live, `nerd deploy` asks the platform for a model review of the stored code and prints what it found (the `review/` rules): a value trusted from the browser, an action more people can do than should, nothing stopping the same thing happening twice, something that can be started and not finished, a rule enforced only on the screen, and a few more. It is a second opinion and can be wrong: read the code at the file and line before changing anything, fix the ones that are real, and say which you did not act on and why. Findings marked "for the person to decide" are theirs: put the question to them in plain words and wait. The person's own summary of the review is in the dashboard under Review; point them to it. Free plans include a few reviews a month, so a deploy may say it was not run.
+
 ## Scheduled jobs and email
 
 - **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.

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

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (f814c3a452ab); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (df4afc8243ef); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,7 +36,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 
@@ -161,6 +163,10 @@ Without MCP, `nerd check --json` returns the same shape, and `nerd check --rule
 - SQL built from values, `eval` or `new Function`, and password handling in server code (the `code/` rules; they block). It also flags, without blocking: tokens signed in app code, HTML built from data, redirects and fetches to an address from the request, `Math.random` for a secret, a body read without `readBody`, and an app that has not turned on `public` in `createNerdApp`.
 - A failing test, a missing access sweep, or a route with an id that no second user was tried against (the `tests/` rules above).
 
+It also reviews how the app is put together and reports, as advice that never blocks (the `design/` rules): a screen calling a route the server does not have, a route no screen uses, a list query with no `.limit(...)`, money in a `real` column (use whole cents in an `integer`), a table with a `userId` and no index on it, a table nothing uses, a file over 400 lines, and `TODO` or placeholder text. Fix these as you go: give every list a limit and every user-owned table an index when you write them, and remove the starter's `todos` table, route, and tests once the app's own feature replaces them. When a fix would change or drop a column that may hold people's data, tell the person first.
+
+After a deploy is live, `nerd deploy` asks the platform for a model review of the stored code and prints what it found (the `review/` rules): a value trusted from the browser, an action more people can do than should, nothing stopping the same thing happening twice, something that can be started and not finished, a rule enforced only on the screen, and a few more. It is a second opinion and can be wrong: read the code at the file and line before changing anything, fix the ones that are real, and say which you did not act on and why. Findings marked "for the person to decide" are theirs: put the question to them in plain words and wait. The person's own summary of the review is in the dashboard under Review; point them to it. Free plans include a few reviews a month, so a deploy may say it was not run.
+
 ## Scheduled jobs and email
 
 - **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.

package/template/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (f814c3a452ab); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (df4afc8243ef); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,7 +36,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 
@@ -161,6 +163,10 @@ Without MCP, `nerd check --json` returns the same shape, and `nerd check --rule
 - SQL built from values, `eval` or `new Function`, and password handling in server code (the `code/` rules; they block). It also flags, without blocking: tokens signed in app code, HTML built from data, redirects and fetches to an address from the request, `Math.random` for a secret, a body read without `readBody`, and an app that has not turned on `public` in `createNerdApp`.
 - A failing test, a missing access sweep, or a route with an id that no second user was tried against (the `tests/` rules above).
 
+It also reviews how the app is put together and reports, as advice that never blocks (the `design/` rules): a screen calling a route the server does not have, a route no screen uses, a list query with no `.limit(...)`, money in a `real` column (use whole cents in an `integer`), a table with a `userId` and no index on it, a table nothing uses, a file over 400 lines, and `TODO` or placeholder text. Fix these as you go: give every list a limit and every user-owned table an index when you write them, and remove the starter's `todos` table, route, and tests once the app's own feature replaces them. When a fix would change or drop a column that may hold people's data, tell the person first.
+
+After a deploy is live, `nerd deploy` asks the platform for a model review of the stored code and prints what it found (the `review/` rules): a value trusted from the browser, an action more people can do than should, nothing stopping the same thing happening twice, something that can be started and not finished, a rule enforced only on the screen, and a few more. It is a second opinion and can be wrong: read the code at the file and line before changing anything, fix the ones that are real, and say which you did not act on and why. Findings marked "for the person to decide" are theirs: put the question to them in plain words and wait. The person's own summary of the review is in the dashboard under Review; point them to it. Free plans include a few reviews a month, so a deploy may say it was not run.
+
 ## Scheduled jobs and email
 
 - **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.

package/template/GEMINI.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (f814c3a452ab); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (df4afc8243ef); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,7 +36,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 
@@ -161,6 +163,10 @@ Without MCP, `nerd check --json` returns the same shape, and `nerd check --rule
 - SQL built from values, `eval` or `new Function`, and password handling in server code (the `code/` rules; they block). It also flags, without blocking: tokens signed in app code, HTML built from data, redirects and fetches to an address from the request, `Math.random` for a secret, a body read without `readBody`, and an app that has not turned on `public` in `createNerdApp`.
 - A failing test, a missing access sweep, or a route with an id that no second user was tried against (the `tests/` rules above).
 
+It also reviews how the app is put together and reports, as advice that never blocks (the `design/` rules): a screen calling a route the server does not have, a route no screen uses, a list query with no `.limit(...)`, money in a `real` column (use whole cents in an `integer`), a table with a `userId` and no index on it, a table nothing uses, a file over 400 lines, and `TODO` or placeholder text. Fix these as you go: give every list a limit and every user-owned table an index when you write them, and remove the starter's `todos` table, route, and tests once the app's own feature replaces them. When a fix would change or drop a column that may hold people's data, tell the person first.
+
+After a deploy is live, `nerd deploy` asks the platform for a model review of the stored code and prints what it found (the `review/` rules): a value trusted from the browser, an action more people can do than should, nothing stopping the same thing happening twice, something that can be started and not finished, a rule enforced only on the screen, and a few more. It is a second opinion and can be wrong: read the code at the file and line before changing anything, fix the ones that are real, and say which you did not act on and why. Findings marked "for the person to decide" are theirs: put the question to them in plain words and wait. The person's own summary of the review is in the dashboard under Review; point them to it. Free plans include a few reviews a month, so a deploy may say it was not run.
+
 ## Scheduled jobs and email
 
 - **Scheduled jobs**: put the work in the `POST /api/cron` handler (already in `src/server/index.ts`, guarded by `verifyCron()`), then turn the schedule on with `nerd cron hourly` or `nerd cron daily`. The platform calls it; the app never needs its own timer.

package/template/migrations/0000_init.sql

@@ -5,3 +5,5 @@ CREATE TABLE `todos` (
 	`done` integer DEFAULT false NOT NULL,
 	`created_at` text NOT NULL
 );
+--> statement-breakpoint
+CREATE INDEX `todos_user_idx` ON `todos` (`user_id`);

package/template/migrations/meta/0000_snapshot.json

@@ -1,7 +1,7 @@
 {
   "version": "6",
   "dialect": "sqlite",
-  "id": "a804e9fb-b416-462b-a3e2-0349c283a4b7",
+  "id": "b47c99fc-b1b2-4e2c-97a9-6ac84d8b3947",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "tables": {
     "todos": {
@@ -44,7 +44,15 @@
           "autoincrement": false
         }
       },
-      "indexes": {},
+      "indexes": {
+        "todos_user_idx": {
+          "name": "todos_user_idx",
+          "columns": [
+            "user_id"
+          ],
+          "isUnique": false
+        }
+      },
       "foreignKeys": {},
       "compositePrimaryKeys": {},
       "uniqueConstraints": {},

package/template/migrations/meta/_journal.json

@@ -5,7 +5,7 @@
     {
       "idx": 0,
       "version": "6",
-      "when": 1794323561793,
+      "when": 1794342101281,
       "tag": "0000_init",
       "breakpoints": true
     }

package/template/src/server/db/schema.ts

@@ -1,14 +1,19 @@
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
 
 // Add your tables here, then run `pnpm db:generate` to create a migration.
-// Rows that belong to a user should carry their id from c.var.user.
+// Rows that belong to a user should carry their id from c.var.user, with an index on it:
+// every page that lists someone's rows looks them up by that column.
 
-export const todos = sqliteTable("todos", {
-  id: integer("id").primaryKey({ autoIncrement: true }),
-  userId: text("user_id").notNull(),
-  title: text("title").notNull(),
-  done: integer("done", { mode: "boolean" }).notNull().default(false),
-  createdAt: text("created_at")
-    .notNull()
-    .$defaultFn(() => new Date().toISOString()),
-});
+export const todos = sqliteTable(
+  "todos",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    userId: text("user_id").notNull(),
+    title: text("title").notNull(),
+    done: integer("done", { mode: "boolean" }).notNull().default(false),
+    createdAt: text("created_at")
+      .notNull()
+      .$defaultFn(() => new Date().toISOString()),
+  },
+  (t) => [index("todos_user_idx").on(t.userId)],
+);

package/template/src/server/routes/todos.ts

@@ -18,6 +18,8 @@ todos.get("/", async (c) => {
     .from(schema.todos)
     .where(eq(schema.todos.userId, c.var.user!.id))
     .orderBy(desc(schema.todos.createdAt))
+    // A list always has an end. Raise this, or add paging, when someone really has more.
+    .limit(200)
     .all();
   return c.json({ todos: rows });
 });