research: scaffold ships an always-on idiomatic multi-feature example gallery

[vivek7405]

Question

How should the scaffold give an AI agent context on EVERY webjs feature, without (a) bloating everything into one kitchen-sink page, or (b) relying only on prose docs the agent may not read?

Decision

The scaffold ships an always-on, idiomatic, multi-feature example GALLERY: one route per feature (/routing, /auth, /optimistic-ui, /streaming, /websockets, /file-storage, /caching, ...) plus a couple of composed app demos (/todo, /tic-tac-toe), with a landing/index page (app/page.ts) that links every example. It is structured EXACTLY per webjs conventions, so it teaches the architecture and the features at once. There is no --minimal / --no-examples opt-out: every scaffold always carries the gallery, so an agent always gains the context on how to use webjs.

Structure (idiomatic, NOT a single prune-folder)

• app/ = routing only: thin route pages (app/optimistic-ui/page.ts, app/todo/page.ts, ...) that import from their module.
• modules/<feature>/ = the real logic (components/, actions/, queries/, utils/, types.ts). /todo -> modules/todo/, /optimistic-ui -> modules/optimistic-ui/, etc.
• components/ = shared UI primitives used across examples.
• The routing surface is exercised idiomatically too: app/api/<x>/route.ts, middleware.ts, metadata routes (app/sitemap.ts ...), nested error.ts / loading.ts.
• db/ carries the example tables the data examples use.
• app/page.ts is the landing index (itself a commented page example) linking all example routes.

Prune model

NOT a one-folder delete. Pruning is the normal per-feature replace-the-example workflow (#818, which prunes files AND folders): the agent keeps the example routes/modules the real app needs and removes the rest, each marker-gated so webjs check prompts replacement. More prune surface than a single folder, accepted deliberately because it teaches the REAL structure. The examples double as CI-verified executable docs (they must pass webjs check + build), so they cannot silently rot.

Options compared

• A. Every feature as code in ONE kitchen-sink page. Rejected: coexistence conflicts (a folder cannot have both page.ts and route.ts), unreadable clutter, fights unique-design (Tell scaffold agents to use a unique design, not mimic the scaffold #815).
• B. Knowledge-only (docs / MCP) + a curated core example. Insufficient: an agent learns more from a working, browsable example than from prose, and does not always read the docs.
• C. Features on demand (webjs example add <feature>). Rejected: for an AI agent, "already there to browse" beats "run a command to fetch"; a shipped gallery is zero-friction context.
• D (chosen). Always-on idiomatic gallery in the scaffold. Modular (no coexistence conflicts), discoverable (index links all), self-contained learnable units, CI-verified, teaches the architecture by construction, less mimicry risk than a fake finished homepage (it is clearly labeled examples).

Key reversal

The first proposal was to isolate the whole gallery in ONE "delete-me" folder for easy pruning. REJECTED: that would teach a NON-idiomatic structure (everything under one folder), defeating the teaching purpose. The gallery must follow webjs conventions exactly (app-thin + modules-logic + components-shared), and pruning is per-feature (the normal #818 workflow), even though that is more prune surface.

Default-on with no opt-out (deliberate)

webjs is AI-first and the scaffold is the primary context vehicle, so the gallery is ALWAYS shipped with no --minimal escape hatch. The intent is that an agent can never skip gaining the context; the "cost" (a heavier starting app the agent prunes per-feature) is accepted as the price of guaranteed context.

Relationship to existing issues

• Make the scaffold the primary how-to-use-webjs context vehicle for AI agents #821 is the umbrella (scaffold as maximum-context vehicle); this gallery is its concrete architecture and implementation.
• dogfood: close first-pass friction found building a full-stack app #817 (seed a full-stack example module; empty-modules/ gap) is SUBSUMED: the gallery ships several real, idiomatic example modules, so the modules architecture is demonstrated, not just described. Its specific first-pass fixes (typed Metadata, Drizzle read pattern, MCP prompts) remain concrete sub-tasks of the gallery work.
• dogfood: scaffold guidance should prune unused files/folders, not keep everything #818 (prune) is the complementary per-feature prune workflow the gallery relies on.
• Tell scaffold agents to use a unique design, not mimic the scaffold #815 (unique design, do not mimic, merged) is respected: the gallery is clearly example content the agent replaces per-feature, not the final look.
• dogfood: make the .server.ts vs 'use server' distinction unmissable for agents #820 (.server.ts vs 'use server') and dogfood: split ui registry lib/utils.ts so importing cn() doesn't pin a page to the browser #819 (cn.ts) are demonstrated / respected by the gallery examples.
• Builds on research: keep three scaffolds and enrich, not consolidate to saas-as-default #822 (keep the three scaffolds and enrich each).

[vivek7405]

Deep-dive: why not the single delete-me folder

I initially pushed a single app/(examples)/ folder with one marker so the whole gallery deletes in one rm. Vivek correctly rejected it: a teaching scaffold that structures its examples non-idiomatically teaches the WRONG structure. The gallery must model app-thin + modules-logic + components-shared exactly, so the agent absorbs the architecture from the layout itself. The cost is per-feature pruning (more surface than one delete), which is the normal #818 replace-the-example workflow anyway. Delete-convenience lost to teaching-correctness, on purpose.