nerdsystem 0.0.23 → 0.0.25

package/template/GEMINI.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (1794b8a1a530); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (1e4962fc7891); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -31,12 +31,12 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 ## The loop
 
 1. Make the change, and write or update its tests in the same step (see "Build it so it is safe and it works").
-2. `nerd check` (static rules, typecheck, then the tests and access checks). Fix anything it reports.
+2. `nerd check` (static rules, typecheck, then the tests and access checks). Fix anything it reports. When it says the code has changed since its last review (`session/review-due`), review it before you deploy: see "Review what you built before it goes live".
 3. `nerd dev` to run locally when you need to try it. The local app talks to the real auth service, so signup and login work exactly as in production.
 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.
+**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 is still open from the latest review of the 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 what is open from the review 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.
 
@@ -127,6 +127,19 @@ When a test fails, fix the app. Change a test only when the behaviour it describ
 
 What the tests do not prove: that the feature is the one the person wanted, or that its rules (who may book which slot, what a discount applies to) are right. Say what you built and what is public when you hand it over, so they can tell you if it is wrong.
 
+### Review what you built before it goes live
+
+Tests show the app does what was checked. They cannot show that the server trusts a price the browser sent, that any signed-in person can approve what only staff should, or that two people can book the same slot. Looking for those is your job, before every deploy that changes the server, the data model, or what a screen does. Nobody else reads each change: nerdsystem reads the code itself only now and then.
+
+1. Run `nerd review checklist`. It prints what to look for (the `review/` rules), the files that changed since the last review, the findings still open from earlier reviews, and the format of the report.
+2. Have it done with fresh eyes. In Claude Code, give the whole checklist to the `nerd-reviewer` subagent that ships in `.claude/agents/` (it only reads; if this session does not have it yet, use any read-only subagent). In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself, reading the files again from disk and not from memory.
+3. Check each thing raised against the code, because a review can be wrong. Fix what is real. A finding marked "for the person to decide" is theirs: ask it as a plain question, with no file names, and wait for the answer.
+4. Write `.nerd/review.json` as the checklist describes and run `nerd review report`. Then `nerd check` and `nerd deploy`.
+
+The report is stored as your review, and the person sees it in their dashboard under Review together with the plain-language summary you wrote for them, so write that for someone who cannot read code. Report what you found, including what you fixed. When nerdsystem does read the code itself, it compares: a finding from its read stays open until your report says it is still there, fixed, or checked and not applicable, and a clean report it then contradicts is recorded as a miss. Never report a review you did not do, and never use `dismissed` to make a finding go away.
+
+Keep it in proportion. Review the files that changed, not the whole app each time; a change to wording or styling alone does not need one. The first review of an app reads everything.
+
 ## Data rules
 
 - Every table holding user data has a `user_id` text column, and every read and write filters on `c.var.user.id`. This is how users are kept apart.
@@ -167,7 +180,7 @@ Without MCP, `nerd check --json` returns the same shape, and `nerd check --rule
 
 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.
+After a deploy is live, `nerd deploy` prints what is open from the review on file (the `review/` rules): usually the one you reported with `nerd review report`, and now and then nerdsystem's own read of the stored code, which runs on an app's first deploy and about weekly on paid plans when the code has changed, and takes a minute or two. Either way 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 answer each in your next report. Findings marked "for the person to decide" are theirs: put the question to them in plain words and wait. The person's own page for the review is in the dashboard under Review; point them to it.
 
 ## Scheduled jobs and email
 
@@ -181,7 +194,7 @@ Paid plans only; on Free the command answers with the plan that includes it, so
 
 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.
+3. When they say it is done, run `nerd domains` every minute or two until the status is `active` and the "bare name" column says it forwards here, then open both addresses and confirm they load 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.