@webjsdev/cli 0.10.40 → 0.10.41

package/templates/.cursorrules

@@ -1,189 +1,21 @@
-# Cursor Rules: webjs app
-
-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.dev**.
-
-## Persistence + scaffold rules (non-negotiable)
-
-- **Use Drizzle + SQLite for data, never JSON files.** It's already wired up
-  (`db/schema.server.ts`, `db/connection.server.ts`, `npm run db:generate` + `npm run db:migrate`). For ANY
-  data the app stores (todos, posts, messages, products, comments…),
-  define a Drizzle table. NEVER create `data/*.json`, `db.json`, or any
-  JSON file as a fake database. NEVER use module-scope arrays / Maps as
-  a substitute. NEVER use localStorage for app data. These are project conventions in CONVENTIONS.md (a JSON file used as a
-  database resets on reload and cannot scale).
-- **The scaffold is reference, not the final product.** Replace
-  `app/page.ts`, the example `User` model, the example users module, etc.
-  with the app the user actually asked for. Don't ship "Hello from
-  <app-name>" as the deliverable.
-- **Study the gallery first, prune it second.** The full-stack and saas scaffolds ship
-  single-feature demos under `app/features/` plus one whole example app under
-  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
-  read every demo end to end (code AND comments) to learn the idioms BEFORE you
-  write or delete anything. Only after internalising the patterns should you
-  prune, keeping and adapting what you need and deleting the rest (the
-  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
-  for the todo app, also the `todos` table). Never delete blindly up front. Each
-  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
-  until you resolve it. Delete now-empty directories after pruning. The `api`
-  template ships a BACKEND-features showcase instead (endpoints under
-  `app/api/features/`: the `route()` adapter + validation, rate limiting,
-  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
-  listed in the root `app/route.ts` index; prune it the same way.
-- **Prune what the app does not use.** Keep the infrastructure the app
-  USES and delete the rest (files AND folders). No persistence means
-  delete `db/`, `drizzle.config.ts`, and the `db:*` scripts. No UI kit
-  used means delete `components/ui/`, `components.json`, and
-  `lib/utils/cn.ts`. No PWA means delete `public/sw.js` and
-  `offline.html`. Always KEEP the durable knowledge (`AGENTS.md`,
-  `CONVENTIONS.md`, the rule files, the MCP), never prune it, so removing
-  example code never removes your context. Prune AFTER using the features
-  and examples as reference, never blindly up front. A no-op for the `api` template
-  (no UI kit, no PWA files).
-- **`app/` is routing-only.** Only routing files live in `app/` (page,
-  layout, route, middleware, metadata routes). CSS, helpers, and constants
-  do NOT: `globals.css` is at `styles/`, browser-safe helpers at
-  `lib/utils/`, feature logic in `modules/`.
-- **Use a unique design, and redesign means more than recolor (UI apps).** Give
-  the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
-  from what the app IS. `app/layout.ts` ships as a MINIMAL shell (theme, design
-  tokens, and Tailwind infra, then `${children}` in a bare padded container) with
-  NO header, nav, footer, or reading column: design the app's own chrome from
-  scratch. Decide whether it needs a header at all, a nav (or none), a footer, a
-  sidebar, a centered reading column, or a full-bleed canvas, from what fits the
-  app. `LAYOUT-REFERENCE.md` at the project root is a complete worked layout to
-  learn the patterns from, then build your own. Two `webjs-scaffold-placeholder`
-  markers gate `webjs check`: the minimal shell ("design your layout from
-  scratch") and the palette block ("own the colors"), so check fails until each
-  is addressed. Keep the design TOKENS and theme wiring in `app/layout.ts`
-  (infrastructure the ui kit reads) and set the token VALUES to your own palette;
-  run `webjs check --clear-placeholders` to keep the starter palette
-  deliberately. Style with Tailwind utilities wherever they reach, and use custom
-  CSS only for what utilities cannot express (@theme tokens, @keyframes,
-  scrollbar, complex color-mix or gradients). The `api` template has no UI, so
-  this does not apply there.
-- **Render the app and LOOK before you call UI work done (every agent, not just one harness).**
-  You write CSS blind, so a layout or design defect ships silently: `webjs check`
-  and `webjs typecheck` pass even when a component collapses, grid cells are
-  uneven, the layout resizes as it fills, or the app just kept the scaffold's
-  colors. Static tools give no failure signal for this. The only thing that
-  catches it is rendering the app and looking at the pixels. So for ANY page,
-  layout, or component work: run it (`webjs dev`), open every route you changed in
-  a real browser (drive it with your harness's browser tool or MCP if it has one,
-  otherwise open it yourself and screenshot), and PLAY THROUGH every state (empty,
-  filled, win, draw, reload, narrow and wide, light and dark). Confirm nothing
-  collapses or reflows, that cells stay equal, that the design is the app's OWN,
-  and that both themes read. Ship a real-browser test (`webjs test --browser`) for
-  the mechanical floor (measure `getBoundingClientRect()` and assert cells stay
-  equal across a move). Fix and re-render until it holds, then state in your final
-  message what you rendered and confirmed. Claude Code additionally ENFORCES this
-  via the `webjs-design-review` skill plus a Stop hook, but the discipline is
-  harness-agnostic and this rule is the source of truth for every agent.
-- **Only three templates exist:** `webjs create <name>` (default
-  full-stack), `--template api`, `--template saas`. The CLI rejects any
-  other `--template` value. Pick:
-  - Any product UI (todo, blog, dashboard, marketplace, social…) → default
-  - HTTP/JSON API only, no UI → `--template api`
-  - Auth / login / signup / SaaS → `--template saas`
-
-## Before starting ANY work
-
-FIRST, before writing any code:
-1. Run `git branch --show-current` to check the branch.
-   - If on main/master: STOP. Ask the user which branch to use, or create
-     one with `git checkout -b feature/<name>`.
-   - If on a feature branch: verify it matches the current task. Ask if unsure.
-2. Sync with parent: `git fetch origin && git log HEAD..origin/main --oneline`
-   - If upstream has new commits: `git rebase origin/main` before starting.
-   - Resolve any conflicts before proceeding with the task.
-3. If more than one agent may work this repo at once, use a DEDICATED git
-   worktree per task, not a shared checkout: `git worktree add -b <branch>
-   ../<repo>-<slug> origin/main`, `cd` in, work there, `git worktree remove`
-   after merge. Two agents in one directory collide (a `git checkout` in one
-   moves HEAD under the other, so commits land on the wrong branch). A lone
-   agent in a clean checkout may use a plain branch.
-
-## Autonomous mode (sandbox / no-prompt)
-
-If running without interactive approval, auto-decide:
-- On main? Auto-create feature/<task-slug> branch
-- Parent has new commits? Auto-rebase before starting
-- 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, no blocking on questions.
-
-## Mandatory workflow (never skip)
-
-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.
-
-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. The user should never have to ask for a commit.
-- HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
-  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
-- 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, not main
-- 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
-
-## Framework rules
-
-- No build step: source files are served as ES modules
-- **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (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.
-- **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css`) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag.
-- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
-- Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
-- One function per server action file (*.server.ts)
-- **`.server.ts` vs `'use server'`, the decision.** Will the client call it? Add `'use server'` and the file becomes an RPC action (browser import rewritten to a typed stub). Is it server-only infra instead (a DB driver, secrets, node:*)? Use NO directive, and NEVER import it into a page/layout/component. Reach it from a `'use server'` action, `route.ts`, or `middleware.ts`. A `.server.ts` WITHOUT the directive is a server-only utility whose browser import throws at module load.
-- **Label every interactive control.** Give each control an accessible name, and make clickable text a `<label for="control-id">` (or the control itself) so a text click activates the control on BOTH the JS path and the no-JS form-submit path. Use `aria-label` and `aria-pressed` on icon-only controls. `assertNoA11yViolations(el)` in a browser test catches missing labels.
-- Components must call customElements.define('tag', Class)
-- **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
-- Server-only code (the DB driver `pg`, 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. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra 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. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
-- Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported. For those, 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) OR from an `async render()` in the component itself (`const u = await getUser(this.uid)`, which SSR awaits so the data is in the first paint), NOT from `fetch` calls in `connectedCallback`. Prefer the co-located `async render()` over prop-drilling; `renderFallback()` is the optional re-fetch loading state (never first paint), and a `Task` is for genuinely client-only data. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
-- **Default to optimistic UI for feasible mutations.** Use `optimistic()` from `@webjsdev/core` for create/toggle/like/reorder so the UI updates instantly and rolls back on failure (no hand-written try-catch or temp-id bookkeeping). Do NOT use it where it hurts: unpredictable or server-computed results, side-effectful or OAuth/payment mutations, and destructive irreversible actions (confirm-first instead).
-- **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.
-- **Keep pages and layouts as pure carriers** so their modules stay out of the network tab. A page/layout never hydrates; the framework drops its module from the browser as long as its only browser job is registering the components it imports. It starts shipping its own module (invisible in tests, an elision verdict) the moment its closure does any OTHER client work. Don't give a page/layout module-scope client work (a top-level call, a window/document/customElements access, a bare side-effect import, or a @webjsdev/core/client-router import: routing is automatic) or import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in .server.{js,ts}. Self-check: page.ts/layout.ts should not appear in the browser's network tab.
-- See AGENTS.md for the complete directive decision guide
+# WebJs app rules (Cursor)
+
+Cursor reads `AGENTS.md` natively; this file points you at it and the agent
+skill, and carries the commit rule.
+
+- **Read `AGENTS.md` first, then `.agents/skills/webjs/SKILL.md`** (the guide to
+  building a WebJs app; it routes to focused references under
+  `.agents/skills/webjs/references/` that you load only when a task needs them).
+- **The scaffold ships a browsable feature gallery** (single-concept demos under
+  `app/features/` plus the `app/examples/todo` app, with logic in `modules/`).
+  It is reference to learn the idioms from, not part of your product.
+- **Building a real app? Learn from the gallery FIRST, then clear it, then
+  build.** Skim the demos relevant to your task for the runnable idiom (the skill
+  teaches the same and SURVIVES the clear, so you never lose it), then run
+  `npm run gallery:clear` to shed the gallery and reset the home, then grow the
+  app in place: add routes under `app/`, components under `components/`, features
+  under `modules/<feature>/`, and keep server-only code behind `.server.ts`.
+- **Use the wired-up database (Drizzle)** for persistence. Never a JSON file, an
+  in-memory array, or localStorage.
+- **Commit per logical unit** as soon as it is complete, and never commit to
+  `main`.

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

@@ -1,187 +1,9 @@
-# GitHub Copilot Instructions: webjs app
+# Copilot instructions
 
-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. When AGENTS.md doesn't cover what you need,
-the full hosted docs are at **https://docs.webjs.dev**.
+This is a thin bridge to the single source. GitHub Copilot always reads this
+file; in VS Code it reads `AGENTS.md` directly only when `chat.useAgentsMdFile`
+is enabled, so this bridge keeps Copilot pointed at the instructions regardless.
 
-## Persistence + scaffold rules (non-negotiable)
-
-- **Use Drizzle + SQLite for data, never JSON files.** It's already wired up
-  (`db/schema.server.ts`, `db/connection.server.ts`, `npm run db:generate` + `npm run db:migrate`). For ANY
-  data the app stores (todos, posts, messages, products, comments…),
-  define a Drizzle table. NEVER create `data/*.json`, `db.json`, or any
-  JSON file as a fake database. NEVER use module-scope arrays / Maps as
-  a substitute. NEVER use localStorage for app data. It resets on reload and cannot scale. This is a project convention
-  (CONVENTIONS.md).
-- **The scaffold is reference, not the final product.** Replace
-  `app/page.ts`, the example `User` model, the example users module, etc.
-  with the app the user actually asked for. Don't ship "Hello from
-  <app-name>" as the deliverable.
-- **Study the gallery first, prune it second.** The full-stack and saas scaffolds ship
-  single-feature demos under `app/features/` plus one whole example app under
-  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference:
-  read every demo end to end (code AND comments) to learn the idioms BEFORE you
-  write or delete anything. Only after internalising the patterns should you
-  prune, keeping and adapting what you need and deleting the rest (the
-  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
-  for the todo app, also the `todos` table). Never delete blindly up front. Each
-  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
-  until you resolve it. Delete now-empty directories after pruning. The `api`
-  template ships a BACKEND-features showcase instead (endpoints under
-  `app/api/features/`: the `route()` adapter + validation, rate limiting,
-  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
-  listed in the root `app/route.ts` index; prune it the same way.
-- **Prune what the app does not use.** Keep the infrastructure the app
-  USES and delete the rest (files AND folders). No persistence means
-  delete `db/`, `drizzle.config.ts`, and the `db:*` scripts. No UI kit
-  used means delete `components/ui/`, `components.json`, and
-  `lib/utils/cn.ts`. No PWA means delete `public/sw.js` and
-  `offline.html`. Always KEEP the durable knowledge (`AGENTS.md`,
-  `CONVENTIONS.md`, the rule files, the MCP), never prune it, so removing
-  example code never removes your context. Prune AFTER using the features
-  and examples as reference, never blindly up front. A no-op for the `api` template
-  (no UI kit, no PWA files).
-- **`app/` is routing-only.** Only routing files live in `app/` (page,
-  layout, route, middleware, metadata routes). CSS, helpers, and constants
-  do NOT: `globals.css` is at `styles/`, browser-safe helpers at
-  `lib/utils/`, feature logic in `modules/`.
-- **Use a unique design, and redesign means more than recolor (UI apps).** Give
-  the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
-  from what the app IS. `app/layout.ts` ships as a MINIMAL shell (theme, design
-  tokens, and Tailwind infra, then `${children}` in a bare padded container) with
-  NO header, nav, footer, or reading column: design the app's own chrome from
-  scratch. Decide whether it needs a header at all, a nav (or none), a footer, a
-  sidebar, a centered reading column, or a full-bleed canvas, from what fits the
-  app. `LAYOUT-REFERENCE.md` at the project root is a complete worked layout to
-  learn the patterns from, then build your own. Two `webjs-scaffold-placeholder`
-  markers gate `webjs check`: the minimal shell ("design your layout from
-  scratch") and the palette block ("own the colors"), so check fails until each
-  is addressed. Keep the design TOKENS and theme wiring in `app/layout.ts`
-  (infrastructure the ui kit reads) and set the token VALUES to your own palette;
-  run `webjs check --clear-placeholders` to keep the starter palette
-  deliberately. Style with Tailwind utilities wherever they reach, and use custom
-  CSS only for what utilities cannot express (@theme tokens, @keyframes,
-  scrollbar, complex color-mix or gradients). The `api` template has no UI, so
-  this does not apply there.
-- **Render the app and LOOK before you call UI work done (every agent, not just one harness).**
-  You write CSS blind, so a layout or design defect ships silently: `webjs check`
-  and `webjs typecheck` pass even when a component collapses, grid cells are
-  uneven, the layout resizes as it fills, or the app just kept the scaffold's
-  colors. Static tools give no failure signal for this. The only thing that
-  catches it is rendering the app and looking at the pixels. So for ANY page,
-  layout, or component work: run it (`webjs dev`), open every route you changed in
-  a real browser (drive it with your harness's browser tool or MCP if it has one,
-  otherwise open it yourself and screenshot), and PLAY THROUGH every state (empty,
-  filled, win, draw, reload, narrow and wide, light and dark). Confirm nothing
-  collapses or reflows, that cells stay equal, that the design is the app's OWN,
-  and that both themes read. Ship a real-browser test (`webjs test --browser`) for
-  the mechanical floor (measure `getBoundingClientRect()` and assert cells stay
-  equal across a move). Fix and re-render until it holds, then state in your final
-  message what you rendered and confirmed. Claude Code additionally ENFORCES this
-  via the `webjs-design-review` skill plus a Stop hook, but the discipline is
-  harness-agnostic and this rule is the source of truth for every agent.
-- **Only three templates exist:** `webjs create <name>` (default
-  full-stack), `--template api`, `--template saas`. The CLI rejects any
-  other `--template` value. Pick:
-  - Any product UI (todo, blog, dashboard, marketplace, social…) → default
-  - HTTP/JSON API only, no UI → `--template api`
-  - Auth / login / signup / SaaS → `--template saas`
-
-## Before starting ANY work
-
-FIRST, before writing any code:
-1. Check `git branch --show-current`.
-   - If on main/master: create a feature branch before editing.
-   - If on a feature branch: verify it matches the task at hand.
-2. Sync: `git fetch origin && git rebase origin/main` if behind.
-3. If more than one agent may work this repo at once, use a DEDICATED git
-   worktree per task (`git worktree add -b <branch> ../<repo>-<slug> origin/main`,
-   `cd` in, work there, `git worktree remove` after merge), never a shared
-   checkout. Two agents in one directory collide: a `git checkout` in one moves
-   HEAD under the other, so commits land on the wrong branch. A lone agent in a
-   clean checkout may use a plain branch.
-
-## 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.
-
-Quality bar stays the same, no blocking on questions.
-
-## Mandatory workflow (never skip)
-
-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 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 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
-
-## Framework rules
-
-- No build step: source files are served as ES modules. Don't introduce
-  build tools or bundlers in the critical path.
-- **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (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.
-- **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
-- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible) semantic tokens set to the brand palette. Use the canonical utility names everywhere, in the page chrome AND inside components: `bg-background`, `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`, `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`, `border-border`, `ring-ring`. These are exactly the tokens a component copied in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui component share one theme with no wiring. NEVER invent a parallel token vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it collides with the ui tokens (the accent once flipped to neutral on navigation for exactly this reason) and diverges from the shadcn conventions the kit and AI agents expect. Reach for opacity modifiers (`bg-primary/10`, `hover:bg-primary/90`) before adding a token; add one the canonical way (a `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
-- Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `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. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults in the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
-- Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
-- **Default to optimistic UI for feasible mutations.** Use `optimistic()` from `@webjsdev/core` for create/toggle/like/reorder so the UI updates instantly and rolls back on failure (no hand-written try-catch or temp-id bookkeeping). Do NOT use it where it hurts: unpredictable or server-computed results, side-effectful or OAuth/payment mutations, and destructive irreversible actions (confirm-first instead).
-- Server actions: *.server.ts files with one exported async function each.
-- **`.server.ts` vs `'use server'`, the decision.** Will the client call it? Add `'use server'` and the file becomes an RPC action (browser import rewritten to a typed stub). Is it server-only infra instead (a DB driver, secrets, node:*)? Use NO directive, and NEVER import it into a page/layout/component. Reach it from a `'use server'` action, route.ts, or middleware.ts. A `.server.ts` WITHOUT the directive is a server-only utility whose browser import throws at module load.
-- **Label every interactive control.** Give each control an accessible name, and make clickable text a `<label for="control-id">` (or the control itself) so a text click activates the control on BOTH the JS path and the no-JS form-submit path. Use `aria-label` and `aria-pressed` on icon-only controls. `assertNoA11yViolations(el)` in a browser test catches missing labels.
-- Server-only code (a DB driver like pg, 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. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file. A TYPE-ONLY `import type { Todo } from '#db/schema.server.ts'` is the exception, fine in a page or component because the stripper erases it before it reaches the browser.
-- Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported; use plain template-literal expressions 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).
-- Keep pages and layouts as pure carriers so their modules stay out of the network tab. A page/layout never hydrates; the framework drops its module from the browser as long as its only browser job is registering the components it imports. It starts shipping its own module (invisible in tests, an elision verdict) the moment its closure does any OTHER client work. Don't give a page/layout module-scope client work (a top-level call, a window/document/customElements access, a bare side-effect import, or a @webjsdev/core/client-router import: routing is automatic) or import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in .server.{js,ts}. Self-check: page.ts/layout.ts should not appear in the network tab.
-- 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 (declared via the `WebComponent({ ... })` factory) are for HTML attributes and .prop=${...} hydration.
-- Don't skip tests or documentation updates.
+The instructions for this app live in `AGENTS.md` (the cross-agent source) and
+the skill at `.agents/skills/webjs/SKILL.md`. Read `AGENTS.md` first, then the
+skill (it routes to focused references on demand).

package/templates/.github/pull_request_template.md

@@ -23,7 +23,7 @@ in [`CONVENTIONS.md`](../CONVENTIONS.md) for the full guidance.
 - [ ] **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`,
+      `CHANGELOG.md`, `docs/**/*.md`, `.agents/skills/webjs/**/*.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.