Coding Rules Overview

These rules apply to all code written in this repo. Read the relevant page before starting work in that area.

Authority order

The required flow is plan → document → code. Active plans lead while they are ahead of Fumadocs, but implementation should still pass through the documentation layer first: read the relevant /plans file, update Fumadocs to follow the settled plan, then update code. Once promoted, Fumadocs becomes the stable reference for implementation and review.

Small changes use the fast track and skip tasks and /plans when bun run verify:changed --list reports the cosmetic tier and they have no product, schema, workflow, API, persistence, routing, permission, or agent-behavior impact. If a small fix reveals a behavior decision, return to the normal pipeline.

Keep traceability one-way and lightweight. Active plans point forward to coarse target docs, docs record source-plan provenance in frontmatter, and code points to docs only where the reference materially helps maintain or review the implementation. Do not maintain many-to-many cross-reference lists by hand.

For Convex tables, use this order when sources diverge: active plan → schema docs → convex/schema.ts. Never infer intended schema fields from the codebase alone.

• Planning Workflow — required /plans → /docs → /src pipeline, plan metadata, requirement tracking, maintenance loop
• Repository Operations — commands, Git/worktree rules, verification gates, deployments, and local Convex recovery
• Cloudflare Staging — isolated Workers and Convex staging, runtime checks, credentials, and cost policy
• Code Vocabulary and Style Authorities — precedence, path-aware naming, guarantee-bearing role words, comments, reuse, and enforcement levels
• Codebase Versioning — directory-first versioning for APIs, modules, routes, and reusable logic
• File Size — line-count targets, the ≥500-line deepening trigger, tolerated outliers
• Convex — schema rules, function file conventions, internal function pattern, agent wiring
• UI Components — the FSD tree, the upstream landing zone, promotion workflow, import rules
• Storybook — the Proto / Spec / Live story lifecycle, how the gate reads it, assertion discipline
• The Stack — orientation for the furniture primitive the Folio family is drawn with; the annotated Stack stories are the authority
• Tailwind — class ordering, design tokens, shadow conventions, cn() and cva()