@webjsdev/cli 0.10.57 → 0.10.58

package/templates/.agents/rules/workflow.md

@@ -50,15 +50,21 @@ Read `AGENTS.md` first. Full hosted docs are at https://webjs.dev/docs.
 2. Browser tests in `test/<feature>/browser/*.test.js` for hydration, DOM, slots,
    and the client router.
 3. Documentation stays in sync on the SAME PR as the code, never a follow-up.
-4. `npm run check` must pass (correctness), and so must `npm run doctor`
-   (project health). CI runs both. Doctor fails on whatever your `package.json`
-   `webjs.doctor.gate` marks `error`, which starts as the un-versioned
-   stylesheet link check, plus the two hard toolchain checks that default to
-   `error` with no gate entry at all: `NODE_VERSION` (the Node floor) and
-   `TSCONFIG_ERASABLE` (`erasableSyntaxOnly` missing from an existing
-   tsconfig), either of which would 500 the app at runtime. Everything else it
-   reports is a warning that cannot fail the build. Widen or narrow the gate in
-   `package.json` rather than in the workflow.
+4. `npm run ci` must pass before you push. It runs the step list declared in
+   `package.json` under `webjs.ci`, one result line per step: `webjs check`
+   (correctness), `webjs doctor` (project health), `webjs typecheck`, a
+   dependency audit, then the server, browser, and e2e test layers. The GitHub
+   workflow runs the same list on every PR and push, so the two cannot drift;
+   `npm run ci -- --only Tests` runs one layer while you iterate, and
+   `npm run ci -- --signoff` posts a green commit status (basecamp/gh-signoff)
+   a branch-protection rule can require. Doctor fails on whatever your
+   `package.json` `webjs.doctor.gate` marks `error`, which starts as the
+   un-versioned stylesheet link check, plus the two hard toolchain checks that
+   default to `error` with no gate entry at all: `NODE_VERSION` (the Node
+   floor) and `TSCONFIG_ERASABLE` (`erasableSyntaxOnly` missing from an
+   existing tsconfig), either of which would 500 the app at runtime. Everything
+   else it reports is a warning that cannot fail the build. Widen or narrow the
+   gate, and the step list, in `package.json` rather than in the workflow.
 
 How a PR gets REVIEWED is deliberately not specified here. Use whatever your
 team already does. WebJs has opinions about the code (the conventions above,

package/templates/.agents/skills/webjs/SKILL.md

@@ -264,6 +264,7 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 
 ## Testing Defaults
 
+- `npm run ci` before every push: it runs the `webjs.ci` step list in `package.json` (correctness, project health, types, a dependency audit, then the server, browser, and e2e test layers) with a result line per step, and CI runs the same list, so a green local run predicts the pipeline. `npm run ci -- --only Tests` runs one layer while iterating. See `references/testing.md` and `references/built-ins.md`.
 - Prefer server/handler tests first: drive the app with `handle()` from `@webjsdev/server/testing` and assert on the `Response`.
 - Add a browser test (`npm run test:browser`) for anything touching hydration, the client router, slots, or custom-element upgrade. A unit test is necessary but NOT sufficient for a browser-facing change.
 - Render the app and LOOK for any UI change: `npm run check` and `npm run typecheck` pass even when a layout collapses. Static tools give no signal for a visual defect.

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -216,6 +216,48 @@ An over-limit body responds `413` without buffering the whole payload.
 
 `before` runs to completion first (a non-zero exit aborts the boot). `parallel` (dev only) runs long-lived watchers alongside the server and tears them down on exit. `watch` (dev only) adds extra live-reload directories outside the app tree.
 
+### Local CI (`webjs.ci`)
+
+`webjs ci` runs the step list the block declares, the Rails 8.1 `bin/ci` posture: your machine is the first CI runner, and a cloud pipeline runs the SAME list by calling `npm run ci`, so the two cannot drift. Each step prints a heading, then `✅ <title> passed in 2.11s` or `❌ <title> failed in 0.01s`; the run ends with every failure listed and one total line, and exits 1 on any failure.
+
+```jsonc
+{ "webjs": { "ci": { "steps": [
+  { "title": "Setup", "run": "webjs db migrate" },
+  { "title": "Checks", "parallel": 2, "steps": [        // two at a time
+    "webjs check",                                       // a string is a command titled by itself
+    { "title": "Types", "run": "webjs typecheck" },
+    { "title": "Tests", "steps": [                       // a nested group takes ONE slot, runs in order
+      { "title": "Tests: server", "run": "webjs test --server" },
+      { "title": "Tests: e2e", "run": "webjs test --server", "env": { "WEBJS_E2E": "1" } }
+    ] }
+  ] }
+] } } }
+```
+
+A step is a string, a `{ title, run, env? }` command, or a `{ title, steps, parallel? }` group. `parallel` is a slot count (default 1); a parallel group captures each step's output and replays it whole when the step finishes, so two steps never interleave, and a group nested inside it takes one slot and runs sequentially (it cannot declare `parallel`, which the reader reports rather than honours). `env` is per-step, so the e2e opt-in does not depend on a shell prefix. Every child runs with `CI=true`, `node_modules/.bin` on PATH, and `.env` loaded first (a real env var wins), so a `webjs db migrate` step sees `DATABASE_URL`.
+
+Flags: `-f` / `--fail-fast` stops after the first failure (the default runs everything and lists every failure), `--only <title>` runs one step or group by title (repeatable, an unknown title is an error rather than an empty green run), `--json` emits one document on stdout (`{ ok, seconds, steps: [{ title, run, group, ok, code, seconds, output? }] }`, failed steps carrying their captured output, the human report on stderr) for an agent loop, and `--signoff` runs `gh signoff` after a green run. To hold a merge until a LOCAL run is green, install `basecamp/gh-signoff`, run `gh signoff install` once (a branch-protection rule requiring the `signoff` status), and run `npm run ci -- --signoff`; a red run posts nothing.
+
+Under GitHub Actions each step is a `::group::` in the log, a failed step is an `::error::` annotation, and a step table is appended to the job summary, so a single job running the whole list still names the layer that broke. The scaffold's workflow is exactly that one job; `webjs create --skip-ci` omits it and the local list always ships. A malformed block (a group with no title, a nested `parallel`, an unknown key) refuses to run and names every problem by JSON path, because a silently dropped step is a check that never ran. Nothing declared is exit 1 too, naming any workspace member that declares one, since "ran zero steps" would read as green.
+
+### Bring your own ORM (`webjs.db`)
+
+Drizzle is the scaffold DEFAULT, not lock-in. The runtime never imports it, `db/connection.server.ts` is the app's own file, and `webjs db` is adapter-driven: a `db` block maps each verb to the shell command `webjs db <verb>` runs instead of the drizzle-kit default (node_modules/.bin on PATH like a `before` step, extra CLI args appended).
+
+```jsonc
+{ "webjs": {
+  "db": {
+    "generate": "prisma migrate dev --create-only",
+    "migrate":  "prisma migrate deploy",
+    "push":     "prisma db push",
+    "studio":   "prisma studio",
+    "reset":    "prisma migrate reset --force"
+  }
+} }
+```
+
+Any key is a verb (`reset` above adds `webjs db reset`). A verb the block does not name keeps its default (drizzle-kit for `generate` / `migrate` / `push` / `studio`, `db/seed.server.ts` for `seed`), so an app with no block is unchanged and the scaffold emits none. The payoff is that `webjs db migrate` stays one spelling across ORMs, so the scaffolded `dev.before` / `start.before`, the Dockerfile, CI, and the deploy docs all keep working after a swap. Write the bare binary (`prisma migrate deploy`), not `npx prisma ...`, since a pure Bun image has no `npx`. The swap itself is the app's own files: replace `db/connection.server.ts` with the new client, drop `drizzle.config.ts` / `db/columns.server.ts`, and keep server-only imports behind `.server.ts` as before.
+
 ### Doctor severity gate
 
 `webjs doctor` reports project health, and by default only a broken toolchain fails the exit. `--strict` makes EVERY warning fatal, which is unusable in CI, because four checks are environment-shaped: `GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, and `FRAMEWORK_RESOLVE` plus `FRAMEWORK_LINKS` depend on the environment. So per-check severity is CONFIG, keyed by the stable code every result carries.

package/templates/.agents/skills/webjs/references/styling.md

@@ -115,7 +115,7 @@ So near an island the fragment is the smaller and more predictable choice, not a
 
 ### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
 
-An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. Conflicts are keyed on the CSS PROPERTY wherever `cn` can tell the properties apart, rather than on the shared class prefix, so the common prefix collisions do NOT evict: `cn('border-2', 'border-primary')` keeps both (a width and a colour), `cn('flex', 'flex-1')` keeps both (a `display` and a `flex-grow`, the shape an element that is both a flex container and a flex child needs), `cn('shadow-lg', 'shadow-red-500')` keeps both (a box-shadow and its colour), `cn('bg-clip-text', 'bg-primary')` keeps both (a clip and a colour, so the gradient-text idiom survives a later background), and an arbitrary value carrying a type hint is read as the property the hint names (`cn('shadow-lg', 'shadow-[color:red]')` keeps both). It is a small hand-rolled merger, not `tailwind-merge`, so it is still coarse in two ways. A prefix outside the families it knows is not grouped at all, so both classes are emitted and the winner is left to compiled stylesheet order (`inset-shadow-sm` against `inset-shadow-red-500`, `ring-2` against `ring-red-500`). And where one prefix carries two properties it reads the value against Tailwind's DEFAULT scales, so a `@theme`-extended name it cannot know about can still be misread and evict the wrong class: a custom `--shadow-card` makes `shadow-card` a box-shadow, but `cn` sees an unfamiliar name under a prefix whose bare names are usually colours and treats it as one. When an override has to win and you are unsure, pass the one class rather than layering, or install `clsx` + `tailwind-merge` and replace the helper (its header comment shows the swap). For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size.
+An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. Conflicts are keyed on the CSS PROPERTY wherever `cn` can tell the properties apart, rather than on the shared class prefix, so the common prefix collisions do NOT evict: `cn('border-2', 'border-primary')` keeps both (a width and a colour), `cn('flex', 'flex-1')` keeps both (a `display` and a `flex-grow`, the shape an element that is both a flex container and a flex child needs), `cn('shadow-lg', 'shadow-red-500')` keeps both (a box-shadow and its colour), `cn('bg-clip-text', 'bg-primary')` keeps both (a clip and a colour, so the gradient-text idiom survives a later background), and an arbitrary value carrying a type hint is read as the property the hint names (`cn('shadow-lg', 'shadow-[color:red]')` keeps both). It is a small hand-rolled merger, not `tailwind-merge`, so it is still coarse in two ways. A prefix outside the families it knows is not grouped at all, so both classes are emitted and the winner is left to compiled stylesheet order (`inset-shadow-sm` against `inset-shadow-red-500`, `ring-2` against `ring-red-500`). And where one prefix carries two properties it reads the value against Tailwind's DEFAULT scales, so a `@theme`-extended name it cannot know about can still be misread and evict the wrong class: a custom `--shadow-card` makes `shadow-card` a box-shadow, but `cn` sees an unfamiliar name under a prefix whose bare names are usually colours and treats it as one. When an override has to win and you are unsure, pass the one class rather than layering, or install `clsx` + `tailwind-merge` and replace the helper (its header comment shows the swap). For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size. Under the opt-in `webjsui lint` (configured by a `lint` block in `components.json`, see `references/ui-kit.md`), `w-9 h-9` is layout and `rounded-full` is shape in the shadcn category taxonomy, so an app running it sets `no-restyle` to `allow: ["layout", "rounded"]` for this idiom to pass: the plain radius group is granted by name without opening the whole `shape` category, and `border-2` beside a helper still fires.
 
 ```ts
 // components/ui/button.ts  (npx webjsdev ui add button, themed to your app)

package/templates/.agents/skills/webjs/references/testing.md

@@ -189,6 +189,17 @@ WEBJS_ELIDE=0 npm run test:e2e
 
 A test that passes under one and fails under the other is a wrong verdict, and `webjs elision` tells you which module and on what evidence. If the component's interactivity is genuinely invisible to static analysis, the fix is `static interactive = true` on it; see `components.md` for what that override does and does not rescue.
 
+## One command for every layer (`webjs ci`)
+
+```sh
+npm run ci                     # the webjs.ci list: check, doctor, typecheck, audit, then every test layer
+npm run ci -- --only Tests     # one step or group by title
+npm run ci -- --fail-fast      # stop at the first failure
+npm run ci -- --json           # one JSON document for an agent loop
+```
+
+The scaffold declares its gate once, in `package.json` under `webjs.ci`, and `npm run ci` runs it with a timed result line per step (the Rails `bin/ci` model). The generated GitHub workflow runs the same list, so a green local run predicts CI. Run it before every push; the pre-commit hook deliberately runs none of it so a commit stays fast. Browser and e2e steps need a Chromium on the machine (`npx playwright install chromium`, plus `puppeteer-core` for the e2e layer), which the workflow installs for itself. The list, the flags, the `--signoff` merge gate, and the JSON shape are in `references/built-ins.md` under "Local CI".
+
 ## Type-checking your tests (`webjs typecheck`)
 
 Your tests are inside the tsconfig `include`, so `npm run typecheck` reads them (#1299). Treat a type error in a test as a failed gate, not a review catch: the checker sees a wrong argument shape or an unannotated parameter in a test the same way it sees one in `app/`.

package/templates/.agents/skills/webjs/references/ui-kit.md

@@ -52,6 +52,31 @@ So the loop is: `add` the component, then query `ui <name>` (MCP) or
   that ships inside the installed `@webjsdev/ui`, with no network. This pins you
   to the installed version; run `npx webjsdev ui diff` to see where your local copies
   drift from the upstream (that command alone compares against the live registry).
+- `npx webjsdev ui lint` is an OPT-IN design-system linter over the app's own
+  source. It reads the Tailwind classes in `html` templates, `cn()` calls and
+  `class=${...}` holes and reports, at the line, a raw palette colour where the
+  theme declares a role token (`no-raw-colors`, with a message naming only the
+  `--color-*` tokens the configured `tailwind.css` actually declares), an
+  arbitrary value such as `p-[13px]` (`no-arbitrary-values`; an arbitrary
+  VARIANT like `[&_svg]:size-4` never fires), and a class composed over a kit
+  helper (`no-restyle`, naming the helper's real variants and sizes read from
+  the app's copied `components/ui/*.ts`). It is off until `components.json`
+  carries a `lint` block, and with no block it reports nothing and exits 0.
+  `components/ui/**` is skipped by default (a copied primitive owns structural
+  values no variant expresses), and `allow` uses shadcn's category taxonomy
+  (`layout`, `color`, `typography`, `spacing`, `shape`, `effects`, `motion`) or
+  a class-group id such as `rounded`. `--json` emits `{ violations, summary }`
+  for an agent loop; `--max-warnings <n>` pins a count.
+
+  ```json
+  "lint": {
+    "rules": {
+      "no-raw-colors": "warn",
+      "no-arbitrary-values": { "severity": "warn", "allow": ["layout"] },
+      "no-restyle": { "severity": "error", "allow": ["layout", "rounded"] }
+    }
+  }
+  ```
 
 ## Inventory (run `npx webjsdev ui list` or the MCP `ui` tool for the authoritative, current set)
 

package/templates/.github/pull_request_template.md

@@ -4,10 +4,9 @@
 
 ## Test plan
 
-- [ ] Unit tests added/updated (`webjs test` passes)
-- [ ] E2E tests added/updated for user-facing changes (`webjs test --e2e` passes)
-- [ ] `webjs check` passes (no convention violations)
-- [ ] `webjs doctor` passes (project health; it fails on whatever `webjs.doctor.gate` marks `error`, plus the hard `NODE_VERSION` / `TSCONFIG_ERASABLE` checks)
+- [ ] `webjs ci` passes locally (the `webjs.ci` step list in package.json: `webjs check`, `webjs doctor`, `webjs typecheck`, the dependency audit, and the server / browser / e2e test layers; CI runs the same list)
+- [ ] Unit tests added/updated
+- [ ] E2E tests added/updated for user-facing changes (`WEBJS_E2E=1 webjs test`)
 
 ## Definition of done
 

package/templates/.github/workflows/ci.yml

@@ -1,15 +1,25 @@
 name: CI
 
-# The test gate for {{APP_NAME}}. Runs the full test pyramid on every PR
-# into main and on every push to main. This is the gate the local
-# pre-commit hook deliberately leaves out, so `git commit` stays fast and
-# the test gate runs in one authoritative place a local --no-verify cannot
-# skip. Same posture as the webjs framework's own CI.
+# The cloud half of CI for {{APP_NAME}}. The step list itself lives in
+# package.json under "webjs": { "ci": { "steps": [...] } }, and `npm run ci`
+# runs it: on a developer machine before a push, and here on every PR into
+# main and every push to main, so the two can never drift. This job only
+# prepares the runner (Node, dependencies, a browser, the database) and then
+# runs that one command.
 #
-# The four layers run as separate jobs so a failure names the layer that
-# broke. Mark all four as required status checks in the branch-protection
-# rule for main so a PR can only merge when every layer is green. Free on
-# public repos (ubuntu-latest has unlimited Actions minutes).
+# One job on purpose. Each step is still a collapsible log group with its own
+# result line, a failing step is annotated, and the run's step table lands in
+# the job summary, so a failure names the layer that broke. Mark this job as a
+# required status check in the branch-protection rule for main. A team that
+# wants one required check PER LAYER can add a matrix job that runs
+# `npx webjs ci --only "<group title>"` per entry.
+#
+# The local pre-commit hook deliberately runs none of this, so a commit stays
+# fast; `npm run ci` before pushing is the local gate. To hold a merge until a
+# LOCAL run is green, `npm run ci -- --signoff` posts a green commit status
+# through basecamp/gh-signoff, which branch protection can require (`gh signoff
+# install`), the Rails posture. Free on public repos (ubuntu-latest has
+# unlimited Actions minutes).
 
 on:
   pull_request:
@@ -17,40 +27,21 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 # A newer push to the same branch cancels the older in-flight run.
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  conventions:
-    name: Conventions (webjs check)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - run: npm run check
-      # Project health, on top of the correctness checks. WHICH findings are
-      # fatal is your call, declared in package.json under
-      # "webjs": { "doctor": { "gate": { "<CODE>": "off" | "warn" | "error" } } },
-      # so this step and a local `npm run doctor` always agree. The scaffold
-      # starts with UNMARKED_ASSET_LINKS at error (an un-versioned /public url
-      # is a real deploy-staleness bug). Two checks fail with no gate entry at
-      # all, NODE_VERSION and TSCONFIG_ERASABLE, because either would 500 the
-      # app at runtime; everything else stays a warn and cannot fail this job.
-      # Widen or narrow the gate in package.json, not
-      # here. Deliberately not --strict: the git-hook, env-drift, vendor-pin,
-      # and framework-resolve checks are environment-shaped and would fail a
-      # perfectly healthy runner.
-      - run: npm run doctor
-
-  unit:
-    name: Unit + integration (node --test)
+  ci:
+    name: CI (npm run ci)
     runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      DATABASE_URL: file:./ci.db
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
@@ -58,58 +49,17 @@ jobs:
           node-version: '24'
           cache: npm
       - run: npm ci
-      - name: Set up the database (generate + apply migrations)
-        run: npm run db:generate && npm run db:migrate
-        env:
-          DATABASE_URL: file:./ci.db
-      # --server keeps this job to node:test (the browser layer is its own
-      # job below). Without WEBJS_E2E the e2e folders are skipped too.
-      - run: npm run test:server
-        env:
-          DATABASE_URL: file:./ci.db
-
-  browser:
-    name: Browser (web-test-runner / Playwright)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - name: Install Playwright Chromium
+      - name: Install Playwright Chromium (browser + e2e layers)
         run: npx playwright install --with-deps chromium
-      - run: npm run test:browser
-
-  e2e:
-    name: E2E (full app boot)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - name: Set up the database (generate + apply migrations)
-        run: npm run db:generate && npm run db:migrate
-        env:
-          DATABASE_URL: file:./ci.db
-      # The scaffold's e2e test (test/hello/e2e/) drives a real browser
-      # via puppeteer-core, which is not a default dependency (the test
-      # skips when it is absent). Install it and Chromium so the e2e
-      # layer actually runs in CI rather than skipping silently.
-      - name: Install puppeteer-core + Chromium
-        run: |
-          npm install --no-save puppeteer-core
-          npx playwright install --with-deps chromium
+      # The scaffold's e2e test (test/hello/e2e/) drives a real browser via
+      # puppeteer-core, which is not a default dependency (the test skips when
+      # it is absent). Install it so the e2e layer runs here rather than
+      # skipping silently.
+      - name: Install puppeteer-core
+        run: npm install --no-save puppeteer-core
       - name: Resolve the Chromium binary path
         run: echo "CHROMIUM_PATH=$(node -e "console.log(require('playwright-core').chromium.executablePath())")" >> "$GITHUB_ENV"
-      # --server with WEBJS_E2E=1 runs node:test including the e2e folders
-      # (the runner gates them on that env var) and skips the browser layer.
-      - name: Run e2e
-        env:
-          WEBJS_E2E: '1'
-          DATABASE_URL: file:./ci.db
-        run: npm run test:server
+      - name: Set up the database (generate + apply migrations)
+        run: npm run db:generate && npm run db:migrate
+      # Everything above prepares the runner. This is the whole gate.
+      - run: npm run ci

package/templates/.hooks/pre-commit

@@ -7,10 +7,11 @@
 #
 # To bypass in emergencies: git commit --no-verify
 #
-# Tests and convention checks run in CI (.github/workflows/ci.yml), not
-# here, so a commit stays fast and the test gate cannot be skipped by a
-# local --no-verify. The CI workflow runs `webjs check` + `webjs test`
-# on every push and pull request.
+# Tests and convention checks do not run here, so a commit stays fast. The
+# step list lives in package.json under "webjs": { "ci" }. Run it locally
+# with `npm run ci` before pushing (the local gate), and the CI workflow
+# (.github/workflows/ci.yml) runs the same list on every push and pull
+# request, where a local --no-verify cannot skip it.
 #
 # Running more than one AI agent on this repo at once? Give each task its own
 # git worktree, not a shared checkout. Two agents in one working directory

package/templates/partials/agents-playbook-api.md

@@ -44,15 +44,20 @@ cross-origin access use the `cors()` middleware from `@webjsdev/server`; with
 
 ### 5. Verify before you call it done
 
-Run each of these and fix what it reports, in order:
+Run `npm run ci` and fix what it reports. It is one command for every gate,
+the step list declared in `package.json` under `webjs.ci`, with a result line
+per step:
 
-- `npm run check` (correctness: no browser-import or boundary violation).
-- `npm run doctor` (project health; CI runs it too). It fails on whatever
-  `package.json` `webjs.doctor.gate` marks `error`, plus the two hard toolchain
-  checks that are fatal with no gate entry, `NODE_VERSION` and
-  `TSCONFIG_ERASABLE`.
-- `npm run typecheck` (zero type errors).
-- `npm test` (unit tests for the endpoints and modules you built).
+- `webjs check` (correctness: no browser-import or boundary violation).
+- `webjs doctor` (project health). It fails on whatever `package.json`
+  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
+  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
+- `webjs typecheck` (zero type errors).
+- A dependency audit.
+- The test layers for the endpoints and modules you built.
+
+The GitHub workflow runs the same list, so a green local run predicts CI.
+While iterating, `npm run ci -- --only Tests` runs one layer.
 
 Then boot `npm run dev` and probe each endpoint for the expected status and JSON
 shape.
@@ -66,6 +71,7 @@ npm run dev             # dev server at http://localhost:8080
 npm run start           # production server
 npm test                # unit + browser tests
 npm run typecheck
+npm run ci              # every gate, one command (the webjs.ci steps in package.json)
 npm run check           # correctness checks
 npm run doctor          # project health (severity per check: webjs.doctor.gate)
 npm run db:generate && npm run db:migrate

package/templates/partials/agents-playbook-fullstack.md

@@ -95,16 +95,21 @@ accessor). Use the shorthand for primitives
 
 ### 7. Verify before you call it done
 
-Run each of these and fix what it reports, in order:
-
-- `npm run check` (correctness: no browser-import or boundary violation).
-- `npm run doctor` (project health; CI runs it too). It fails on whatever
-  `package.json` `webjs.doctor.gate` marks `error`, plus the two hard toolchain
-  checks that are fatal with no gate entry, `NODE_VERSION` and
-  `TSCONFIG_ERASABLE`.
-- `npm run typecheck` (zero type errors).
-- `npm test` (unit and browser tests for the features you built).
-- `npm run css:build` (compile Tailwind).
+Run `npm run ci` and fix what it reports. It is one command for every gate,
+the step list declared in `package.json` under `webjs.ci`, with a result line
+per step:
+
+- `webjs check` (correctness: no browser-import or boundary violation).
+- `webjs doctor` (project health). It fails on whatever `package.json`
+  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
+  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
+- `webjs typecheck` (zero type errors).
+- A dependency audit.
+- The server, browser, and e2e test layers for the features you built.
+
+The GitHub workflow runs the same list, so a green local run predicts CI.
+While iterating, `npm run ci -- --only Tests` runs one layer. Then
+`npm run css:build` (compile Tailwind).
 
 Then boot `npm run dev`, confirm every page route returns HTTP 200, and open
 every route you changed in a real browser and play through its states: `check`
@@ -121,6 +126,7 @@ npm run start                # production server
 npm test                     # unit + browser tests
 npm run typecheck
 npm run css:build            # compile Tailwind
+npm run ci                   # every gate, one command (the webjs.ci steps in package.json)
 npm run check                # correctness checks
 npm run doctor               # project health (severity per check: webjs.doctor.gate)
 npx webjsdev ui add <name>   # copy a ui primitive into components/ui/