@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/core/design-system-tokens.md

@@ -0,0 +1,469 @@
+---
+name: design-system-tokens
+description: Design token definitions, base component visual specs, dark mode patterns, and pattern library for building consistent UIs
+topics: [design-system, tokens, colors, typography, spacing, components, dark-mode, pattern-library]
+---
+
+## Summary
+
+## Design Tokens
+
+Design tokens are the atomic values that define the visual language. They are variables, not hard-coded values. Every visual property in the application references a token.
+
+### Color Tokens
+
+**Brand colors:**
+
+```
+--color-primary: #2563EB          // Main brand/action color
+--color-primary-hover: #1D4ED8    // Interactive state
+--color-primary-active: #1E40AF   // Pressed/active state
+--color-primary-light: #DBEAFE    // Backgrounds, subtle highlights
+--color-primary-lighter: #EFF6FF  // Very subtle tints
+
+--color-secondary: #7C3AED        // Supporting brand color
+--color-secondary-hover: #6D28D9  // Interactive state
+--color-secondary-light: #EDE9FE  // Backgrounds
+```
+
+**Neutral scale:**
+
+```
+--color-neutral-50: #FAFAFA       // Lightest background
+--color-neutral-100: #F5F5F5      // Card backgrounds, zebra stripes
+--color-neutral-200: #E5E5E5      // Borders, dividers
+--color-neutral-300: #D4D4D4      // Disabled borders
+--color-neutral-400: #A3A3A3      // Muted text, placeholders, disabled text
+--color-neutral-500: #737373      // Secondary icons
+--color-neutral-600: #525252      // Tertiary text
+--color-neutral-700: #404040      // Secondary text
+--color-neutral-800: #262626      // Dark backgrounds (dark mode cards)
+--color-neutral-900: #171717      // Primary text, dark mode page background
+```
+
+**Semantic colors:**
+
+```
+--color-success: #16A34A          // Success states, positive actions
+--color-success-light: #DCFCE7    // Success backgrounds
+--color-success-dark: #15803D     // Success text on light backgrounds
+
+--color-warning: #CA8A04          // Warning states, caution
+--color-warning-light: #FEF9C3    // Warning backgrounds
+--color-warning-dark: #A16207     // Warning text on light backgrounds
+
+--color-error: #DC2626            // Error states, destructive actions
+--color-error-light: #FEE2E2      // Error backgrounds
+--color-error-dark: #B91C1C       // Error text on light backgrounds
+
+--color-info: #2563EB             // Informational states
+--color-info-light: #DBEAFE       // Info backgrounds
+```
+
+**Surface and overlay:**
+
+```
+--color-surface: #FFFFFF          // Card/panel surfaces
+--color-overlay: rgba(0,0,0,0.5)  // Modal/dialog backdrop
+--color-focus-ring: rgba(37,99,235,0.5)  // Focus indicator
+```
+
+## Deep Guidance
+
+### Typography Tokens
+
+**Font families:**
+
+```
+--font-family: 'Inter', system-ui, -apple-system, sans-serif
+--font-family-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace
+```
+
+**Font sizes (modular scale):**
+
+```
+--text-xs: 0.75rem    // 12px — fine print, labels, badges
+--text-sm: 0.875rem   // 14px — secondary text, table cells, help text
+--text-base: 1rem     // 16px — body text (default)
+--text-lg: 1.125rem   // 18px — subheadings, emphasis
+--text-xl: 1.25rem    // 20px — section titles
+--text-2xl: 1.5rem    // 24px — page titles
+--text-3xl: 1.875rem  // 30px — hero text, major headings
+--text-4xl: 2.25rem   // 36px — display headings (marketing, landing)
+```
+
+**Font weights:**
+
+```
+--font-weight-normal: 400    // Body text
+--font-weight-medium: 500    // Buttons, labels, navigation
+--font-weight-semibold: 600  // Subheadings, emphasis
+--font-weight-bold: 700      // Headings, strong emphasis
+```
+
+**Line heights:**
+
+```
+--line-height-tight: 1.25    // Headings, single-line labels
+--line-height-normal: 1.5    // Body text (default)
+--line-height-relaxed: 1.75  // Long-form content, help text
+```
+
+**Letter spacing:**
+
+```
+--tracking-tight: -0.025em   // Large headings
+--tracking-normal: 0         // Body text
+--tracking-wide: 0.025em     // Uppercase labels, small caps
+```
+
+### Spacing Tokens
+
+Based on a 4px base unit. Every spacing value in the application uses one of these tokens -- no arbitrary pixel values.
+
+```
+--space-0: 0           // 0px  — no spacing
+--space-0.5: 0.125rem  // 2px  — hairline gaps
+--space-1: 0.25rem     // 4px  — tight gaps (icon to label)
+--space-1.5: 0.375rem  // 6px  — compact inline spacing
+--space-2: 0.5rem      // 8px  — compact spacing (list items, badge padding)
+--space-3: 0.75rem     // 12px — default padding (buttons, inputs)
+--space-4: 1rem        // 16px — standard spacing (form fields, card padding)
+--space-5: 1.25rem     // 20px — medium gaps
+--space-6: 1.5rem      // 24px — section padding
+--space-8: 2rem        // 32px — large gaps (section spacing)
+--space-10: 2.5rem     // 40px — major section gaps
+--space-12: 3rem       // 48px — section separators
+--space-16: 4rem       // 64px — page-level spacing
+--space-20: 5rem       // 80px — hero section padding
+--space-24: 6rem       // 96px — page-level vertical rhythm
+```
+
+### Border and Shadow Tokens
+
+**Border radii:**
+
+```
+--radius-none: 0         // Sharp corners
+--radius-sm: 0.25rem     // 4px  — subtle rounding (tags, badges)
+--radius-md: 0.5rem      // 8px  — standard rounding (cards, inputs, buttons)
+--radius-lg: 0.75rem     // 12px — prominent rounding (modals, panels)
+--radius-xl: 1rem        // 16px — large containers, hero cards
+--radius-full: 9999px    // Pill shapes, avatars, toggles
+```
+
+**Elevation (box shadows):**
+
+```
+--shadow-sm: 0 1px 2px rgba(0,0,0,0.05)                          // Subtle lift (buttons, badges)
+--shadow-md: 0 4px 6px -1px rgba(0,0,0,0.07), 0 2px 4px -2px rgba(0,0,0,0.05)   // Cards, dropdowns
+--shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.05)   // Popovers, floating elements
+--shadow-xl: 0 20px 25px -5px rgba(0,0,0,0.1), 0 8px 10px -6px rgba(0,0,0,0.04)  // Modals, dialogs
+--shadow-inner: inset 0 2px 4px rgba(0,0,0,0.05)                 // Pressed states, input wells
+```
+
+**Border widths:**
+
+```
+--border-width-thin: 1px     // Default borders (inputs, cards, dividers)
+--border-width-medium: 2px   // Focus rings, active tab indicators
+--border-width-thick: 4px    // Left-border accents on alerts
+```
+
+### Transition Tokens
+
+```
+--transition-fast: 150ms ease      // Hover states, color changes
+--transition-base: 200ms ease      // Most interactions
+--transition-slow: 300ms ease      // Layout shifts, modals appearing
+--transition-spring: 300ms cubic-bezier(0.34, 1.56, 0.64, 1)  // Playful bounces (optional)
+```
+
+## Dark Mode
+
+When dark mode is required, define a parallel set of semantic tokens that switch based on the color scheme. Components reference semantic tokens, never raw color tokens directly.
+
+### Semantic Token Mapping
+
+```css
+:root {
+  /* Surfaces */
+  --bg-primary: var(--color-neutral-50);
+  --bg-secondary: var(--color-neutral-100);
+  --bg-card: white;
+  --bg-input: white;
+  --bg-overlay: rgba(0, 0, 0, 0.5);
+
+  /* Text */
+  --text-primary: var(--color-neutral-900);
+  --text-secondary: var(--color-neutral-700);
+  --text-muted: var(--color-neutral-400);
+  --text-inverse: white;
+
+  /* Borders */
+  --border-default: var(--color-neutral-200);
+  --border-strong: var(--color-neutral-300);
+  --border-focus: var(--color-primary);
+
+  /* Shadows */
+  --shadow-color: rgba(0, 0, 0, 0.1);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    /* Surfaces */
+    --bg-primary: var(--color-neutral-900);
+    --bg-secondary: #1a1a1a;
+    --bg-card: var(--color-neutral-800);
+    --bg-input: var(--color-neutral-800);
+    --bg-overlay: rgba(0, 0, 0, 0.7);
+
+    /* Text */
+    --text-primary: var(--color-neutral-50);
+    --text-secondary: var(--color-neutral-400);
+    --text-muted: var(--color-neutral-500);
+    --text-inverse: var(--color-neutral-900);
+
+    /* Borders */
+    --border-default: var(--color-neutral-700);
+    --border-strong: var(--color-neutral-600);
+    --border-focus: #60A5FA;
+
+    /* Shadows — reduced in dark mode, use border emphasis instead */
+    --shadow-color: rgba(0, 0, 0, 0.3);
+  }
+}
+```
+
+### Dark Mode Implementation Rules
+
+- **Always use semantic tokens** (`--bg-primary`, `--text-primary`) in components, never raw color tokens (`--color-neutral-900`). This makes dark mode automatic.
+- **Test both modes**: Every visual change must be verified in both light and dark mode.
+- **Avoid pure black backgrounds**: Use `--color-neutral-900` (#171717) instead of `#000000` -- pure black creates harsh contrast and eye strain.
+- **Reduce shadow prominence in dark mode**: Shadows are less visible on dark backgrounds. Use border emphasis or subtle glow effects instead.
+- **Adjust semantic color intensity**: Success, warning, and error colors may need lighter variants in dark mode for readability on dark surfaces.
+- **Images and illustrations**: Consider providing dark-mode-optimized versions or applying CSS filters (e.g., `brightness(0.9)`) to prevent overly bright images on dark backgrounds.
+
+## Responsive Breakpoints
+
+Define breakpoints as min-width values for mobile-first responsive design:
+
+```
+--breakpoint-sm: 640px     // Small devices (landscape phones)
+--breakpoint-md: 768px     // Tablets
+--breakpoint-lg: 1024px    // Laptops, small desktops
+--breakpoint-xl: 1280px    // Large desktops
+--breakpoint-2xl: 1536px   // Extra-large screens
+```
+
+### Breakpoint Usage
+
+```css
+/* Mobile-first: base styles apply to all sizes */
+.container { padding: var(--space-4); }
+
+/* Tablet and up */
+@media (min-width: 768px) {
+  .container { padding: var(--space-6); max-width: 768px; }
+}
+
+/* Desktop and up */
+@media (min-width: 1024px) {
+  .container { padding: var(--space-8); max-width: 1024px; }
+}
+
+/* Large desktop */
+@media (min-width: 1280px) {
+  .container { max-width: 1200px; }
+}
+```
+
+### Responsive Patterns
+
+- **Stack to grid**: Single-column on mobile, multi-column on desktop
+- **Navigation collapse**: Full nav on desktop, hamburger menu below `--breakpoint-md`
+- **Table adaptation**: Full table on desktop, card layout below `--breakpoint-md`
+- **Touch targets**: Minimum 44x44px on touch devices (below `--breakpoint-lg`)
+- **Font scaling**: Base size stays at 16px; heading sizes may reduce on mobile
+
+## Accessibility Requirements
+
+### Color Contrast
+
+All text must meet WCAG 2.1 AA contrast requirements:
+- **Normal text (< 18px)**: minimum 4.5:1 contrast ratio against background
+- **Large text (>= 18px bold or >= 24px)**: minimum 3:1 contrast ratio
+- **UI components and graphical objects**: minimum 3:1 against adjacent colors
+- **Focus indicators**: must have 3:1 contrast against both the component and the background
+
+### Focus Indicators
+
+Every interactive element must have a visible focus indicator:
+
+```css
+:focus-visible {
+  outline: var(--border-width-medium) solid var(--border-focus);
+  outline-offset: 2px;
+}
+```
+
+- Do not remove focus outlines (`outline: none`) without providing an alternative
+- Use `:focus-visible` (not `:focus`) to show focus rings only for keyboard navigation
+- Focus ring must be visible in both light and dark mode
+
+### Touch Targets
+
+- Minimum interactive element size: 44x44 CSS pixels (WCAG 2.5.5 Target Size)
+- Minimum spacing between adjacent touch targets: 8px
+- Clickable area may be larger than the visual element (use padding, not just visual size)
+
+### Motion and Animation
+
+- Respect `prefers-reduced-motion`: disable non-essential animations
+- Essential animations (loading spinners) should still play but with reduced motion
+- Auto-playing animations should have a pause mechanism
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Base Components
+
+Define the standard appearance and behavior for every common component:
+
+### Buttons
+
+**Variants:**
+- **Primary**: Solid fill (`--color-primary` background, white text). Main call-to-action.
+- **Secondary**: Subtle fill (`--color-neutral-100` background, `--text-primary` text). Secondary actions.
+- **Outline**: Border only (`--border-default` border, `--text-primary` text). Tertiary actions.
+- **Ghost**: No background or border. Minimal visual weight. Navigation, icon-only actions.
+- **Destructive**: Red/danger (`--color-error` background, white text). Delete, remove, cancel actions.
+
+**Sizes:**
+- **sm**: 28px height, `--text-xs`, `--space-2` horizontal padding
+- **md**: 36px height, `--text-sm`, `--space-3` horizontal padding (default)
+- **lg**: 44px height, `--text-base`, `--space-4` horizontal padding
+
+**States:**
+- **Default**: Normal appearance
+- **Hover**: Darker background (e.g., `--color-primary-hover`), cursor pointer
+- **Active**: Even darker background (`--color-primary-active`), slight scale-down
+- **Focused**: Focus ring visible (`--border-focus` outline)
+- **Disabled**: Reduced opacity (0.5), no hover effects, `cursor: not-allowed`
+- **Loading**: Label replaced with spinner, interaction disabled, maintains button width
+
+### Form Elements
+
+**Text inputs and textareas:**
+- Border: `--border-default`, `--radius-md`
+- Focus: `--border-focus` with focus ring
+- Error: `--color-error` border + error message below in `--color-error`
+- Disabled: `--color-neutral-100` background, reduced opacity
+- Height: 36px for inputs (matches button md)
+
+**Labels:**
+- Always visible (never use placeholder as the only label)
+- Required indicator: asterisk or "(required)" text
+- Associated with input via `for`/`id` or wrapping
+
+**Help text:**
+- Below input, `--text-xs`, `--text-muted` color
+- Explains format expectations (e.g., "Must be at least 8 characters")
+
+**Error messages:**
+- Below input, `--text-xs`, `--color-error`
+- Describes what went wrong and how to fix it (not just "Invalid")
+- Replaces help text when error is active
+
+**Select inputs and dropdowns:**
+- Same dimensions and borders as text inputs
+- Chevron indicator aligned right
+- Option list uses `--shadow-lg` elevation
+
+**Checkboxes and radio buttons:**
+- Minimum 20x20px visual size, 44x44px touch target
+- Checked state uses `--color-primary`
+- Labels always to the right, clickable
+
+### Cards
+
+- Background: `--bg-card`
+- Border: `--border-default` or `--shadow-sm`
+- Padding: `--space-4` to `--space-6`
+- Border radius: `--radius-md`
+- **Interactive cards**: hover state increases shadow (`--shadow-md`), cursor pointer
+- **Header/footer sections**: separated by `--border-default` divider, visually distinct padding
+
+### Feedback Components
+
+**Toast notifications:**
+- Temporary, non-blocking, positioned top-right or bottom-center
+- Auto-dismiss after 5 seconds with manual dismiss (X button)
+- Variants: success (green), error (red), warning (yellow), info (blue)
+- Includes icon + message + optional action link
+
+**Alert banners:**
+- Persistent until explicitly dismissed
+- Full-width or contained within a section
+- Left border accent (`--border-width-thick`) with semantic color
+- Variants: info, warning, error, success
+
+**Empty states:**
+- Centered illustration or icon
+- Explanatory heading and description text
+- Call-to-action button ("Create your first [item]")
+- Uses `--text-muted` for description
+
+**Loading states:**
+- **Skeleton loaders** (preferred for content areas): animated placeholder shapes matching content layout
+- **Spinners** (for actions): 20px for inline, 32px for section, 48px for page-level
+- **Progress bars** (for known-duration operations): determinate with percentage
+
+### Navigation
+
+- **Header/navbar**: fixed or sticky, `--shadow-sm` or border-bottom, contains logo + primary nav + user menu
+- **Sidebar**: collapsible on desktop, overlay on mobile, active item highlighted with `--color-primary-light` background
+- **Breadcrumbs**: `--text-sm`, separator chevrons, current page not linked
+- **Tabs**: underline style (active tab has `--color-primary` bottom border, `--border-width-medium`), equal or auto width
+- **Pagination**: prev/next buttons + page numbers, disabled state for first/last, compact mode on mobile (prev/next only)
+
+### Data Display
+
+- **Tables**: header row with `--bg-secondary` background, row hover state, sortable column headers with indicator icon, responsive (horizontal scroll or card layout on mobile)
+- **Lists**: consistent item height and spacing (`--space-2` to `--space-3` between items), interactive items have hover state
+- **Badges/tags**: `--radius-full`, `--text-xs`, `--space-1` vertical / `--space-2` horizontal padding, semantic color variants
+- **Avatars**: `--radius-full`, sizes 24/32/40px, fallback shows initials on `--color-primary-light` background
+- **Stats/metrics**: large value (`--text-2xl`, `--font-weight-bold`), label below (`--text-sm`, `--text-secondary`), optional trend indicator (up/down arrow with green/red)
+
+## Pattern Library
+
+Document recurring UI patterns with implementation guidance:
+
+- **Search with autocomplete**: Debounced input (300ms), dropdown results panel with `--shadow-lg`, keyboard navigation (arrow keys + Enter), "no results" state with suggestion, clear button (X) when input has value
+- **Confirmation dialogs**: Modal with overlay, clearly states what will happen ("Delete 3 items? This cannot be undone."), "Cancel" as default/primary action (preventing accidents), destructive action in `--color-error`
+- **Inline editing**: Click to edit transforms display text into input, Enter to save, Escape to cancel, loading indicator during save, validation feedback
+- **Bulk actions**: Checkbox selection, "Select all" header checkbox, floating action toolbar appears when items selected, count indicator ("3 selected")
+- **Wizard/stepper**: Numbered step indicator, completed steps show checkmark, back/next navigation, save progress between steps, summary step before final submit
+- **Infinite scroll vs. pagination**: Use pagination for data tables and search results (users need to reference positions). Use infinite scroll for feeds and timelines (users scan sequentially).
+
+## Common Pitfalls
+
+**Inconsistent spacing and typography.** Five different font sizes that are all "kind of like body text." Spacing that varies randomly between 12px and 17px with no system. Fix: define a spacing scale and type scale in the design system. Only use values from the scale.
+
+**Hard-coded color values in components.** Using `#2563EB` directly in a component instead of `var(--color-primary)`. When the brand color changes, you must find-and-replace across the entire codebase. Fix: always reference tokens. Lint for hard-coded color/size values.
+
+**Placeholder text as labels.** Using placeholder text instead of labels for form fields. Placeholders disappear when the user starts typing, leaving them with no indication of what the field expects. Fix: always use visible labels. Placeholders are supplementary hints, not replacements for labels.
+
+**Ignoring touch targets on mobile.** Tiny links and buttons that require precise finger tapping. Fix: ensure all interactive elements meet minimum 44x44px touch target size on mobile.
+
+**Dark mode as an afterthought.** Building the entire UI with hard-coded light colors, then trying to add dark mode later. Fix: use semantic tokens from day one. The cost is near-zero upfront and saves a complete restyle later.
+
+**Missing reduced-motion support.** Animations that cause discomfort for users with vestibular disorders. Fix: always wrap non-essential animations in a `prefers-reduced-motion` check.
+
+**Inconsistent elevation hierarchy.** A card inside a modal has a higher shadow than the modal itself, breaking the visual stacking order. Fix: define an elevation scale (sm < md < lg < xl) and assign levels consistently: page content (none), cards (sm), dropdowns (lg), modals (xl).

package/knowledge/core/dev-environment.md

@@ -0,0 +1,223 @@
+---
+name: dev-environment
+description: Development environment setup patterns including Makefile conventions, live reload, and toolchain configuration
+topics: [dev-environment, makefile, live-reload, env-files, toolchain, ci, git-hooks, scripts]
+---
+
+# Dev Environment
+
+A development environment should be reproducible, fast, and invisible. "It works on my machine" is a build system failure, not a developer excuse. This knowledge covers task runners, environment management, git hooks, CI integration, and toolchain patterns that make environments reliable across machines and team members.
+
+## Summary
+
+### Core Components
+
+Every project needs four environment pillars:
+
+1. **Build Tool / Task Runner** — A single entry point for all project tasks. Makefile is the universal choice (works everywhere, zero dependencies). Language-specific alternatives: `package.json` scripts, `pyproject.toml`, `go` tool.
+2. **Environment Management** — `.env` files for local config, `.env.example` committed as documentation, validation at startup, sensible development defaults.
+3. **Git Hooks** — Pre-commit (fast checks: lint, format, type check). Pre-push (slower checks: full test suite). Installed by `make hooks`.
+4. **CI/CD Integration** — CI runs the same commands as local development. `make check` in CI, `make check` locally. No divergent CI-specific scripts.
+
+### Makefile as Universal Task Runner
+
+Makefile provides: discoverable interface (`make help`), dependency management between targets, idempotent execution, parallel execution (`make -j4`), and universal availability on any Unix system with zero installation. Language-specific task runners complement but do not replace it — `make test` calls `npm test` or `pytest`, keeping the stable interface independent of underlying tools. If the underlying tool changes (e.g., Jest to Vitest), only the Makefile target body changes — not CI or documentation.
+
+### The Setup Contract
+
+New developer from clone to green tests in three commands or fewer:
+```bash
+git clone <repo>
+make setup    # Install dependencies, tools, hooks
+make check    # Verify everything works
+```
+
+### Branching Strategy Summary
+
+**Trunk-Based**: All commits to main, feature flags for incomplete work. For small teams with strong tests and continuous deployment. **GitHub Flow**: Feature branches, PR review, squash merge. Best for most teams — simple and structured. **GitFlow**: Separate develop/release/hotfix branches. Only for scheduled releases or multi-version support. Most web apps do not need it.
+
+## Deep Guidance
+
+### Makefile Patterns
+
+#### The Help Target
+
+Every Makefile starts with self-documentation:
+
+```makefile
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show available commands
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+```
+
+Every public target gets a `## Description` comment. Internal targets use `_` prefix and no description.
+
+#### Standard Target Set
+
+```makefile
+.PHONY: test lint format check setup clean hooks
+
+test: ## Run test suite
+	npm test
+
+lint: ## Run linters
+	npm run lint
+
+format: ## Format code
+	npm run format
+
+check: lint test ## Run all quality gates
+
+setup: ## Install dependencies and hooks
+	npm install
+	$(MAKE) hooks
+
+clean: ## Remove build artifacts
+	rm -rf dist/ node_modules/.cache/
+
+hooks: ## Install git hooks
+	@mkdir -p .git/hooks
+	@cp scripts/pre-commit.sh .git/hooks/pre-commit
+	@cp scripts/pre-push.sh .git/hooks/pre-push
+	@chmod +x .git/hooks/pre-commit .git/hooks/pre-push
+```
+
+#### Dependency Chains and Parallel Execution
+
+Targets depend on other targets: `deploy: check build` runs lint, test, and build before deploying. For CI, parallelize independent targets: `$(MAKE) -j2 lint test`.
+
+#### Variables and Platform Compatibility
+
+Use `?=` for overridable variables: `TEST_FLAGS ?=` lets users run `make test TEST_FLAGS="--watch"`. Detect OS for platform-specific commands with `UNAME := $(shell uname -s)` and conditional blocks.
+
+### Environment Variable Management
+
+#### The .env Pattern
+
+```
+.env.example     # Committed — documents all variables with safe placeholders
+.env             # Gitignored — local overrides
+.env.test        # Gitignored — test environment
+.env.production  # Never on disk — injected by deployment platform
+```
+
+`.env.example` is documentation: every variable listed with explanatory comments and placeholder values.
+
+#### Startup Validation
+
+Validate all environment variables at startup, not at point of use. Fail fast with clear messages:
+
+```typescript
+// src/config/env.ts — centralized env access
+function requireEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`Missing required env var: ${key}`);
+  return value;
+}
+
+export const config = {
+  database: { url: requireEnv('DATABASE_URL') },
+  auth: { jwtSecret: requireEnv('JWT_SECRET') },
+} as const;
+```
+
+No `process.env.SOMETHING` scattered throughout the codebase. Python equivalent: use `pydantic_settings.BaseSettings` for typed validation with defaults.
+
+### Live Reload by Stack
+
+| Stack | Tool | Command |
+|-------|------|---------|
+| Next.js / Vite | Built-in HMR | `next dev` / `vite dev` |
+| Express/Fastify | tsx watch | `tsx watch src/server.ts` |
+| FastAPI | uvicorn | `uvicorn app:app --reload` |
+| Go | air | `air` |
+| Shell | entr | `ls scripts/*.sh \| entr make test` |
+
+For full-stack projects, run frontend and backend in parallel via `make dev` using `$(MAKE) -j2 dev-frontend dev-backend` or a process manager like `concurrently`.
+
+### Git Hook Strategies
+
+#### Pre-Commit (Fast, Under 10 Seconds)
+
+Check only staged files when possible:
+- Formatting (run formatter check, fail if files would change)
+- Linting (staged files only via `lint-staged`)
+- Secrets scanning (detect accidentally committed API keys)
+- File size limits (prevent accidental binary commits)
+
+#### Pre-Push (Thorough, Under 60 Seconds)
+
+Run the full quality gate:
+- Complete test suite
+- Full lint (all files, not just staged)
+- Build verification
+
+#### Installation
+
+Single command: `make hooks`. Wrap whichever hook manager the project uses (husky, pre-commit, lefthook, or plain shell scripts).
+
+### CI/CD Integration
+
+#### The Mirror Principle
+
+CI runs `make check` — the exact same command developers run locally. If it passes locally, it passes in CI. No environment-specific surprises.
+
+```yaml
+# .github/workflows/check.yml
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - run: make check
+```
+
+#### Caching
+
+Cache dependencies keyed on lockfile hashes: `node_modules/` on `package-lock.json`, `.venv/` on `pyproject.toml`, `~/go/pkg/mod/` on `go.sum`.
+
+#### Job Structure
+
+Parallelize independent checks, gate dependent steps:
+```yaml
+jobs:
+  lint:  { steps: [checkout, setup, make lint] }
+  test:  { steps: [checkout, setup, make test] }
+  build: { needs: [lint, test], steps: [checkout, setup, make build] }
+```
+
+### Branching Strategies — When to Use Each
+
+#### Trunk-Based Development
+
+All developers commit to `main`. Feature flags gate incomplete work. Releases cut directly from `main`. Requires: strong test suite, feature flag infrastructure, team discipline. Best for: small teams (1-5), continuous deployment. Risk: broken commits affect everyone immediately.
+
+#### GitHub Flow
+
+Feature branches from `main`, PRs with review, squash merge back. `main` is always deployable. Best for: most teams, most projects. Keep branches short (1-3 days), rebase frequently. Risk: long-lived branches diverge.
+
+#### GitFlow
+
+Separate `develop`, `release/*`, `hotfix/*`, `main` branches. Formalized release process. Best for: scheduled releases (mobile, enterprise), multiple supported versions. Risk: branch complexity, merge conflicts. Most web apps do not need this.
+
+### Common Anti-Patterns
+
+**Scripts That Only Work on One OS**: `setup.sh` uses `apt-get`, breaks on macOS. Fix: detect OS and branch, or use devcontainers. Document OS-specific prerequisites.
+
+**Missing Setup Documentation**: New developer spends a day figuring out the build. Fix: `make setup` automates everything possible. `docs/dev-setup.md` covers the rest. Test by having a new team member follow it verbatim.
+
+**Hardcoded Paths**: Scripts reference `/Users/alice/projects/myapp/`. Fix: use relative paths or compute from `$(pwd)` / `$(dirname "$0")`. Never commit absolute paths.
+
+**No Clean Target**: Build artifacts accumulate, stale caches cause mystery failures. Fix: `make clean` removes generated artifacts. `make pristine` removes everything including `node_modules/` for a full reset.
+
+**CI Drift**: CI runs different commands than local dev. Fix: CI calls `make check`. If CI needs extras (artifact upload, deploy), those are separate steps after the quality gate. The gate itself is identical everywhere.
+
+## See Also
+
+- [ai-memory-management](../core/ai-memory-management.md) — Environment setup affects memory hooks