nerdsystem 0.0.21 → 0.0.23

package/dist/cli.js

@@ -9,6 +9,7 @@ import { cron, health, rollback, secretList, secretRemove, secretSet, transfer,
 import { adminHelp, adminSuspend, adminUnsuspend } from "./commands/admin.js";
 import { agentsSync } from "./commands/agents.js";
 import { upgrade } from "./commands/upgrade.js";
+import { review, status } from "./commands/status.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";
@@ -59,12 +60,14 @@ const HELP = `nerd: start, check, and deploy a web app on nerdsystem
   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 status                         What the platform has found for this app that needs attention (updates, review findings, vulnerable packages)
+  nerd review                         The latest model review's findings for this app, with the fix for each
   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
   nerd members [invite <email> --role r | remove <userId>]   Org members and invitations
   nerd clients [create <slug> --name n | release <slug>]     Studio: one org per client, billed through yours
-  nerd domains [add <hostname> | remove <id>]                Custom domains for this project
+  nerd domains [add <domain> | remove <id>]                  The app on your own domain, with the DNS steps for it
   nerd logs [--since 30m] [--limit 100] [--q text] [--pr n]  Logs from the deployed app
   nerd audit [--out file.csv]         Export deployments and builds (Studio)
 
@@ -135,6 +138,14 @@ export async function main(argv) {
             const { values } = parse({ "skip-build": BOOL, "skip-probe": BOOL, force: BOOL, note: STR });
             return deploy(values);
         }
+        case "status": {
+            const { values } = parse({ hook: BOOL }, false);
+            return status({ json: Boolean(values.json), hook: Boolean(values.hook) });
+        }
+        case "review": {
+            const { values } = parse({}, false);
+            return review({ json: Boolean(values.json) });
+        }
         case "upgrade": {
             const { values } = parse({}, false);
             return upgrade({ json: Boolean(values.json) });

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.21";
+const SDK_VERSION = "0.0.23";

package/dist/commands/org.d.ts

@@ -11,6 +11,23 @@ export declare function membersRemove(userId: string | undefined, opts: {
     json: boolean;
     org?: string;
 }): Promise<void>;
+/** The platform's steps for the company that runs the domain's DNS. Absent from an older platform. */
+interface DomainSetup {
+    address: string;
+    forwards: string | null;
+    dnsHost: {
+        id: string;
+        name: string;
+    };
+    method: string;
+    steps: string[];
+    after: string;
+}
+/**
+ * The steps as the platform wrote them, numbered, with a line telling an agent how to pass them on. The person
+ * who owns the domain is usually not technical: they get these steps and nothing to choose between.
+ */
+export declare function setupText(s: DomainSetup): string;
 export declare function domainsList(opts: {
     json: boolean;
 }): Promise<void>;
@@ -45,3 +62,4 @@ export declare function clientsRelease(slug: string | undefined, opts: {
     json: boolean;
     org?: string;
 }): Promise<void>;
+export {};

package/dist/commands/org.js

@@ -35,23 +35,46 @@ export async function membersRemove(userId, opts) {
         return printJson(r);
     log.ok("Removed.");
 }
+/**
+ * The steps as the platform wrote them, numbered, with a line telling an agent how to pass them on. The person
+ * who owns the domain is usually not technical: they get these steps and nothing to choose between.
+ */
+export function setupText(s) {
+    const known = s.dnsHost.id !== "unknown";
+    return [
+        `The app's address will be https://${s.address}${s.forwards ? `, and ${s.forwards} forwards to it` : ""}.`,
+        known ? `This domain's DNS is run by ${s.dnsHost.name}${s.method === "move-dns" ? ", which cannot point a bare domain name at another service, so the DNS moves to Cloudflare (free) first" : ""}. The steps for the domain's owner:` : "The steps for the domain's owner:",
+        "",
+        ...s.steps.map((step, i) => `  ${i + 1}. ${step}`),
+        "",
+        s.after,
+        "",
+        "If you are a coding agent: give the owner these steps as they are, numbered, and nothing else to decide. Do not ask which company they use (it was looked up) and do not offer other record types. When they say it is done, run `nerd domains` until the status is active, then open the address to confirm.",
+    ].join("\n");
+}
 export async function domainsList(opts) {
     const nerd = readNerdJson(findProjectRoot());
     const r = await ApiClient.fromConfig().get(projectPath(nerd, "/domains"));
     if (opts.json)
         return printJson(r);
     if (!r.domains.length)
-        return log.info(`No custom domains. Add one: nerd domains add app.example.com`);
-    table(r.domains.map((d) => ({ hostname: d.hostname, status: d.status, ssl: d.sslStatus ?? "", error: d.lastError ?? "", id: d.id })), ["hostname", "status", "ssl", "error", "id"]);
-    log.info(`\nPoint each hostname at ${r.cnameTarget} with a CNAME record.`);
+        return log.info(`No custom domains. Add one: nerd domains add example.com`);
+    table(r.domains.map((d) => ({ hostname: d.hostname, status: d.status, ssl: d.sslStatus ?? "", does: d.redirectTo ? `forwards to ${d.redirectTo}` : "the app", error: d.lastError ?? "", id: d.id })), ["hostname", "status", "ssl", "does", "error", "id"]);
+    // Only addresses still waiting for their DNS records have steps left to do.
+    for (const s of r.setups ?? [])
+        log.info(`\n${setupText(s)}`);
+    if (!r.setups && r.domains.some((d) => d.status !== "active"))
+        log.info(`\nPoint each hostname at ${r.cnameTarget} with a CNAME record.`);
 }
 export async function domainsAdd(hostname, opts) {
     if (!hostname)
-        throw new CliError("Usage: nerd domains add app.example.com");
+        throw new CliError("Usage: nerd domains add example.com");
     const nerd = readNerdJson(findProjectRoot());
     const r = await ApiClient.fromConfig().post(projectPath(nerd, "/domains"), { hostname });
     if (opts.json)
         return printJson(r);
+    if (r.setup)
+        return log.ok(`Added ${r.domain.hostname}.\n\n${setupText(r.setup)}`);
     log.ok(`Added ${r.domain.hostname}. Create this DNS record, then check with \`nerd domains\`:\n\n  ${r.domain.hostname}  CNAME  ${r.cnameTarget}`);
 }
 export async function domainsRemove(idOrHostname, opts) {

package/dist/commands/status.d.ts

@@ -0,0 +1,47 @@
+import { ApiClient } from "../api.js";
+/** One thing the platform wants looked at, in the catalog's words. */
+export interface AttentionItem {
+    rule_id: string;
+    title: string;
+    severity: "block" | "warn" | "info";
+    audience: "agent" | "human";
+    /** A file and line, or a package and version. Never free text from the app or from a model. */
+    where?: string;
+    risk: string;
+    fix: string;
+}
+export interface Attention {
+    app: string | null;
+    items: AttentionItem[];
+    /** When the review the findings come from was made, so a finding already fixed since is not a surprise. */
+    reviewedAt?: string;
+}
+/** The latest model review's findings for this app, mapped through this CLI's own catalog. */
+export declare function reviewItems(api: ApiClient, base: string): Promise<{
+    items: AttentionItem[];
+    reviewedAt?: string;
+}>;
+/**
+ * Everything the platform has noticed about this app that someone should act on, gathered in a few
+ * seconds without building or testing anything: a newer nerd or SDK, what the model review found in the
+ * live code, and packages with a serious vulnerability reported since the last deploy. Never throws and
+ * never waits long; whatever cannot be reached is simply left out.
+ *
+ * This is what a coding agent is shown when a session starts, so the app's owner does not have to know
+ * that any of it exists, let alone open a dashboard to find it.
+ */
+export declare function gatherAttention(root: string): Promise<Attention>;
+/** Short enough to sit at the top of a session: what, where, and one line on what to do about each kind. */
+export declare function attentionText(a: Attention): string;
+/**
+ * `nerd status`: what needs attention. With `--hook` it is the session-start hook's output: it prints
+ * nothing when there is nothing to say, and exits 0 whatever happens, so a session never opens on an error.
+ */
+export declare function status(opts: {
+    json: boolean;
+    hook: boolean;
+}): Promise<void>;
+/** `nerd review`: only the model review's findings, with every fix written out. */
+export declare function review(opts: {
+    json: boolean;
+}): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,140 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+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 { 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 = {}) => {
+    const r = RULES[rule_id];
+    return r ? { rule_id, title: r.title, severity: r.severity, audience: r.audience, risk: r.risk, fix: extra.fix ?? r.fix, ...(extra.where ? { where: extra.where } : {}) } : null;
+};
+/** The latest model review's findings for this app, mapped through this CLI's own catalog. */
+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: [] };
+    const items = [];
+    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);
+    }
+    return { items, reviewedAt: review.createdAt };
+}
+/**
+ * Everything the platform has noticed about this app that someone should act on, gathered in a few
+ * seconds without building or testing anything: a newer nerd or SDK, what the model review found in the
+ * live code, and packages with a serious vulnerability reported since the last deploy. Never throws and
+ * never waits long; whatever cannot be reached is simply left out.
+ *
+ * This is what a coding agent is shown when a session starts, so the app's owner does not have to know
+ * that any of it exists, let alone open a dashboard to find it.
+ */
+export async function gatherAttention(root) {
+    const items = [];
+    let app = null;
+    let sdk = null;
+    try {
+        sdk = pinned(JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).dependencies?.["@nerdsystem/sdk"]);
+    }
+    catch {
+        // no package.json: nothing to say about the SDK
+    }
+    const versions = process.env.NERD_NO_VERSION_CHECK ? null : await within(currentVersions(), 5000);
+    if (versions)
+        for (const f of versionFindings({ cli: cliVersion(), sdk, versions })) {
+            const it = item(f.rule_id, { fix: f.fix, ...(f.file ? { where: f.file } : {}) });
+            if (it)
+                items.push(it);
+        }
+    let reviewedAt;
+    try {
+        const nerd = readNerdJson(root);
+        app = `${nerd.org}/${nerd.project}`;
+        const api = ApiClient.fromConfig();
+        const base = projectPath(nerd);
+        const [review, project] = await Promise.all([reviewItems(api, base), within(api.get(base), 5000)]);
+        items.push(...review.items);
+        reviewedAt = review.reviewedAt;
+        for (const v of project?.project.depsStatus?.vulnerable ?? []) {
+            if (v.severity !== "critical" && v.severity !== "high")
+                continue;
+            // Names and versions come from the platform's look-up of the registry, and are checked again for shape.
+            if (!/^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(v.name) || !/^\d+\.\d+\.\d+$/.test(v.version))
+                continue;
+            const it = item("platform/vulnerable-package", { where: `${v.name} ${v.version}` });
+            if (it)
+                items.push(it);
+        }
+    }
+    catch {
+        // not linked, or not signed in: the versions above are all there is to say
+    }
+    return { app, items, ...(reviewedAt ? { reviewedAt } : {}) };
+}
+/** Short enough to sit at the top of a session: what, where, and one line on what to do about each kind. */
+export function attentionText(a) {
+    if (!a.items.length)
+        return "";
+    const lines = [`nerdsystem has ${a.items.length} thing(s) for this app${a.app ? ` (${a.app})` : ""} that someone should look at:`, ""];
+    const seen = new Set();
+    for (const it of a.items) {
+        lines.push(`- ${it.title}${it.where ? ` (${it.where})` : ""}${it.audience === "human" ? " [for the person to decide]" : ""}`);
+        if (!seen.has(it.rule_id)) {
+            seen.add(it.rule_id);
+            lines.push(`  Why: ${it.risk}`, `  Fix: ${it.fix}`);
+        }
+    }
+    if (a.reviewedAt)
+        lines.push("", `Findings with a file and a line come from a model's review of the version deployed on ${a.reviewedAt.slice(0, 10)}. It 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.`);
+    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");
+}
+/**
+ * `nerd status`: what needs attention. With `--hook` it is the session-start hook's output: it prints
+ * nothing when there is nothing to say, and exits 0 whatever happens, so a session never opens on an error.
+ */
+export async function status(opts) {
+    let a = { app: null, items: [] };
+    try {
+        a = await gatherAttention(findProjectRoot());
+    }
+    catch {
+        if (!opts.hook && !opts.json)
+            log.info("This folder is not a nerdsystem app (no nerd.json found).");
+    }
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(a, null, 2)}\n`);
+        return;
+    }
+    const text = attentionText(a);
+    if (text)
+        process.stdout.write(`${text}\n`);
+    else if (!opts.hook)
+        log.ok(`Nothing needs attention${a.app ? ` for ${a.app}` : ""}.`);
+}
+/** `nerd review`: only the model review's findings, with every fix written out. */
+export async function review(opts) {
+    const root = findProjectRoot();
+    const nerd = readNerdJson(root);
+    const r = await reviewItems(ApiClient.fromConfig(), projectPath(nerd));
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        return;
+    }
+    if (!r.reviewedAt) {
+        log.info("No model review of this app yet. One runs at the end of `nerd deploy`.");
+        return;
+    }
+    if (!r.items.length) {
+        log.ok(`The review of the version deployed on ${r.reviewedAt.slice(0, 10)} found nothing to raise.`);
+        return;
+    }
+    process.stdout.write(`${attentionText({ app: `${nerd.org}/${nerd.project}`, items: r.items, reviewedAt: r.reviewedAt })}\n`);
+}

package/dist/commands/upgrade.js

@@ -87,6 +87,26 @@ export function upgradeProject(root, tpl, version) {
     // 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);
+    // Claude Code's settings for this folder: keep whatever the person or agent added, and make sure the
+    // session-start hook and the platform's read-only commands are there.
+    const tplSettings = read(path.join(tpl, ".claude/settings.json"));
+    if (tplSettings !== null) {
+        const want = JSON.parse(tplSettings);
+        let have = {};
+        try {
+            have = JSON.parse(read(path.join(root, ".claude/settings.json")) ?? "{}");
+        }
+        catch {
+            have = {}; // an unreadable settings file is replaced rather than left broken
+        }
+        const allow = new Set([...(have.permissions?.allow ?? []), ...(want.permissions?.allow ?? [])]);
+        const hooks = { ...(have.hooks ?? {}) };
+        for (const [event, groups] of Object.entries(want.hooks ?? {})) {
+            const kept = (hooks[event] ?? []).filter((g) => !(g.hooks ?? []).some((h) => typeof h.command === "string" && h.command.startsWith("nerd status")));
+            hooks[event] = [...kept, ...groups];
+        }
+        write(".claude/settings.json", `${JSON.stringify({ ...have, permissions: { ...(have.permissions ?? {}), allow: [...allow] }, hooks }, null, 2)}\n`);
+    }
     const ignore = read(path.join(root, ".gitignore")) ?? "";
     if (!/^\.nerd\/?$/m.test(ignore))
         write(".gitignore", `${ignore}${ignore.endsWith("\n") || !ignore ? "" : "\n"}.nerd/\n`);

package/dist/gates/index.js

@@ -4,6 +4,7 @@ import { gitleaksGate, semgrepGate } from "./tools.js";
 import { suppressionsGate } from "./suppressions.js";
 import { staticGate } from "./static.js";
 import { designGate } from "./design.js";
+import { reviewGate } from "./review.js";
 import { testsGate } from "./tests.js";
 import { versionsGate } from "./versions.js";
 import { applyAttempts, MAX_ATTEMPTS } from "./attempts.js";
@@ -13,7 +14,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, versionsGate, staticGate, semgrepGate, policyGate, piiGate, typecheckGate, testsGate, designGate];
+export const SOURCE_GATES = [suppressionsGate, secretsGate, gitleaksGate, depsGate, rulesGate, versionsGate, staticGate, semgrepGate, policyGate, piiGate, typecheckGate, testsGate, designGate, reviewGate];
 /** Gates that need the built output. */
 export const BUILD_GATES = [bundleGate, policyGate];
 function selectGates(gates, onlyRules) {

package/dist/gates/review.d.ts

@@ -0,0 +1,8 @@
+import { type Gate } from "./types.js";
+/**
+ * Brings the platform's latest model review of this app into the same list as every other check, so an
+ * agent meets its findings in the loop it already runs and nobody has to go and look for them. Advice
+ * only. The words are this CLI's catalog; the review itself contributes a rule id, a file, and a line.
+ * Skipped without comment when there is no sign-in, no linked project, no review, or no network.
+ */
+export declare const reviewGate: Gate;

package/dist/gates/review.js

@@ -0,0 +1,37 @@
+import { ApiClient } from "../api.js";
+import { reviewItems } from "../commands/status.js";
+import { projectPath, readNerdJson } from "../project.js";
+import { counts, result, verdict } from "./types.js";
+/**
+ * Brings the platform's latest model review of this app into the same list as every other check, so an
+ * agent meets its findings in the loop it already runs and nobody has to go and look for them. Advice
+ * only. The words are this CLI's catalog; the review itself contributes a rule id, a file, and a line.
+ * Skipped without comment when there is no sign-in, no linked project, no review, or no network.
+ */
+export const reviewGate = {
+    name: "review",
+    title: "Model review of the deployed version",
+    blocking: false,
+    rulePrefixes: ["review/"],
+    async run(ctx) {
+        const t = Date.now();
+        // A git build has no person's sign-in to ask with, and the review is of code already deployed.
+        if (ctx.committed || process.env.NERD_NO_REVIEW)
+            return result(this, "skip", "Not asked for here", [], t);
+        let got;
+        try {
+            got = await reviewItems(ApiClient.fromConfig(), projectPath(readNerdJson(ctx.root)));
+        }
+        catch {
+            return result(this, "skip", "No linked project or sign-in to ask with", [], t);
+        }
+        if (!got.reviewedAt)
+            return result(this, "skip", "No review yet; one runs at the end of nerd deploy", [], t);
+        const findings = got.items.map((i) => {
+            const [file, line] = (i.where ?? "").split(":");
+            return { rule_id: i.rule_id, severity: i.severity, audience: i.audience, file, line: Number(line) || undefined, risk: i.risk, fix: i.fix, verify: "nerd deploy (the code is reviewed again after the next deploy)", attempt: 1, fingerprint: `${i.rule_id}:${i.where}` };
+        });
+        const when = got.reviewedAt.slice(0, 10);
+        return result(this, verdict(findings), findings.length ? `${counts(findings)}, from the review of the version deployed on ${when}; a second opinion that can be wrong, so read the code first` : `Nothing raised in the review of the version deployed on ${when}`, findings, t);
+    },
+};

package/dist/gates/rules.js

@@ -56,6 +56,7 @@ export const RULES = {
     "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." },
+    "platform/vulnerable-package": { title: "A package this app uses has a serious vulnerability reported since it was deployed", severity: "warn", audience: "agent", risk: "The app passed its checks when it went live. Since then a flaw has been made public in something it depends on, and the live app still carries it.", fix: "Run `nerd check`: it names the package and the version to move to. Update it, run the tests, and deploy." },
     "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`." },

