Problem
The scaffold's per-agent rule files tell the building AI agent to REPLACE the example content ("the scaffold is reference, not the final product"), but they never tell it to use a DISTINCT visual design. So agents frequently ship an app that still looks like the scaffold (its warm-orange palette, the 760px reading column, the serif display, the example chrome), just with different copy. Platforms embedding webjs (e.g. crisp) had to bolt this instruction onto their own build prompt; it should live in the scaffold so EVERY agent on EVERY platform (Claude, Cursor, Copilot, Gemini, OpenCode, Aider) gets it for free.
Design / approach
Add a short "use a unique design, do not mimic the scaffold's example look" guideline alongside the existing "scaffold is reference" guidance, in every per-agent rule surface, in lockstep. Scope it to UI so it is a natural no-op for the api template (no UI): "when the app has a UI, use a design of your own (palette, layout, type, chrome), not the scaffold's example look." Keep the design TOKENS / theme infrastructure (that is not the example look, it is wiring).
Implementation notes (for the implementing agent)
The 3 templates (full-stack / api / saas) SHARE one set of agent-rule files copied for all of them by packages/cli/lib/create.js (see templateFiles ~L457 and the command-rewrite list ~L521), so editing the shared files covers all three. The prose lives in FIVE files under packages/cli/templates/ (edit all in lockstep; CLAUDE.md just @-includes AGENTS.md + CONVENTIONS.md, and .gemini / .opencode / .claude are hooks, not prose):
AGENTS.md around L20-30 (the scaffold-reference + layout-width paragraph).
CONVENTIONS.md ## The scaffold is reference, not the final product (L308), specifically item 5 about adapting app/layout.ts / add a new item.
.cursorrules, .github/copilot-instructions.md, .agents/rules/workflow.md: each has a - **The scaffold is reference, not the final product.** bullet (~L17-21) to extend.
Landmines:
- The scaffold
AGENTS.md / CONVENTIONS.md are DISTINCT from the framework-root ones; edit the packages/cli/templates/ copies.
- Invariant 11 (prose punctuation, no em-dash / space-hyphen / space-semicolon pause) applies to these files.
- Keep the wording UI-scoped so
api apps are unaffected.
Tests + docs: packages/cli/test/ scaffold tests + test/scaffolds/*; run test/docs/doc-source-consistency.test.mjs if it covers scaffold agent files. No docs-site API change (this is scaffold-authoring guidance). Also mirror into the docs-site scaffold/getting-started page only if it restates these rules.
Acceptance criteria
Problem
The scaffold's per-agent rule files tell the building AI agent to REPLACE the example content ("the scaffold is reference, not the final product"), but they never tell it to use a DISTINCT visual design. So agents frequently ship an app that still looks like the scaffold (its warm-orange palette, the 760px reading column, the serif display, the example chrome), just with different copy. Platforms embedding webjs (e.g. crisp) had to bolt this instruction onto their own build prompt; it should live in the scaffold so EVERY agent on EVERY platform (Claude, Cursor, Copilot, Gemini, OpenCode, Aider) gets it for free.
Design / approach
Add a short "use a unique design, do not mimic the scaffold's example look" guideline alongside the existing "scaffold is reference" guidance, in every per-agent rule surface, in lockstep. Scope it to UI so it is a natural no-op for the
apitemplate (no UI): "when the app has a UI, use a design of your own (palette, layout, type, chrome), not the scaffold's example look." Keep the design TOKENS / theme infrastructure (that is not the example look, it is wiring).Implementation notes (for the implementing agent)
The 3 templates (full-stack / api / saas) SHARE one set of agent-rule files copied for all of them by
packages/cli/lib/create.js(seetemplateFiles~L457 and the command-rewrite list ~L521), so editing the shared files covers all three. The prose lives in FIVE files underpackages/cli/templates/(edit all in lockstep;CLAUDE.mdjust@-includes AGENTS.md + CONVENTIONS.md, and.gemini/.opencode/.claudeare hooks, not prose):AGENTS.mdaround L20-30 (the scaffold-reference + layout-width paragraph).CONVENTIONS.md## The scaffold is reference, not the final product(L308), specifically item 5 about adaptingapp/layout.ts/ add a new item..cursorrules,.github/copilot-instructions.md,.agents/rules/workflow.md: each has a- **The scaffold is reference, not the final product.**bullet (~L17-21) to extend.Landmines:
AGENTS.md/CONVENTIONS.mdare DISTINCT from the framework-root ones; edit thepackages/cli/templates/copies.apiapps are unaffected.Tests + docs:
packages/cli/test/scaffold tests +test/scaffolds/*; runtest/docs/doc-source-consistency.test.mjsif it covers scaffold agent files. No docs-site API change (this is scaffold-authoring guidance). Also mirror into the docs-site scaffold/getting-started page only if it restates these rules.Acceptance criteria
apiis unaffected.webjs check(guideline is prose, not an enforced marker).