research: keep three scaffolds and enrich, not consolidate to saas-as-default

[vivek7405]

Question

To give AI agents maximum context on how to use webjs, should the scaffold consolidate from three templates (full-stack, api, saas) to two, making the richest (saas) the default renamed --full-stack and dropping the thin full-stack? Or keep three and enrich each?

Decision

Keep the three scaffolds (full-stack, api, saas) and enrich each. Do NOT make saas the default or fold it into full-stack. The default full-stack stays auth-free but becomes a rich teaching example (see #821); api stays the backend-only context; saas stays as the concrete, wired auth reference.

Options compared

A. saas-as-default (rename saas to --full-stack, drop the thin full-stack, keep --api). Two templates. The default carries the most patterns (auth, sessions, protected routes, User model). Rejected for four reasons:

1. Most apps are not SaaS (todo, blog, dashboard, landing, static hello-world), so auth-by-default gives all of them more to prune, and auth is the most opinionated, least-generic surface to prune. It worsens the leftover problem dogfood: scaffold guidance should prune unused files/folders, not keep everything #818 is meant to fix.
2. Semantic conflation: "full-stack" does not imply "has auth"; naming the auth template --full-stack mis-teaches that.
3. Auth is a FEATURE, not a core webjs idiom. Maximum "how to use webjs" context comes from the core surface (components, signals, optimistic(), the .server.ts boundary, actions/queries, modules, route.ts, PE forms), none of which need auth to teach.
4. The context lever is RICHNESS within a template, not the template COUNT.

B (chosen). Keep three, enrich each. The default full-stack becomes a rich, heavily-commented teaching example (#821) covering the core surface, auth-free. api stays the backend-only teaching context. saas stays as the concrete working auth reference. Optionally auth could later become an additive --auth flag, but that is not part of this decision.

The auth-context analysis (the crux)

The main objection to a no-auth default is "if the agent later needs auth, does it have enough context?" Verified empirically that auth context is DURABLE and independent of the saas scaffold's example code, so a no-auth default does NOT lose it:

• agent-docs/built-ins.md carries a full "## Authentication (NextAuth-style)" section (createAuth({ Credentials, Google, GitHub }), auth/signIn/signOut/handlers) plus a "## Sessions" section (session(), getSession(), SESSION_SECRET). The MCP serves these as resources + via the docs tool.
• The docs site has auth pages (/docs/authentication, /docs/auth).
• The framework source (@webjsdev/server/src/auth.js) is greppable.

So an agent that starts from full-stack and later needs auth reads it from the durable knowledge layer + MCP + source, regardless of scaffold. This is the same layered-context principle behind #818: knowledge is durable and always kept; scaffold example code is one reference among several.

Caveat accepted with eyes open: durable docs are SUFFICIENT, but a working wired example (what saas ships) reduces first-pass errors more than a prose snippet. So saas is kept as the concrete reference, and the durable auth context is strengthened (gaps below).

Auth-context gaps found (folded into #821)

• No dedicated auth recipe in agent-docs/recipes.md (only the built-ins.md reference section).
• No MCP add_auth guided prompt (there are add_page / add_server_action / add_module, but none for auth).
• Two docs-site auth pages (/docs/auth and /docs/authentication) worth reconciling to one.

These are folded into #821 (scaffold-as-context umbrella) rather than a new issue.

What shipped vs what was recommended

The initial user proposal was option A (saas-as-default). After the auth-context analysis, the decision landed on option B (keep three, enrich), which matches the recommendation: maximum context comes from richness (#821), not from making the default a SaaS app, and auth context is durable so a no-auth default is safe.

Cross-references

• Make the scaffold the primary how-to-use-webjs context vehicle for AI agents #821 scaffold-as-context umbrella (the enrichment work; auth gaps folded here).
• dogfood: close first-pass friction found building a full-stack app #817 full-stack example module + typed metadata + Drizzle read + MCP prompts (a slice of Make the scaffold the primary how-to-use-webjs context vehicle for AI agents #821).
• dogfood: make the .server.ts vs 'use server' distinction unmissable for agents #820 teach the .server.ts vs 'use server' distinction (a slice).
• dogfood: scaffold guidance should prune unused files/folders, not keep everything #818 prune unused files/folders (knowledge layer always kept).
• dogfood: split ui registry lib/utils.ts so importing cn() doesn't pin a page to the browser #819 clean/split the ui registry cn.ts.
• Tell scaffold agents to use a unique design, not mimic the scaffold #815 use a unique design, do not mimic the scaffold (merged; the constraint the teaching examples respect).