package/package.json

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

package/template/.claude/settings.json

@@ -6,7 +6,22 @@
       "Bash(nerd db migrations:*)",
       "Bash(nerd auth config)",
       "Bash(pnpm db:generate)",
-      "Bash(pnpm typecheck)"
+      "Bash(pnpm typecheck)",
+      "Bash(nerd status:*)",
+      "Bash(nerd review:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "nerd status --hook 2>/dev/null || true",
+            "timeout": 20
+          }
+        ]
+      }
     ]
   }
 }

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

@@ -39,6 +39,8 @@ 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.
 
+**At the start of every session in this app, run `nerd status` before anything else** (in Claude Code it runs by itself and its output is already above). It lists what the platform has found for this app that someone should act on: a newer `nerd` or SDK, what the model review found in the live code, a package with a newly reported vulnerability. The person who owns this app does not know these exist and should never have to open a dashboard or learn a command to find out. So tell them, in one or two plain sentences with no file names or jargon, and offer to take care of it; if they say yes, fix what is real, run `nerd check`, and deploy. If it prints nothing, say nothing about it. `nerd review` prints the review's findings again with every fix written out.
+
 `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.
@@ -176,6 +178,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.

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 (df4afc8243ef); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -40,6 +40,8 @@ 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.
 
+**At the start of every session in this app, run `nerd status` before anything else** (in Claude Code it runs by itself and its output is already above). It lists what the platform has found for this app that someone should act on: a newer `nerd` or SDK, what the model review found in the live code, a package with a newly reported vulnerability. The person who owns this app does not know these exist and should never have to open a dashboard or learn a command to find out. So tell them, in one or two plain sentences with no file names or jargon, and offer to take care of it; if they say yes, fix what is real, run `nerd check`, and deploy. If it prints nothing, say nothing about it. `nerd review` prints the review's findings again with every fix written out.
+
 `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.
