@webjsdev/cli 0.9.1 → 0.10.1

package/templates/.cursorrules

@@ -1,6 +1,6 @@
-# Cursor Rules - webjs app
+# Cursor Rules: webjs app
 
-You are working on a webjs app - an AI-first, no-build, web-components-first
+You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md doesn't
 cover what you need, the full hosted docs are at **https://docs.webjs.com**.
@@ -36,7 +36,7 @@ FIRST, before writing any code:
    - If upstream has new commits: `git rebase origin/main` before starting.
    - Resolve any conflicts before proceeding with the task.
 
-## Autonomous mode (sandbox / no-prompt mode)
+## Autonomous mode (sandbox / no-prompt)
 
 If running without interactive approval, auto-decide:
 - On main? Auto-create feature/<task-slug> branch
@@ -44,29 +44,44 @@ If running without interactive approval, auto-decide:
 - Merge? Auto-merge in autonomous mode, delete feature branches after
 - Commit message? Auto-generate (meaningful, no AI attribution)
 - Tests failing? Fix them. Convention violations? Fix them.
-Quality bar stays the same - just no blocking on questions.
+Quality bar stays the same, no blocking on questions.
 
 ## Mandatory workflow (never skip)
 
-1. TESTS: Server tests in test/<feature>/ (node:test), browser tests in
-   test/<feature>/browser/ (WTR + Playwright, real Chromium). Run `webjs test`
-   after every change. Never deliver code without passing tests.
+Every code change must include:
+1. Server tests in `test/<feature>/*.test.ts` (node:test).
+2. Browser tests in `test/<feature>/browser/*.test.js` (WTR + Playwright, real Chromium).
+3. Documentation updates. Walk every surface in the **Definition of done**
+   section of CONVENTIONS.md (AGENTS.md, CONVENTIONS.md, README.md, docs/,
+   website/, scaffold scripts) and either update it or write
+   "N/A because <reason>" in the PR body. Docs land on the same PR as the
+   code, never as a follow-up.
+4. Convention check: `webjs check` must pass.
+5. Pre-merge self-review loop. Before saying the PR is ready for merge, run
+   fresh-context review rounds until one round finds zero issues. Cursor
+   primitive: open a NEW composer tab and prompt the review there so the
+   reviewer has no prior context on your decisions. Minimum two rounds;
+   rotate focus each round. Skip the loop only for one-line trivial
+   changes; skipping on a change that touches logic, public surface, build,
+   security, or multiple files is the exact failure mode the loop exists
+   to prevent. The full rule, prompt template, and reporting contract live
+   in the **Pre-merge self-review loop** section of CONVENTIONS.md.
 
-2. DOCS: Update AGENTS.md for API changes. Update docs/ and website/ if
-   they exist. The user should never have to ask for tests or docs.
-
-3. CONVENTIONS: Run `webjs check` and fix violations before committing.
+The user should never have to ask for tests, documentation, or the
+self-review loop.
 
 ## Git rules
 
 - COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix,
   one rename, one doc rewrite per commit. Always `git push` after
-  committing. This is automatic.
+  committing. The user should never have to ask for a commit.
 - HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
-  commit before continuing. The Claude Code hook at
-  `.claude/hooks/nudge-uncommitted.sh` fires at threshold 4. Cursor users
-  should self-enforce the same rule. Batching multiple logical units into
-  one commit is the failure mode this rule exists to prevent.
+  commit before continuing. Cursor 1.7+ has its own
+  `.cursor/hooks/nudge-uncommitted.sh` (afterFileEdit) firing at threshold
+  4; the same enforcement runs for Claude users via
+  `.claude/hooks/nudge-uncommitted.sh`. On older Cursor versions without
+  the hook, self-enforce the same rule. Batching multiple logical units
+  into one commit is the failure mode this rule exists to prevent.
 - Write meaningful commit messages: what changed and why, not "update files"
 - NEVER add "Co-Authored-By", "Generated by", "AI-assisted" or similar
   attribution trailers to commits
