Keep every scaffold surface in sync with what webjs create generates

The scaffold is the primary way AI agents learn WebJs, through TWO teaching surfaces that must stay in sync with the framework:

1. The agent skill .agents/skills/webjs/ (SKILL.md + references/): the DURABLE teacher. It is the ONE canonical source (bundled into every scaffold at prepack via scripts/sync-scaffold-skill.mjs, and the repo's own agent guide). Crucially, gallery:clear strips the whole gallery to a blank slate, so the skill is the ONLY teaching surface that SURVIVES, and after a clear it is the agent's sole reference. A feature the skill does not teach is lost the moment an agent clears the gallery.
2. The gallery (the repo-root gallery/** app): runnable, densely commented demos an agent learns the idioms from by reading and running, then adapts. It is DISPOSABLE (removed by gallery:clear before real work begins). It lives ONCE, at the repo root, as a live workspace app you can boot and test (npm run dev:gallery, npm test --workspace=@webjsdev/gallery). packages/cli/prepack bundles it into packages/cli/templates/gallery/ for the tarball and postpack deletes that copy, so never edit or commit there.

So a change to a WebJs FEATURE usually needs BOTH: the skill updated (the durable pattern) AND a gallery demo (the runnable illustration). A change to what webjs create emits is a first-class change with MANY surfaces, and the recurring failure is updating one (usually a template file, or the gallery but not the skill) while the skill, the per-agent rule files, the scaffold tests, the framework docs, and the preview apps drift behind. This skill closes that gap.

It is the sibling of webjs-doc-sync. Division of labour:

• webjs-doc-sync owns the framework's API/behaviour docs (the root AGENTS.md API sections, agent-docs/*.md, docs-site topic pages, the marketing website).
• webjs-scaffold-sync (this skill) owns what the scaffold GENERATES and the surfaces that DESCRIBE the scaffold.

They overlap on two surfaces (the scaffold's per-agent rule files, and the template matrix in the framework docs/README). Whichever skill reaches that surface must update it; when in doubt run both.

Enforcement is TWO tiers, deliberately mirroring how tests are enforced (a commit-time floor plus an un-skippable CI gate):

• Tier 1, the commit floor. .claude/hooks/require-scaffold-with-src.sh BLOCKS a commit that stages framework-feature source (packages/(core|server|cli)/src) with no teaching surface in the same commit (escape hatch WEBJS_NO_SCAFFOLD_GATE=1). A teaching surface is EITHER the scaffold (packages/cli/templates or packages/cli/lib) OR the agent skill (.agents/skills/webjs/), since the skill is the durable half of the teaching pair. Like the test commit gate, it only proves you touched a teaching file; it cannot tell a real demo from a doc bullet, nor that you updated BOTH the gallery and the skill where both were needed, which is exactly how #848 slipped (forbidden()/unauthorized() staged doc bullets, shipped no gallery demo).
• Tier 2, the CI coverage gate. test/scaffolds/gallery-coverage.test.js reconciles the LIVE framework surface against the hand-curated test/scaffolds/gallery-coverage.json manifest and FAILS when a new surface is neither demoed nor exempted. It gates THREE surfaces: @webjsdev/core exports (a { demo } pointing at a gallery file that references it), @webjsdev/server exports ({ demoed: true }, verified by a generated app importing it), and routing convention files (the stems the router parses, DERIVED from packages/server/src/router.js so a new stem === '...' branch auto-appears, each demonstrated by a file in a generated app). Every entry is demo/demoed or { exempt } with a reason (internal: ... for plumbing, deferred: ... for an agent-facing surface not yet demoed). It runs on every npm test and in CI, so it cannot be skipped with a local --no-verify, the analogue of "a test must exist AND pass": a new export or convention turns CI red until it is classified. When you add or rename a core/server export, or add a routing convention file the router parses, update the manifest (a demo, or an honest exemption), the same reflex as writing a test.

THIS skill does the substantive per-surface judgment and the generate-boot-check verification that neither tier can automate.

The complete scaffold surface map

Treat this as the universe. For any scaffold change, decide per surface whether it applies, then update or consciously skip each.

1. The agent skill .agents/skills/webjs/ (the DURABLE teacher, canonical at the repo root, bundled into every scaffold at prepack). It is the surface most likely to be forgotten and the most important to keep current, because it is the ONLY teaching surface that survives gallery:clear. A new feature, export, idiom, or convention MUST be taught here so an agent building AFTER a clear still learns it:
   • .agents/skills/webjs/SKILL.md (the router: add the concept to the right "what this covers" line and route to the reference).
   • .agents/skills/webjs/references/*.md (the focused reference the feature belongs to, e.g. data-and-actions.md, client-router-and-streaming.md, components.md, styling.md, built-ins.md). Add the API + the idiom + the gotcha, matching the depth of the sibling entries.
   • Edit the repo-root copy; scripts/sync-scaffold-skill.mjs bundles it into templates/ at prepack (do NOT hand-edit a bundled copy).
2. The generators (the code that writes the app):
   • packages/cli/lib/create.js (the main generator: layout, home page, the theme block, db/schema, the full-stack gallery wiring, the per-template gates like isApi / isFullStack / !isApi).
   • packages/cli/lib/api-gallery.js (the api backend-features showcase). Auth is a full-stack GALLERY card now (gallery/{app/features/auth, modules/auth}), pruned by gallery:clear, not a separate template.
   • The gallery:clear reset scripts (BOTH templates, MANDATORY parity). packages/cli/templates/scripts/clear-gallery.mjs (full-stack) strips the app to a barebones blank slate (the gallery routes + modules, the example design system components/ui/, lib/utils/ui.ts, the example theme-toggle + its layout wiring, the example tests, empty leftover dirs), keeping only the buildable base + the skill. packages/cli/templates/scripts/clear-api-gallery.mjs (the api template) does the same for the backend showcase (app/api/features, the demo modules, env.ts, the widgets test), keeping the health + users base. RULE: any NEW gallery artifact (a route, a module, a shared component, a lib helper, a schema table) MUST be added to the matching clear script's removal list in the SAME change, or gallery:clear leaves it behind and the app is not a blank slate. This is enforced by test/scaffolds/scaffold-gallery.test.js (full-stack: asserts modules/ and components/ are EMPTY after clear, so a forgotten module/component fails) and the api clear test in the same file; run them after any gallery change.
   • Any future *-template.js / *-gallery.js split out for escaping sanity.
3. The verbatim template files copied into every app:
   • The repo-root gallery/** app (the UI feature gallery + example app). Its own shell (app/layout.ts, app/page.ts, components/theme-toggle.ts, lib/utils/cn.ts) is NOT payload: the generator writes those itself, so both the copy and the prepack bundle filter them via packages/cli/lib/gallery-shell-files.js. Add a file there if the gallery ever needs another app-only shell file.
   • packages/cli/templates/** (everything else copied per app: lib/utils/ui.ts, public/, tsconfig.json, gitignore, .hooks/, the metadata/route stubs).
4. The per-agent rule files (LOCKSTEP: all carry the SAME rules in each agent's format, the #134/#136 divergence lesson). A convention/workflow change for generated apps must land in ALL of them together:
   • packages/cli/templates/AGENTS.md
   • packages/cli/templates/CLAUDE.md
   • packages/cli/templates/CONVENTIONS.md
   • packages/cli/templates/.cursorrules
   • packages/cli/templates/.github/copilot-instructions.md
   • packages/cli/templates/.agents/rules/workflow.md
   • packages/cli/templates/.gemini/**, .opencode/**, .claude/** (whatever per-agent rule files the scaffold currently ships; enumerate, do not assume)
5. The scaffold tests: test/scaffolds/*.test.js (e.g. scaffold-gallery, scaffold-ui-integration). A new demo/template/generated-file assertion goes here, including the counterfactual (a per-template exclusion test).
6. The framework docs that DESCRIBE the scaffold (shared with doc-sync):
   • Root AGENTS.md "Scaffolding" section.
   • The docs site: website/app/(site)/docs/getting-started/page.ts (+ backend-only, ai-first, conventions where they describe generated structure).
   • README.md (the template matrix + the "scaffold is the tutorial" note).
7. The CLI surface: packages/cli/ --template validation + --help/usage text when a template or flag is added or renamed.
8. The preview / example / dogfood apps: examples/blog/ and any in-repo apps, plus the local preview apps the user tests, when a convention they demonstrate changes.

Change-type to surface mapping

Per-change sync procedure

Run the mandatory generate + boot + check verifications in PARALLEL when more than one template is affected: each verification is its own background Bash task, launched in one batch, with EVERY task's result collected before the sync is declared done (a forgotten background boot is a silently unverified template). Prefer the in-process harness (createRequestHandler + Request objects, the dogfood boot-check pattern in the start-work skill): it binds no port, so parallel runs cannot collide. When a real webjs dev listen is unavoidable, give each boot a distinct --port.

1. Identify the change's IDENTIFYING TOKENS: the demo route (app/features/<x>, app/api/features/<x>), the template name, the generated file path, the convention phrase, or the scoping phrase (e.g. "full-stack only").
2. Grep those tokens across every scaffold surface:

   git grep -n -iE '<token1>|<token2>' -- \
     'packages/cli/lib/**' 'packages/cli/templates/**' 'test/scaffolds/**' \
     AGENTS.md README.md 'website/app/(site)/docs/**'

3. Update every surface the mapping says applies. For a SCOPING or wording change (e.g. "gallery is full-stack only" becoming "full-stack and saas"), the grep MUST surface and fix every copy, in the rule files AND the framework docs.
4. VERIFY BY GENERATING (mandatory, non-negotiable). The generators emit strings, so a template-literal / escaping / interpolation bug is invisible in the generator's own syntax and only appears in the GENERATED app. For each affected template, generate an app and prove it:

   # generate (files only is enough for structure/typecheck; install to boot)
   node -e "import('packages/cli/lib/create.js').then(m => m.scaffoldApp('probe', '/tmp/x', { template: 'full-stack', install: false }))"
   # then in the generated app: webjs check (clean), webjs typecheck (clean),
   # and boot it to hit the new route(s).

   A scaffold change is NOT done until a freshly generated app of each affected template BOOTS, serves the new/changed route, passes webjs check, and webjs typecheck is clean.
5. Run the scaffold tests (node --test 'test/scaffolds/*.test.js') and add/adjust assertions (a new demo in the FEATURES list, a per-template inclusion/exclusion test, the counterfactual).
6. Respect the prose-punctuation invariant (#11) in every comment and doc, and keep each demo densely commented (a header stating the webjs concept + the why, and inline comments on the non-obvious idiom). Add a prune note where removal is NOT obvious, which is what the demos that carry one do: a card spanning several paths (the auth card names its route, its module, its api routes and its schema column), or one that depends on another (the server-actions card says to prune it with auth). A self-contained demo needs none, since npm run gallery:clear sheds the lot. The scaffold teaches by its comments, and a thin demo is a bug.

Audit-mode procedure (sweep the scaffold for drift)

Fan the sweep out like the doc-sync audit: one read-only Explore agent per surface of the map, spawned in one message; the agents report and the edits stay in the main session.

1. List the shipped scaffold changes (new demos, new template, scoping changes, changed generated files).
2. For each, pull its tokens and run the surface grep above.
3. A surface is a GAP when the mapping says it applies but the token is absent or describes stale behaviour there (a classic gap: a demo added to the full-stack home but missing from the saas home, or a scoping phrase updated in one rule file but not the other five).
   • Skill-vs-gallery coverage sweep (the highest-value audit now that gallery:clear strips the gallery): for EACH gallery demo (app/features/<x> + its modules/<x>), confirm the concept it teaches is also taught in .agents/skills/webjs/references/*.md. A concept the gallery demonstrates but the skill omits is a GAP, because it vanishes at gallery:clear and the agent building the real app never sees it. Fill it in the matching reference at the depth of its siblings.
4. For a bulk audit, file a grounded follow-up via webjs-file-issue per gap (title scaffold: <surface> missing <thing>); for a single in-flight change, just fix all surfaces on the same PR.

What this skill does NOT do

• It does not regenerate llms.txt / llms-full.txt (live-generated) or the website changelog (auto from PR titles).
• It does not own framework API/behaviour docs (that is webjs-doc-sync); when a change touches both a framework API and the scaffold, run both skills.
• It does not decide whether a CLI change alters generated output; that judgement is step 1, and a pure-internal refactor correctly updates no scaffold surface.