vite-flare-starter: Instructions file for Claude Code

Vite Flare Starter: AI developer context

Pattern library and production-ready starter kit for Cloudflare Workers (version in package.json). This file loads every session, so it holds the rules; docs/REFERENCE.md is the deep reference (module map, stack, UI kit, agents, AI, skills, auth, deploy) and its "Where to find things" table routes every other topic.

Pattern library, not a demo

• The modules are reference implementations: before building a feature in a fork, read the closest existing module (table "What each module demonstrates" in docs/REFERENCE.md).
• Don't delete modules you don't need: hide them with VITE_FEATURE_* flags in .dev.vars (src/shared/config/features.ts), so the code stays a readable reference.

Forking

• Fork, don't clone: a real GitHub fork keeps upstream wired, so git pull upstream main brings bug fixes and security patches; clone and rm -rf .git only when the user explicitly asks for a detached snapshot. Guides: FORKING.md, UPGRADING.md (releases), PATCHES.md (divergence).
• After forking: nav items in src/shared/config/nav.ts, unneeded modules off in src/shared/config/features.ts, rebrand in src/shared/config/app.ts, first module per docs/PATTERNS.md.
• Rebrand before production: VITE_APP_NAME, VITE_TOKEN_PREFIX + TOKEN_PREFIX, index.html title, favicon in public/; VITE_GITHUB_URL="" hides GitHub links.
• No product surface until DESIGN_BRIEF.md is filled from real material; with no material, design deliberately, never inherit the placeholder (FORKING.md Part 0).
• Friction the starter hasn't solved: issues and PRs upstream are welcome, shaped per CONTRIBUTING.md.

Building

• Navigation: edit src/shared/config/nav.ts, not the layout component; features.ts flags control visibility.
• Pages over modals: modals only for confirmations and quick decisions. A new page: module component, Route in src/client/App.tsx, nav item, feature flag if optional.
• Layouts: compose AppShell (src/components/ui/app-shell.tsx) differently; don't fork a whole layout file.
• List pages: pick the shape from what the user does, not what the data looks like (picker table and scaffolds in docs/REFERENCE.md). A new layout primitive needs 3+ surfaces or a firm plan for several, stays single-purpose, and gets a row in that table.
• Charts: Kumo ECharts with echarts and useChartTheme (canvas can't read CSS vars) from @/client/lib/echarts, imported inside route-lazy pages.
• Agents: use the Cloudflare agents SDK base; don't extend a raw DurableObject (decision table in docs/REFERENCE.md, detail in docs/AGENTS.md).
• "Watch X periodically and surface findings" is a Routine, not an AutonomousAgent subclass (docs/ROUTINES.md). Before designing a config DSL or rules engine, ask whether channels-as-tools plus a markdown skill covers it.
• Every primitive a user picks from a list (agent, tool, skill, channel) self-describes with displayName + description; render enum values through src/shared/format/agent.ts.
• Every multi-page feature passes the first-time-user test: sign in and complete the task without reading source. Anywhere you'd say "click Skip" is a UX bug.
• AI SDK stays on v6: the Cloudflare agents line pins ai ^6.
• Internal AI calls pick a model by role (resolveModelRole in server/lib/ai/roles.ts), not a hardcoded id, and pass thinkingOffProviderOptions(role) or thinkingOffRunOptions(role). Models live in src/shared/config/models.ts; Cloudflare retires Workers AI models without notice, so run pnpm doctor:models after any Workers AI release.
• Tenancy: use scopeUser(table.userId, userId) (src/server/lib/tenancy.ts) anywhere you'd write eq(table.userId, userId), in reads and write guards; it returns undefined in shared mode, so filter and(...) arrays with isCondition.