@@ -177,6 +179,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.

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

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (df4afc8243ef); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,6 +36,8 @@ 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.
 
+**At the start of every session in this app, run `nerd status` before anything else** (in Claude Code it runs by itself and its output is already above). It lists what the platform has found for this app that someone should act on: a newer `nerd` or SDK, what the model review found in the live code, a package with a newly reported vulnerability. The person who owns this app does not know these exist and should never have to open a dashboard or learn a command to find out. So tell them, in one or two plain sentences with no file names or jargon, and offer to take care of it; if they say yes, fix what is real, run `nerd check`, and deploy. If it prints nothing, say nothing about it. `nerd review` prints the review's findings again with every fix written out.
+
 `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.
@@ -173,6 +175,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.

package/template/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (df4afc8243ef); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,6 +36,8 @@ 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.
 
+**At the start of every session in this app, run `nerd status` before anything else** (in Claude Code it runs by itself and its output is already above). It lists what the platform has found for this app that someone should act on: a newer `nerd` or SDK, what the model review found in the live code, a package with a newly reported vulnerability. The person who owns this app does not know these exist and should never have to open a dashboard or learn a command to find out. So tell them, in one or two plain sentences with no file names or jargon, and offer to take care of it; if they say yes, fix what is real, run `nerd check`, and deploy. If it prints nothing, say nothing about it. `nerd review` prints the review's findings again with every fix written out.
+
 `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.