@@ -77,23 +92,22 @@ Quality bar stays the same - just no blocking on questions.
   Plain hyphens stay fine in compound words, CLI flags, filenames,
   and ranges. Semicolons stay fine inside code
 - Work on feature branches, not main
-- NEVER push directly to main - create a pull request
+- NEVER push directly to main. Create a pull request instead.
 - NEVER merge any branch without explicit user permission. Always ask:
   "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
   Wait for approval AND the delete/keep preference before proceeding.
   This applies to ALL merges, not just merges into main.
 - Run tests before every commit
-- Keep commits small and focused
 
 ## Framework rules
 
 - No build step: source files are served as ES modules
-- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server falls back to esbuild + inline sourcemap for those files (~3x wire bytes per request).
+- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Web components with shadow DOM: use `static styles = css` not inline styles
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
 - Server-only code (@prisma/client, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
-- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported - use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
-- **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content (read SSR-meaningful defaults in `constructor()`, not `connectedCallback` - the server doesn't call lifecycle hooks). Initial data for components comes from the page function (server-side fetch + pass as attribute/property), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` + server action over `fetch` + click handler - the framework upgrades plain forms to partial-swap submissions automatically.
-- **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Layouts persist across navigation - put shared chrome (sidenav, header) in `layout.ts`, page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.
+- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
+- **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
+- **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Because layouts persist across navigation, put shared chrome (sidenav, header) in `layout.ts` and page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.
 - See AGENTS.md for the complete directive decision guide

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

@@ -33,53 +33,80 @@ FIRST, before writing any code:
    - If on a feature branch: verify it matches the task at hand.
 2. Sync: `git fetch origin && git rebase origin/main` if behind.
 
-## Autonomous mode
+## Autonomous mode (sandbox / no-prompt)
 
 If running without interactive approval (sandbox, auto-approve, etc.):
 - On main? Auto-create feature/<task-slug> branch
 - Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
 - Auto-generate meaningful commit messages. Fix tests and violations.
 
-## Mandatory workflow
+Quality bar stays the same, no blocking on questions.
+
+## Mandatory workflow (never skip)
 
 Every code change must include:
-1. Commit and push PER LOGICAL UNIT, not at the end. One feature, one fix,
-   one rename, one doc rewrite per commit. Always `git push` after
-   committing. Don't accumulate changes. If you have 5+ unstaged files
-   spanning different concerns, commit before continuing. The Claude Code
-   hook at `.claude/hooks/nudge-uncommitted.sh` enforces threshold 4 for
-   Claude users; Copilot users should self-enforce the same rule. Automatic.
-2. Server tests in test/<feature>/*.test.ts (node:test for actions, queries, utilities)
-3. Browser tests in test/<feature>/browser/*.test.js (WTR + Playwright, real Chromium)
-4. Documentation updates (AGENTS.md for API, docs/ for user guides)
-5. Convention validation: `webjs check` must pass
+1. Server tests in `test/<feature>/*.test.ts` (node:test).
+2. Browser tests in `test/<feature>/browser/*.test.js` (WTR + Playwright, real Chromium).
+3. Documentation updates. Walk every surface in the **Definition of done**
+   section of CONVENTIONS.md (AGENTS.md, CONVENTIONS.md, README.md, docs/,
+   website/, scaffold scripts) and either update or write
+   "N/A because <reason>" in the PR body. Docs land on the same PR as the
+   code, never as a follow-up.
+4. Convention check: `webjs check` must pass.
+5. Pre-merge self-review loop. Before saying the PR is ready for merge,
+   run fresh-context review rounds until one round finds zero issues.
+   Copilot primitive: open a NEW chat session (reset the side panel) for
+   each round so the reviewer has no prior context on the implementation
+   decisions. Minimum two rounds; rotate focus each round. Skip the loop
+   only for one-line trivial changes; skipping on a change that touches
+   logic, public surface, build, security, or multiple files is the exact
+   failure mode the loop exists to prevent. The full rule, prompt
+   template, and reporting contract live in the **Pre-merge self-review
+   loop** section of CONVENTIONS.md.
+
+The user should never have to ask for tests, documentation, or the
+self-review loop. The commit-per-logical-unit rule lives under "Git rules"
+below, not here, since it governs how work is grouped rather than what
+each change must include.
 
 ## Git rules
 
-- Commit after each logical unit of work
+- COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix,
+  one rename, one doc rewrite per commit. Always `git push` after
+  committing. The user should never have to ask for a commit.
+- HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
+  commit before continuing. The Claude Code hook at
+  `.claude/hooks/nudge-uncommitted.sh` enforces threshold 4 for Claude
+  users. Copilot has no equivalent hook surface today; self-enforce the
+  same rule. Batching multiple logical units into one commit is the
+  failure mode this rule exists to prevent.
 - Meaningful commit messages: what changed and why
 - NEVER add Co-Authored-By or AI attribution trailers to commits
+- NEVER use em-dashes (U+2014), a hyphen-as-pause (` - `), or a
+  semicolon-as-pause (` ; `) in commit messages or anywhere else.
+  Rewrite the sentence so no pause-punctuation crutch is needed. Use a
+  period, comma, colon, parentheses, or a restructured phrasing. Plain
+  hyphens stay fine in compound words, CLI flags, filenames, and ranges.
+  Semicolons stay fine inside code.
 - Work on feature branches, create PRs, never push directly to main
 - NEVER merge any branch without explicit user permission. Always ask:
   "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
   Wait for approval AND the delete/keep preference. Applies to ALL merges.
 - Run `webjs test` before every commit
 
-## Code patterns
+## Framework rules
 
-- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server falls back to esbuild + inline sourcemap for those files (~3x wire bytes per request).
-- Tagged template: html`<div>${value}</div>` with css`...` for styles
+- No build step: source files are served as ES modules. Don't introduce
+  build tools or bundlers in the critical path.
+- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
+- Tagged template: html`<div>${value}</div>` with css`...` for styles.
+  Don't use inline `style="..."` on components (use `static styles = css\`...\``).
 - Components: extend WebComponent, declare `static properties` (and `static styles` for shadow-DOM components), call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field.
-- Server actions: *.server.ts files with one exported async function each
-- Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported - use plain template-literal expressions and lifecycle hooks instead.
+- Server actions: *.server.ts files with one exported async function each.
+- Server-only code (@prisma/client, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
+- Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. Use plain template-literal expressions and lifecycle hooks instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'
-- Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts)
-
-## What NOT to do
-
-- Don't introduce build tools or bundlers in the critical path
-- Server-only code (@prisma/client, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
-- Don't use inline style="..." on components (use static styles = css`...`)
+- Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts).
 - Component state lives in signals from @webjsdev/core. Module-scope signals share state across components; instance signals (created in the constructor) carry component-local state. Reactive properties (static properties + declare) are for HTML attributes and .prop=${...} hydration.
-- Don't skip tests or documentation updates
+- Don't skip tests or documentation updates.

package/templates/.github/pull_request_template.md

@@ -8,7 +8,31 @@
 - [ ] E2E tests added/updated for user-facing changes (`webjs test --e2e` passes)
 - [ ] `webjs check` passes (no convention violations)
 
-## Documentation
+## Definition of done
 
-- [ ] AGENTS.md updated (if API surface changed)
-- [ ] Docs updated (if docs/ exists and feature is documented)
+Documentation MUST land on the same PR as the code change. Drift is how
+a codebase rots. Walk every markdown file in the project (`git ls-files
+'*.md'`) and ask whether this PR changed behaviour, surface, or
+invariants it describes. For each row below, write `Updated <path>` or
+`N/A because <reason>`. Reviewers should reject the PR if this section
+is left as the template default. See the **Definition of done** section
+in [`CONVENTIONS.md`](../CONVENTIONS.md) for the full guidance.
+
+- [ ] **Tests.** Unit coverage for logic. Real-browser coverage for
+      user-facing behaviour.
+- [ ] **Every markdown file in the project** that describes the
+      changed surface. Common cases (non-exhaustive): `AGENTS.md` (root
+      + nested), `CONVENTIONS.md`, `README.md` (root + nested),
+      `CHANGELOG.md`, `docs/**/*.md`, `agent-docs/**/*.md`,
+      `.github/*.md`. The rule is generative: if a markdown file in
+      this project mentions a thing this PR changed, it gets touched
+      on this PR.
+- [ ] **`website/`** (if the project has one). Marketing copy on the
+      landing or pricing page when the change touches a claim made
+      there.
+- [ ] **Scaffold scripts / codegen** (if the project has any). Updated
+      when the change affects what new instances generate.
+- [ ] **Pre-merge self-review loop.** Ran N rounds; last round clean.
+      Skip only for one-line trivial changes. See the **Pre-merge
+      self-review loop** section in [`CONVENTIONS.md`](../CONVENTIONS.md)
+      for the prompt template and reporting contract.

package/templates/.hooks/pre-commit

@@ -21,8 +21,33 @@ if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
   exit 1
 fi
 
+# Require a test to accompany app-code changes. Tool-agnostic floor: a
+# commit that stages app code (app/, modules/, components/, lib/) with no
+# test (test/** or *.test.* / *.spec.*) is blocked. The full suite below
+# proves tests PASS; this proves a test was WRITTEN. Bypass for a genuine
+# non-code commit with WEBJS_NO_TEST_GATE=1, or --no-verify in emergencies.
+if [ "${WEBJS_NO_TEST_GATE:-}" != "1" ]; then
+  STAGED=$(git diff --cached --name-only 2>/dev/null)
+  APP_CODE=$(printf '%s\n' "$STAGED" | grep -E '^(app|modules|components|lib)/.*\.([mc]?[jt]sx?)$' || true)
+  if [ -n "$APP_CODE" ]; then
+    TESTS=$(printf '%s\n' "$STAGED" | grep -E '(^|/)test/|\.test\.[mc]?[jt]sx?$|\.spec\.[mc]?[jt]sx?$' || true)
+    if [ -z "$TESTS" ]; then
+      echo ""
+      echo "ERROR: app code changed but no test is staged."
+      echo "Every change ships with a test. Add or update the test that"
+      echo "proves the new behaviour (a browser/e2e test for interactive"
+      echo "or component code), then git add it."
+      echo ""
+      echo "Genuine non-code commit? WEBJS_NO_TEST_GATE=1 git commit ..."
+      echo "Emergency bypass: git commit --no-verify"
+      echo ""
+      exit 1
+    fi
+  fi
+fi
+
 # webjs test + webjs check on every commit. Tool-agnostic enforcement:
-# fires regardless of which agent (Claude, Cursor, Windsurf, Copilot,
+# fires regardless of which agent (Claude, Cursor, Antigravity, Copilot,
 # human) is making the commit. Skipped if the CLI is not yet installed
 # (fresh clone before npm install).
 if command -v webjs >/dev/null 2>&1 || [ -x "node_modules/.bin/webjs" ]; then

package/templates/AGENTS.md

@@ -301,6 +301,20 @@ In Docker / Railway, prefer `npm start` (or `node node_modules/.bin/npm
 start`) as the CMD over `node ... webjs.js start ...`. The npm form
 fires `prestart`; the direct binary form skips it.
 
+**Health and readiness probes.** Every webjs server answers two endpoints:
+`/__webjs/health` (liveness, 200 once the process is listening) and
+`/__webjs/ready` (readiness, 503 until the instance is fully warm, then 200).
+Fully warm means the deterministic analysis AND the first vendor attempt have
+both completed, so the importmap and its build id are settled. Point your
+platform's readiness check at `/__webjs/ready` so it holds traffic off a
+not-yet-warmed instance instead of routing the first user request into the cold
+analysis or the brief window where the importmap is still resolving. On
+Railway, set `"healthcheckPath": "/__webjs/ready"` under `deploy` in
+`railway.json`. For dependency-aware
+readiness (gate on a live DB ping), add an optional `readiness.{js,ts}` at the
+app root that default-exports an async check; `/__webjs/ready` runs it once warm
+and reports 503 if it returns `false` or throws.
+
 Scripts:
 
 - `npm run db:migrate`: `prisma migrate dev` (dev-time schema changes + migration + generate)
@@ -320,6 +334,87 @@ const users = await prisma.user.findMany();
 To switch to Postgres or MySQL: change `provider` in `prisma/schema.prisma`
 and the `DATABASE_URL` in `.env`.
 
+## NPM packages (vendor pipeline)
+
+Adding a third-party npm package follows the same `npm install` flow
+as any Node project, with one webjs-specific concern: how the BROWSER
+fetches that package.
+
+```sh
+npm install dayjs                 # standard npm install
+```
+
+Now write `import dayjs from 'dayjs'` in any component or page. The
+import works in dev immediately. webjs's scanner discovers bare
+imports on the first request (memoized for the process) and asks
+`api.jspm.io` to resolve them to CDN URLs (jspm.io serves pre-bundled
+ESM for every npm package). The browser fetches the bundle directly
+from `https://ga.jspm.io`.
+
+**For production deploys**, run `webjs vendor pin` once and commit
+the result:
+
+```sh
+webjs vendor pin                  # writes .webjs/vendor/importmap.json
+git add .webjs/vendor/
+git commit -m "vendor dayjs"
+```
+
+The pin file holds the resolved jspm.io URLs. Server reads it from
+disk on the first request (memoized); no `api.jspm.io` call needed in
+production. Deterministic across deploys.
+
+**For offline-capable / strict-CSP production**, use `--download`:
+
+```sh
+webjs vendor pin --download       # also vendors bundle bytes locally
+git add .webjs/vendor/
+git commit -m "vendor + download dayjs"
+```
+
+Bundle files land in `.webjs/vendor/<pkg>@<version>.js`. importmap
+points at local `/__webjs/vendor/` paths. Browser fetches from your
+own origin. Suitable for `script-src 'self'` CSP, air-gapped deploys,
+or compliance environments. See [docs.webjs.com Deployment → CSP](https://docs.webjs.com/docs/deployment#csp).
+
+**Other CLI commands:**
+
+```sh
+webjs vendor list                 # show pinned packages with versions
+webjs vendor unpin <pkg>          # remove one entry from pin file
+webjs vendor audit                # npm security advisories against pinned versions
+webjs vendor outdated             # list pinned packages with newer versions on npm
+webjs vendor update               # re-pin every outdated package to its latest
+
+# Switch CDN at pin time (default: jspm.io). Resolver options:
+# jspm, jsdelivr, unpkg, skypack. Useful for jspm.io incident response.
+webjs vendor pin --from jsdelivr
+webjs vendor update --from jsdelivr
+```
+
+Same posture as Rails 7 + importmap-rails: explicit pin command,
+committed manifest, optional `--download` for full offline capability,
+and a `--from` knob to swap the resolver CDN if jspm.io has an
+incident.
+
+**Don't auto-run `webjs vendor pin` in `predev` / `prestart`.** Auto-pin
+would silently churn the committed importmap.json as jspm.io resolves
+URLs or transitive deps drift. Pin is a deliberate developer action,
+like `npm install` itself.
+
+**Do NOT modify the `.webjs/` lines in `.gitignore` / `.dockerignore`.**
+The scaffolded pattern is three lines (`.webjs/*` + `!.webjs/vendor/`
++ `!.webjs/vendor/**`) and is structurally load-bearing. Collapsing it
+to a single `.webjs/` excludes the parent directory; once the parent
+is excluded, git cannot re-include `.webjs/vendor/` via a child
+negation (gitignore semantics: parent exclusion blocks child
+negations). The breakage is invisible: `webjs vendor pin` runs, writes
+files, and git silently ignores them. Production then has no
+importmap.json and the server falls back to calling api.jspm.io on
+every cold start. The `gitignore-vendor-not-ignored` lint rule
+(`webjs check`) verifies the pattern with `git check-ignore` and will
+fail CI if it regresses.
+
 ## Imports
 
 ```ts
@@ -770,9 +865,9 @@ composition, so a nested shell ends up dropped by the HTML parser.
    ```
 
    If you turn `erasableSyntaxOnly` off and use non-erasable syntax,
-   the dev server falls back to esbuild and emits inline sourcemaps
-   for those specific files: roughly 3x wire bytes per request, and
-   stack-trace positions are no longer byte-exact. The
+   the dev server fails at strip time and returns a 500 naming the
+   file and pointing at the `no-non-erasable-typescript` lint rule.
+   webjs is buildless end-to-end and has no bundler fallback. The
    `erasable-typescript-only` convention check warns when the flag
    is missing or set to false.
 9. **No em-dashes (U+2014) anywhere, and no hyphen or semicolon used
@@ -788,8 +883,15 @@ composition, so a nested shell ends up dropped by the HTML parser.
 ## Workflow expectations for AI agents
 
 1. Branch before editing. Never push to `main` directly.
-2. Every code change comes with: unit test(s), AGENTS.md / docs updates if
-   the feature surface changed, `webjs check` passing.
+2. Every code change comes with a test, AGENTS.md / docs updates if the
+   feature surface changed, `webjs check` passing. A unit test is not
+   always enough: a component, hydration, the client router, or a server
+   action called from the client needs a browser test
+   (`webjs test --browser`) asserting the behaviour in a real browser. A
+   commit that stages app code (`app/`, `modules/`, `components/`, `lib/`)
+   with no test is blocked by `.claude/hooks/require-tests-with-src.sh`
+   and the `.hooks/pre-commit` floor (bypass a genuine non-code commit
+   with `WEBJS_NO_TEST_GATE=1`).
 3. Commit and push **per logical unit**, not at the end. A logical unit is one
    feature, one fix, one rename, one doc rewrite. If you have 5+ unstaged files
    spanning different concerns, commit the current group before continuing.
@@ -802,14 +904,25 @@ composition, so a nested shell ends up dropped by the HTML parser.
    | Gemini CLI | `.gemini/hooks/nudge-uncommitted.sh` (`AfterTool`) | `.gemini/settings.json` |
    | Cursor 1.7+ | `.cursor/hooks/nudge-uncommitted.sh` (`afterFileEdit`) | `.cursor/hooks.json` |
    | OpenCode | `.opencode/plugins/nudge-uncommitted.ts` (`tool.execute.after`) | `.opencode/plugins/` |
-   | Windsurf | text rule only (post-write hooks cannot inject context) | `.windsurfrules` |
+   | Antigravity (Google) | text rule only (post-write hooks not yet exposed) | `.agents/rules/workflow.md` |
    | GitHub Copilot | text rule only (no hooks API) | `.github/copilot-instructions.md` |
-   | Google Antigravity | text rule only (no hooks API) | `AGENTS.md` |
 
    Tool-agnostic fallback: `.hooks/pre-commit` runs `webjs test` + `webjs check`
    on every commit, regardless of which agent (or human) made it. No AI
    attribution trailers in commit messages.
-4. When unsure how a framework feature works, `grep` or `cat` the
+4. Run the **pre-merge self-review loop** before signaling the PR is
+   ready. After committing the work, trigger a fresh-context review
+   pass (a new chat / composer tab / subagent / Cascade thread
+   depending on your tool) and iterate fix-then-review rounds until
+   one round finds zero issues. Minimum two rounds; rotate focus each
+   round so the reviewer does not rediscover the same surface twice.
+   Skip the loop only for one-line trivial changes; skipping on a
+   change that touches logic, public surface, build, security, or
+   multiple files is the exact failure mode the loop exists to
+   prevent. The full rule, prompt template, and reporting contract
+   live in the **Pre-merge self-review loop** section of
+   `CONVENTIONS.md`.
+5. When unsure how a framework feature works, `grep` or `cat` the
    relevant `node_modules/@webjsdev/*/src/` file before asking the user.
 
 Project-specific conventions and overrides live in