feat: ship an idiomatic feature gallery + example app in the scaffold

.agents/skills/webjs-doc-sync/SKILL.md

@@ -42,7 +42,7 @@ applies, then update or consciously skip each.
 2. **`README.md`** (repo root). Update when a headline capability changes (the
    feature list, the quickstart, the runtime/template matrix).
 3. **The docs site: `docs/app/docs/<topic>/page.tsx`.** This is the
-   user-facing documentation at docs.webjs.com. Find the topic page(s) that cover
+   user-facing documentation at docs.webjs.dev. Find the topic page(s) that cover
    the area (`server-actions`, `routing`, `components`, `caching`, `configuration`,
    `client-router`, `data-fetching`, ...) and update them. `llms.txt` /
    `llms-full.txt` are generated LIVE from the doc pages (no build step), so they

.claude/hooks/require-scaffold-with-src.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+#
+# PreToolUse hook: BLOCK a `git commit` that changes framework FEATURE
+# source but stages NO scaffold surface. The scaffold is webjs's PRIMARY
+# teaching surface for AI agents: an agent learns the framework by reading
+# the generated gallery/showcase and its comments, then builds the real app
+# by adapting them. So when a webjs FEATURE is added or changed, the scaffold
+# that teaches it must move too, exactly as the docs must (this is the
+# scaffold twin of require-docs-with-src.sh).
+#
+# It fires on every commit, decides from the STAGED diff (not model
+# judgement), and BLOCKS (exit 2) when framework-feature source is staged
+# with no scaffold surface in the same commit.
+#
+# What a hook CANNOT do: know WHETHER a given change actually needs a
+# scaffold demo (a bug fix, an internal perf change, or a tweak to an
+# already-demoed feature may not). So it enforces the floor (a
+# feature-source commit must stage SOME scaffold surface OR consciously opt
+# out) and points at the webjs-scaffold-sync skill for the per-surface walk
+# and the mandatory generate-boot-check.
+#
+# Scope: only fires on `git commit` Bash calls. Inspects the STAGED diff,
+# so `git add` choices drive it.
+#
+# Trigger (feature source that MAY need a scaffold update): the runtime +
+# CLI packages' src, packages/(core|server|cli)/src/**. Editor plugins, the
+# MCP, and intellisense do not shape the scaffold, so they are excluded.
+#
+# Satisfying surface: the scaffold itself, packages/cli/templates/** (the
+# template files + per-agent rule files) OR packages/cli/lib/** (the
+# create.js / saas-template.js / api-gallery.js generators).
+#
+# Allowed (exit 0): commits touching no feature src; commits that stage a
+# scaffold surface alongside the source; and a change that genuinely needs
+# no scaffold update (a bug fix, an internal refactor, a tweak to an
+# already-demoed feature) via WEBJS_NO_SCAFFOLD_GATE=1.
+#
+# Rule: AGENTS.md "Code workflow" (Scaffold) + the webjs-scaffold-sync skill.
+
+set -euo pipefail
+
+if [ "${WEBJS_NO_SCAFFOLD_GATE:-}" = "1" ]; then
+  exit 0
+fi
+
+payload=$(cat)
+cmd=$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+if [ -z "$cmd" ]; then exit 0; fi
+
+# Match `git commit` as a whole word (a real commit, not git commit-tree).
+if ! printf '%s' "$cmd" | grep -Eq '(^|[^[:alnum:]-])git commit([^[:alnum:]-]|$)'; then
+  exit 0
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then exit 0; fi
+
+staged=$(git diff --cached --name-only 2>/dev/null || true)
+if [ -z "$staged" ]; then exit 0; fi
+
+# Framework FEATURE source: the runtime + CLI packages' src. A change here is
+# the kind that MAY need the scaffold that teaches it to move too.
+src_touched=$(printf '%s\n' "$staged" | grep -E '^packages/(core|server|cli)/src/' || true)
+if [ -z "$src_touched" ]; then exit 0; fi
+
+# Any scaffold surface staged in the same commit? The scaffold is the
+# templates (files + per-agent rule files) and the generators (cli/lib).
+scaffold_staged=$(printf '%s\n' "$staged" | grep -E '^packages/cli/(templates|lib)/' || true)
+if [ -n "$scaffold_staged" ]; then exit 0; fi
+
+cat >&2 <<'EOF'
+BLOCKED: this commit changes framework-feature source but stages no scaffold.
+
+Staged source under packages/(core|server|cli)/src/** with no scaffold
+surface in the same commit. The scaffold is webjs's PRIMARY teaching surface
+for AI agents (they learn the framework by reading the generated
+gallery/showcase, then build the real app by adapting it), so a task is NOT
+done until the scaffold that teaches the changed feature is in sync too.
+
+If this added or changed a webjs FEATURE an agent should learn from the
+scaffold (a new export/API, an html hole, a lifecycle hook, a server-action
+capability, a config key, a CLI behaviour), invoke the webjs-scaffold-sync
+skill, then `git add` the scaffold surface(s) and commit again:
+  packages/cli/templates/gallery/         a UI feature-gallery demo (full-stack + saas)
+  packages/cli/lib/api-gallery.js         an api backend-showcase endpoint
+  packages/cli/lib/{create,saas-template}.js  the generators (home, theme, schema, wiring)
+  packages/cli/templates/ (AGENTS/CONVENTIONS/.cursorrules/...)  scaffold rules in lockstep
+  test/scaffolds/**                       the scaffold assertions for the above
+The skill walks every surface AND runs the mandatory generate + boot +
+`webjs check` verification (the generators emit strings, so escaping bugs
+only show in a freshly generated app).
+
+Change that genuinely needs no scaffold update (a bug fix, an internal
+refactor, a tweak to an already-demoed feature)? Re-run with
+WEBJS_NO_SCAFFOLD_GATE=1.
+
+Hook: .claude/hooks/require-scaffold-with-src.sh
+EOF
+exit 2

.claude/hooks/route-skills.sh

@@ -128,6 +128,25 @@ if has '(doc|documentation) (gap|drift|sync|coverage|debt)' \
   add_match "webjs-doc-sync: the request is about documentation sync, drift, or a doc gap. Invoke the webjs-doc-sync skill BEFORE editing any doc. It holds the authoritative map of EVERY surface (AGENTS.md + agent-docs/, README, the docs site under docs/app/docs/, the marketing website/, and the scaffold templates' per-agent rule files) and the change-type to surface mapping, so no surface is silently skipped. File each confirmed gap via webjs-file-issue."
 fi
 
+# --- webjs-scaffold-sync: keep every scaffold surface in sync -----------
+# Triggers: change what `webjs create` generates (a gallery/showcase demo, a
+# template, the generated layout/home/theme/schema), sync the scaffold,
+# "update all three templates", check the scaffold is consistent, teach
+# agents via the scaffold. The scaffold is webjs's PRIMARY teaching surface,
+# so a change must propagate across the generators (packages/cli/lib/*), the
+# per-agent rule files, the scaffold tests, the framework template-matrix
+# docs, and the preview apps, with a mandatory "generate + boot + check".
+if has '(sync|update|check|fix|add to).{0,24}(the )?(scaffold|template)' \
+   || has '(all (three|3) )?(scaffold )?templates?\b' \
+   || has 'gallery.{0,40}(template|saas|api|full-?stack|scaffold)' \
+   || has '(ship|include|add|put).{0,30}(the )?(gallery|showcase)' \
+   || has '(add|new|update).{0,24}(gallery|showcase)' \
+   || has '(scaffold|gallery) (consistent|in sync|drift|gap)' \
+   || has 'what `?webjs create`? generates' \
+   || has '(feature|backend) gallery'; then
+  add_match "webjs-scaffold-sync: the request changes what \`webjs create\` generates (a gallery/showcase demo, a template, a generated file, a scaffold convention). Invoke the webjs-scaffold-sync skill BEFORE editing. It holds the authoritative map of every scaffold surface (the packages/cli/lib/* generators, the templates/, the per-agent rule files in lockstep, the scaffold tests, the framework template-matrix docs, the preview apps) plus the mandatory generate-boot-check verification, so no surface is silently skipped. It is the scaffold-side sibling of webjs-doc-sync."
+fi
+
 # --- code-review: review the diff before a PR is ready ------------------
 # Triggers: review the PR/diff/branch/changes, code review, look it over
 # for bugs. Reviewing every change before it is marked ready is a standing

.claude/settings.json

@@ -40,6 +40,10 @@
             "type": "command",
             "command": ".claude/hooks/require-docs-with-src.sh"
           },
+          {
+            "type": "command",
+            "command": ".claude/hooks/require-scaffold-with-src.sh"
+          },
           {
             "type": "command",
             "command": ".claude/hooks/require-bun-parity-with-runtime-src.sh"

.claude/skills/webjs-doc-sync/SKILL.md

@@ -42,7 +42,7 @@ applies, then update or consciously skip each.
 2. **`README.md`** (repo root). Update when a headline capability changes (the
    feature list, the quickstart, the runtime/template matrix).
 3. **The docs site: `docs/app/docs/<topic>/page.tsx`.** This is the
-   user-facing documentation at docs.webjs.com. Find the topic page(s) that cover
+   user-facing documentation at docs.webjs.dev. Find the topic page(s) that cover
    the area (`server-actions`, `routing`, `components`, `caching`, `configuration`,
    `client-router`, `data-fetching`, ...) and update them. `llms.txt` /
    `llms-full.txt` are generated LIVE from the doc pages (no build step), so they
@@ -59,7 +59,13 @@ applies, then update or consciously skip each.
    `.gemini` / `.opencode` / `.claude` rule files. These per-agent files all carry
    the SAME rules in each agent's format; a workflow/convention change must land in
    ALL of them in lockstep (the #134 / #136 divergence lesson). The CLI help text
-   in `packages/cli/` is part of this surface for a new command or flag.
+   in `packages/cli/` is part of this surface for a new command or flag. When the
+   change is to what `webjs create` GENERATES (a gallery/showcase demo, a
+   template, the generated layout/home/theme/schema, a scaffold convention),
+   this surface has more parts (the `packages/cli/lib/*` generators, the scaffold
+   tests, the framework template-matrix docs, the preview apps) and a mandatory
+   "generate + boot + check" step: use the dedicated **`webjs-scaffold-sync`**
+   skill for those, and treat this doc-sync entry as the docs-only slice.
 6. **Example / dogfood apps** (`examples/blog/CONVENTIONS.md` and friends). Update
    when a convention the example demonstrates changes.