@@ -173,6 +175,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.

package/template/CLAUDE.md

@@ -13,6 +13,10 @@ nerdsystem deploys this app to Cloudflare and provides authentication and author
 - With a linked GitHub repo, pushes to the production branch and pull requests deploy automatically. `nerd builds` and `nerd builds show <id>` show what happened.
 - `pnpm db:generate` creates a migration after editing `src/server/db/schema.ts`. Never edit the database by hand.
 
+## When a session starts
+
+Run `nerd status` first (Claude Code does this by itself). It lists what the platform has found for this app: updates, findings from the model review of the live code, packages with a new vulnerability. The app's owner does not know these exist. Tell them in plain words and offer to take care of them; they should never need a command or a dashboard to find out.
+
 ## Layout
 
 - `src/server/index.ts` is the Worker entry. Build the API here with Hono; mount routers under `/api/...`.

package/template/GEMINI.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (df4afc8243ef); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,6 +36,8 @@ 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.
 
+**At the start of every session in this app, run `nerd status` before anything else** (in Claude Code it runs by itself and its output is already above). It lists what the platform has found for this app that someone should act on: a newer `nerd` or SDK, what the model review found in the live code, a package with a newly reported vulnerability. The person who owns this app does not know these exist and should never have to open a dashboard or learn a command to find out. So tell them, in one or two plain sentences with no file names or jargon, and offer to take care of it; if they say yes, fix what is real, run `nerd check`, and deploy. If it prints nothing, say nothing about it. `nerd review` prints the review's findings again with every fix written out.
+
 `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.
@@ -173,6 +175,17 @@ After a deploy is live, `nerd deploy` asks the platform for a model review of th
 - **Secrets** (Stripe keys, API tokens): never in code or in the client. Locally they live in `.dev.vars` (gitignored). For production, ask the person to add it under the app's Settings tab in the dashboard, or to run `nerd secret set NAME` and paste the value; it reaches the app as `c.env.NAME` on the next deploy. Pull request previews do not get it unless it was set with `--previews` (use that only for keys that are safe in a preview, such as a test-mode key). `nerd secret list` shows names only. Do not put a real secret value in any command you run yourself.
 - **Email**: `sendEmail(c.env, { to, subject, text, html?, replyTo? })` from `@nerdsystem/sdk` sends through the platform. The relay only sends to addresses that have an account on this app (someone who signed up); any other recipient is refused with a 400, and the sender name is always the app's name. On the Free plan the recipient must also have confirmed their address by finishing a password reset (403 otherwise); paid plans can write to every signed-up user. It is limited per day by plan (50 on Free, 1,000 on Pro at $39 a month, 2,000 on Studio at $99 a month), so use it for transactional mail such as receipts and notifications, not bulk. Plans can be paid monthly or yearly at ten times the monthly price. Pass `replyTo` (the owner's address, or one they give you) whenever a person might answer the message; without it replies go to a mailbox nobody reads. Mail goes out under the app's name from the platform's address; on Pro and Studio the owner can switch it to their own domain in the dashboard under Settings, which needs no code change.
 
+## Putting the app on the owner's own domain
+
+Paid plans only; on Free the command answers with the plan that includes it, so say that and stop.
+
+1. Run `nerd domains add example.com` with the bare domain the owner gives you. The platform makes `www.example.com` the app's address and sets the bare name up to forward to it. It also looks up which company runs the domain's DNS and prints the exact steps for that company.
+2. Give the owner those steps as printed, numbered. Do not ask who their registrar is, do not show a table of record types, and do not offer alternatives: the platform already chose. The steps are things only they can do (signing in where the domain is managed).
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active`, then open the address and confirm it loads with https. If it is still pending after an hour, run `nerd domains` and read the steps again with them; the usual cause is a leftover parking record.
+4. Tell them two things once it is live: they sign in once more on the new address (same account, same data), and links to the old `.nerdsystem.app` address keep working.
+
+For a subdomain such as `app.example.com`, the same command gives a single record to add.
+
 ## Debugging production
 
 When something is wrong on the deployed app: `nerd logs --since 1h` (add `--q "text"` to search, `--pr 12` for a preview) shows errors with the request that caused them. Reproduce locally with `nerd dev` using the same input, fix it, run `nerd verify`, and deploy or open a pull request. If a deploy made things worse, `nerd rollback` puts the previous production bundle back without touching the database. Write a one-line note on every deploy (`nerd deploy --note "fix: todos query filtered by user"`); the dashboard shows these as a changelog people can read.