@caddis/cli 0.0.0 → 0.2.0

package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: feature-plan
+description: Create a phased, TDD-structured implementation plan that acts as the durable spine for multi-session work
+---
+
+# /feature-plan — phased plan (the durable spine)
+
+Create an implementation plan for: **$ARGUMENTS**
+
+If `$ARGUMENTS` is empty, ask what to plan and stop.
+
+The plan file is the **durable spine of the harness** — it must let any future session (or another
+agent, on any tool) resume with zero re-discovery. Optimize for that.
+
+## Headless mode
+When the invocation contains the marker **`HEADLESS RUN RULES`** (a docket runner / non-interactive
+caller spawned this session — no human is present), the scope-check questions and any interview are
+**suspended and forbidden**. This mode exists for one-line ideas: the card may be a short title with **no
+description**, and there may be **no codebase, PROJECT-FACTS, or prior PRD** to read. That is expected —
+write a complete best-effort plan anyway.
+
+Absolute rules in this mode (they override everything below):
+- **NEVER ask a question, request clarification, or end your turn with questions.** Replying with a list
+  of scoping questions is a hard failure. Never use AskUserQuestion, never pause, never wait for input.
+- **A bare title (or PRD path) is sufficient input.** Where information is missing, invent a reasonable,
+  conventional interpretation, state it explicitly as an assumption in `## Constraints & decisions`, and
+  proceed. Making an explicit assumption is ALWAYS correct; asking is ALWAYS wrong here. If you feel you
+  lack information, **write an assumption and continue** — never ask.
+- **Every unresolved decision becomes an `[TECH-DECISION OPEN]` note** (inline in the relevant phase) or
+  a bullet under `## Constraints & decisions` — never a question to the user.
+- **Honor the caller's output path and slug** (falling back to `.caddis/plans/<feature-slug>.md`);
+  set `feature: <slug>` in the frontmatter to that slug.
+- **Also emit a visual companion** — a self-contained, scannable HTML page at `<artifact_dir>/<slug>.html`
+  presenting the plan visually (a goal card, phases as cards with their steps, an affected-files table,
+  and a risks/decisions section). **Use inline `<style>` ONLY** — the visual is rendered in a *sandboxed*
+  iframe with no script execution, so a `<script>`/CDN (e.g. the Tailwind browser CDN) would NOT run and
+  the page would appear unstyled. Keep it fully portable — no external `<script>`/`<link>`, no local
+  asset files, no `/`-rooted paths. This is the visual the human reviews in docket alongside the markdown.
+  Write it after the `.md`; the runner finds it by the matching `<slug>.html` name.
+- **Always write the plan file, then end with exactly one fenced `json` highlights block** — nothing
+  after it:
+  ```json
+  {"artifact":"<artifact_dir>/<slug>.md","summary":"<=280 chars>","open_questions":<int>}
+  ```
+
+The only acceptable final output in this mode is the written plan plus its highlights block — never
+questions. Everything below applies in both modes; only the interview/scope questions are skipped.
+
+## Step 1 — Scope check
+Read the relevant code first (don't guess). **Ground in the workspace scan:** if `.caddis/PROJECT-FACTS.md`
+exists (setup-project-ai extracts it — run/test/build commands, env-var names, CI/deploy workflows, entry
+points), read it first. It's a free, token-zero project fingerprint that anchors the plan in what actually
+exists instead of assumed. If the work fits comfortably in one session, say so and offer to just do it
+instead of planning. Only produce a plan for genuinely multi-phase work.
+
+## Step 2 — Design phases
+Break the work into **independently completable** phases (~30–60 min each, clear exit gate). Each phase
+follows the harness loop: **RED → GREEN → REFACTOR → VERIFY → COMMIT**. Front-load risk.
+
+**Derive risks from the workspace scan** (PROJECT-FACTS + a quick look), not generic boilerplate: **no test
+setup** → every phase carries regression risk, build its tests first; **no CI/deploy workflow** → the only
+gate is local, say so; **auth / migration / secret-handling** in scope → flag security/structural risk on
+those phases. Put what the scan actually shows into the plan's `## Risks` table.
+
+Before writing the plan, consider dispatching the **preflight** subagent to validate your assumptions
+(paths, symbols, APIs, primitives) against the codebase — it routinely catches wrong assumptions early.
+
+### Assign a model tier + effort per phase (don't default everything to the priciest)
+Match capability to each phase's difficulty — not one model for the whole plan. Use Claude Code's
+evergreen `/model` aliases so this never rots as model names change:
+- **cheap** (`/model haiku`) — mechanical, fully-specced, repeat-of-an-existing-pattern phases.
+- **mid** (`/model sonnet`) — standard feature work with clear specs. **This is the default.**
+- **frontier** (`/model opus`) — novel architecture, tricky algorithms, security-sensitive or
+  judgment-heavy seams; also recommend a `code-reviewer` pass.
+- **ultra** (`/model fable`) — RARE: long-horizon / multi-step / can't-self-verify work (large-codebase
+  reasoning, scientific). ~2× opus's rate-limit burn — reserve for the few phases that truly need it.
+Default to **mid**; reserve frontier/ultra for phases that earn them. Effort is a secondary knob: leave
+it at your session default and note **"bump to `high`"** only on a genuinely hard phase. `max` is manual
+escalation, never a planned default.
+
+### Assign an execution LANE per phase (which harness runs it — not just which model)
+A tier can be served by an OSS provider instead of Anthropic (cheat sheet:
+`docs/guide/multi-model-workflow.md`; wiring: the caddis repo's `.caddis/plans/model-access.md`):
+- **claude** (default) — this session, `/model <alias>` as above. Required for judgment-heavy,
+  security-sensitive, or novel-architecture phases.
+- **glm-headless** — mechanical, fully-specced phases run on GLM without touching Claude quota:
+  `claude-glm -p "/caddis:implement <plan-path> — Phase N only"` (from the repo root, on the
+  feature branch). The local-coder gate below exists exactly so these phases survive a weaker
+  implementer — a phase may only take this lane if it passes that gate.
+- **review lane (every phase that touches code)** — cross-vendor review by a vendor that did NOT
+  write the code: `python .github/tools/oss_review.py --range main..HEAD --provider deepseek`
+  (Claude or GLM implemented) or `--provider glm` / a Claude `code-reviewer` pass (DeepSeek-adjacent
+  work). Never same-vendor.
+
+## Step 3 — Write the plan to `.caddis/plans/<feature-slug>.md`
+
+Create `.caddis/plans/` if it doesn't exist.
+
+```markdown
+---
+type: plan
+status: draft
+feature: <feature-slug>
+creation-agent: caddis
+Original Author: Claude Code
+Creation Date: <YYYY-MM-DDTHH:MM:SSZ>
+Creating Model: <model-id>
+---
+
+# <Feature> — Implementation Plan
+**Created:** <ISO date>  •  **Status:** Phase 1 of N  •  **Spine for:** <one-line goal>
+
+## Goal
+<2–3 sentences: what we're building and why.>
+
+## Current state
+<What exists now that's relevant — cite real files/symbols verified against the codebase.>
+
+## Constraints & decisions
+- <key tech decision + rationale>
+
+## Phases
+
+### Phase 1 — <name>  ⏳
+> ⚠️ **Switch model/lane BEFORE starting this phase** — the *active* model does the work, not the
+> one named here. Lane `claude`: run `/model <alias>`. Lane `glm-headless`: run the exact command below.
+**Model:** <tier> (`/model <alias>`) — <one-line rationale tied to this phase's difficulty>
+**Lane:** claude — this session  |  glm-headless — `claude-glm -p "/caddis:implement <this plan's path> — Phase 1 only"`
+**Session:** continue | **fresh** (start a new session for this phase — note why: lane change / heavy context)
+**Goal:** <one sentence>
+**Touches:** `<files>`
+**TDD:**
+  - RED: failing test(s) — `<test file>::<case>` asserting <behavior>
+  - GREEN: <minimal implementation>
+  - REFACTOR: <what to clean if needed>
+**Verify (subagents):** dispatch `tester` (must return passed), then `code-reviewer` (verdict: approved)
+**Cross-review:** `python .github/tools/oss_review.py --range main..HEAD --provider <vendor that did NOT implement>` → REVIEW: CLEAN
+**Exit gate:** <specific, testable — e.g. "GET /api/x returns 200 with {shape}", not "tests pass">
+**Commit:** `<conventional commit message>`
+**Then:** update the Tracker row (status + hash) → `/caddis:handoff` if ending the session here.
+
+### Phase 2 — <name>  🔲
+<same structure>
+
+## Execution protocol (standing rules — this plan is the memory, not anyone's head)
+- One phase at a time: read this plan → run the phase on its **Lane** → RED→GREEN→VERIFY→CROSS-REVIEW→
+  COMMIT → update the **Tracker** row. The Tracker is the resume signal for every future session.
+- **Session boundaries:** `/caddis:handoff` after any phase that ends a sitting. Start a FRESH
+  session (or `/clear`) before any phase marked `Session: fresh`, before a lane change, or whenever
+  context feels heavy. Resume with exactly: `read <this plan's path> and implement the next ⏳ phase`.
+- **Ship gate:** NEVER push or merge to main from a phase — phases only commit to the feature branch.
+  When all phases are ✅: `/caddis:ship-pr` (stops at green CI), then STOP and wait for the human's
+  explicit go before `/caddis:ship-merge`.
+
+## Affected files
+| File | Action |
+|---|---|
+
+## Risks
+| Risk | Mitigation |
+|---|---|
+
+## Tracker (update as you go — this is the resume signal)
+| Phase | Model | Lane | Status | Commit | Cross-review | Notes |
+|---|---|---|---|---|---|---|
+| 1 | mid | claude | not started | — | — | |
+```
+
+## Plan quality gate — local-coder ready (MANDATORY)
+The plan must be executable by a **low-capability local coder model** (the planner→coder handoff: a
+strong model plans, a cheaper/local model implements). The plan carries the intelligence; the coder
+only follows it. Before finishing, verify every phase against this gate — a phase that fails it is not
+done:
+- **Exact paths** — every file to create/edit is named in full (no "the relevant service file").
+- **Exact symbols** — function/class/component names and signatures are spelled out, not described.
+- **Pre-decided judgment** — no "choose an approach", "use a suitable library", or open options left to
+  the coder. If there's a decision, make it here with the rationale.
+- **Explicit data bindings** — exact field paths / response shapes the code must read or produce.
+- **Copy-paste verification** — each phase's exit gate is a literal command to run + expected output,
+  not "tests pass".
+- **No abbreviation** — never "etc.", "similar to Phase 1", "and so on". Write every item in full.
+- **Model tier named** — every phase names a tier (cheap/mid/frontier/ultra) + a one-line rationale; no
+  phase silently defaults to the most expensive model. Default mid; frontier/ultra only where justified.
+- **Lane + reviewer named** — every phase names its execution lane (`claude` or `glm-headless`, with
+  the literal launch command for glm phases) and a cross-review provider that is a different vendor
+  than the implementer. A glm-headless phase MUST pass every bullet of this gate — that lane has no
+  slack for reasoning out gaps.
+
+If any phase relies on the implementer *reasoning out* a gap, close the gap in the plan now.
+
+## Step 4 — Report
+Output the plan path (`.caddis/plans/<feature-slug>.md`), the phase list (one line each, with each
+phase's model tier + lane), confirm the local-coder gate passed (or list the phases that need
+tightening), and: *"To start: `read the plan and implement Phase 1`. To resume later: `/handoff` at
+session end, then `read relay.md` next time. The plan's Execution protocol carries every command —
+nothing to memorize."*
+
+Do not start implementing — this command only produces the plan.

package/bundles/antigravity-plugin/skills/frontend-design/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications. Generates creative, polished code that avoids generic AI aesthetics while strictly adhering to the user's technical standards.
+---
+
+# Frontend Design Skill
+
+This skill guides the creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+## 1. Core Principle: Avoid "AI Slop"
+- **Typography:** Avoid system fonts (Inter, Arial, Roboto). Pair a distinctive display font (e.g., *Cormorant Garamond*, *Playfair Display*, *Space Mono*) with a refined, readable body font. Use dramatic scale jumps ($h1 > 5rem$ vs metadata $< 0.75rem$).
+- **Color & Theme:** Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Visuals:** Create atmosphere and depth using textures (grain, noise), glassmorphism, or complex gradients rather than defaulting to solid flat colors.
+
+## 2. Technical Implementation Standards
+**CRITICAL:** You must ignore generic React patterns. Instead, you represent the specific technical architecture defined in the user's stack.
+
+**Mandatory Reference:**
+Before writing any component logic, state management, or hooks, you must cross-reference and apply the patterns found in:
+`./references/my-tech-stack.md`
+
+Specifically, you must:
+1.  **Use Composition:** Build flexible UIs using the *Composition Over Inheritance* and *Compound Component* patterns defined in the reference file.
+2.  **Use Custom Hooks:** Do not write ad-hoc logic for debouncing or toggling; use `useDebounce` and `useToggle` from the reference.
+3.  **Optimize Performance:** Apply `useMemo` and `useCallback` strictly according to the "Memoization Rules" in the reference.
+4.  **Ensure Stability:** Wrap complex or risky components in the `ErrorBoundary` pattern provided.
+5.  **Enforce Accessibility:** Follow the keyboard navigation and focus management patterns exactly as specified.
+
+## 3. Design Thinking Process
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Tone:** Pick an extreme (Brutalist, Luxury, Retro-futuristic, Editorial, Industrial).
+- **Motion:** Use animations for effects and micro-interactions. Focus on high-impact moments (staggered page loads) rather than scattered micro-interactions.
+- **Differentiation:** What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+## 4. Output Requirements
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- **Production-grade:** Functional, responsive, and accessible.
+- **Visually striking:** Memorable and cohesive with a clear point-of-view.
+- **Technically compliant:** Strictly follows the architecture in `my-tech-stack.md`.
+
+## 5. Transition Integrity (No Stale UI)
+
+For data-heavy views that switch entities (profile A → profile B), enforce deterministic transitions:
+
+- Use a **single render region** (e.g., Streamlit's `st.empty()`) that replaces its entire content on each render pass.
+- **NEVER use dynamic keys** (nonce, entity ID) on containers inside `st.empty()` — dynamic keys cause the framework to create *new* DOM nodes instead of replacing existing ones, leaving ghost/shadow copies visible for 1-2 seconds until frontend reconciliation catches up.
+- Use **stable keys** on inner containers. The render region handles content replacement; inner containers just need stable identity for in-place DOM updates.
+- Temporarily hide high-salience identity panels/tabs during loading to avoid ghosted prior-state flashes.
+- Execute state transitions outside container context managers to avoid interrupted cleanup.
+
+Acceptance rule: users must only perceive `old state → loader → new state`, with no stale intermediate artifacts.
+
+## 6. Dial System — Design Variance Controls
+
+Calibrate these three dials per project before writing any component. Declare them in a comment at the top of the main design file.
+
+```ts
+// DESIGN_VARIANCE: 7      // 1 (safe/corporate) → 10 (experimental/editorial)
+// MOTION_INTENSITY: 5     // 1 (static) → 10 (cinematic)
+// VISUAL_DENSITY: 4       // 1 (minimal/lots of space) → 10 (data-dense/information-heavy)
+```
+
+| Dial | 1–3 | 4–6 | 7–10 |
+|---|---|---|---|
+| `DESIGN_VARIANCE` | Standard grid, safe palette | Distinctive but accessible | Experimental layout, bold choices |
+| `MOTION_INTENSITY` | Opacity fade only | Entrance animations, hover states | Parallax, stagger, spring physics |
+| `VISUAL_DENSITY` | Hero + CTA, generous whitespace | Cards with secondary info | Dashboard-style, compact rows |
+
+**Rule**: Do not override the user's declared dials. If undeclared, infer from context and state your assumption.
+
+## 7. AI Tells — Forbidden Patterns
+
+These are signals of generic AI output. Every instance must be eliminated:
+
+### Generic Names
+- ❌ `Company Name`, `Your Brand`, `Hello, World!`, `Example Corp`
+- ✅ Invent plausible, domain-specific content: `Meridian Analytics`, `Kaspar & Voss`, `Orin Health`
+
+### Fake Placeholder Numbers
+- ❌ `$1,234.56`, `1,234 users`, `99.9% uptime`, `42 orders`
+- ✅ Domain-plausible numbers with realistic variance: `$14,820`, `3,241 customers`, `99.4% uptime`, `127 orders`
+
+### AI Copywriting Clichés
+- ❌ "Empowering your workflow", "Seamlessly integrated", "Next-generation solution", "Unlock the power of..."
+- ✅ Specific, functional copy: "Track invoice aging in real time", "Filter by region, team, or date"
+
+### Oversaturated Accents
+- ❌ `#FF6B6B` coral-pink, `#6C63FF` purple-blue gradient (the two default AI accent colors)
+- ✅ Chosen from the brief or brand guide; if absent, pick something unexpected: amber, forest green, slate
+
+### Generic Iconography
+- ❌ Rocket ship for launching, lightbulb for ideas, three horizontal bars for "menu" on desktop nav
+- ✅ Icons that match the actual function; text labels as fallback if icon meaning is ambiguous
+
+## 8. Typography Discipline
+
+- **Maximum 2 font families** — one display (headings), one text (body + UI). Loading 3+ is a performance and taste failure.
+- **Optical sizing**: Headings at `6rem+` need `letter-spacing: -0.03em`. Text under `0.875rem` needs `letter-spacing: 0.01em`.
+- **Vertical rhythm**: `line-height: 1.6` for body, `1.1–1.2` for large headings, `1.4` for UI labels.
+- **Scale**: Use a modular scale (1.25× or 1.333×), not arbitrary sizes. Common scale: `0.75 / 0.875 / 1 / 1.125 / 1.5 / 2 / 3 / 4.5rem`.
+- **Weight contrast**: Body at 400, labels at 500, headings at 700–800. Avoid using 4 or more weights.
+
+```css
+/* Correct optical sizing */
+.hero-heading {
+  font-size: clamp(3rem, 6vw + 1rem, 6rem);
+  line-height: 1.05;
+  letter-spacing: -0.04em;
+}
+.body-text {
+  font-size: 1rem;
+  line-height: 1.625;
+  letter-spacing: 0;
+}
+```
+
+## 9. Color Calibration
+
+- **Maximum 1 accent color** — two accents compete; zero creates bland work.
+- **Palette minimum**: Background, Surface (+1 level of elevation), Text, Muted text, Border, Accent, Destructive.
+- **Forbidden**: Purple/blue AI gradient cliché (`from-purple-500 to-blue-600` or equivalent). Use if and only if the brand explicitly requires it.
+- **Dark mode**: Shift background to `hsl(220 15% 8%)` range, not pure black (`#000`). Pure black with white text fails contrast for long reading.
+- **Accent contrast**: Accent on background must pass WCAG AA (4.5:1 for normal text, 3:1 for large text / UI components).
+
+```css
+/* ✅ Correct token setup */
+:root {
+  --bg: hsl(220 15% 97%);
+  --surface: hsl(220 15% 100%);
+  --text: hsl(220 25% 12%);
+  --muted: hsl(220 10% 50%);
+  --border: hsl(220 15% 88%);
+  --accent: hsl(38 92% 50%);       /* Amber — unexpected, not AI-default */
+  --destructive: hsl(0 72% 51%);
+}
+```
+
+## 10. Layout Diversification
+
+When `DESIGN_VARIANCE` > 4, **ban the centered-hero-with-CTA default** layout. Use instead:
+
+| Layout Pattern | When to Use |
+|---|---|
+| **Editorial split** — large text left, visual right (or reversed) | Brand/marketing pages |
+| **Bento grid** — asymmetric tiles of varying sizes | Dashboards, feature showcases |
+| **Fullbleed scroll narrative** — content revealed on scroll sections | Storytelling, case studies |
+| **Sidebar dock + content** — persistent nav or filter rail | Application interfaces |
+| **Masonry** — uneven column heights | Media, portfolio grids |
+| **Timeline / sequence** — vertical progression with connectors | Onboarding, process flows |
+
+**Never** stack all sections centered on a 1200px `max-width` container unless `DESIGN_VARIANCE` ≤ 3.
+
+## 11. Interactive State Completeness
+
+Every interactive element must implement all four states before the component is done:
+
+| State | What to Implement |
+|---|---|
+| **Loading** | Skeleton, spinner, or disabled appearance while data fetches |
+| **Empty** | Non-generic empty state with context-specific message + action |
+| **Error** | Specific error message, retry action, not just "Something went wrong" |
+| **Tactile** | Hover + active (pressed) visual feedback — scale, shadow, or color shift |
+
+```tsx
+// ✅ Complete interactive state example
+function DataCard({ id }: { id: string }) {
+  const { data, error, status } = useQuery(...)
+  
+  if (status === 'pending') return <CardSkeleton />
+  if (status === 'error')   return <ErrorCard message={error.message} onRetry={refetch} />
+  if (!data.items.length)   return <EmptyCard title="No records yet" action={<CreateButton />} />
+  
+  return (
+    <div className="group transition-all hover:shadow-md hover:-translate-y-0.5 active:scale-[0.99]">
+      {/* content */}
+    </div>
+  )
+}
+```
+
+## 12. Data Realism
+
+Never use placeholder data that signals the interface is unfinished:
+
+| ❌ Avoid | ✅ Use Instead |
+|---|---|
+| "Lorem ipsum dolor sit amet" | Domain-appropriate text: "Q3 revenue shows 14% growth vs prior quarter" |
+| User: "John Doe" | Plausible name + avatar initial: "Margot Belleview" |
+| Date: "January 1, 2024" | Recent plausible date: "Feb 12, 2026" |
+| Metric: "1,234" | Realistic variance: "3,817" (not round numbers with too many digits) |
+| Chart data: constant line | Realistic noise with trend: slight growth with variance |
+
+**Rule**: Each piece of sample data should make a reviewer believe it could be real production data, not a template. If the user provides real data patterns, use them precisely.

package/bundles/antigravity-plugin/skills/frontend-design/references/my-tech-stack.md

@@ -0,0 +1,127 @@
+# My Technical Standards & Architecture Patterns
+
+This document serves as the technical reference for all frontend implementation. When building components or pages, follow these structural patterns to ensure performance, stability, and clean code.
+
+## 1. Component Patterns
+
+### Composition Over Inheritance
+Build flexible UIs by composing small, focused components rather than deep inheritance chains.
+
+```
+export function Card({ children, variant = 'default' }) {
+  return <div className={`card card-${variant}`}>{children}</div>
+}
+
+export function CardHeader({ children }) {
+  return <div className="card-header">{children}</div>
+}
+
+// Usage: <Card><CardHeader>Title</CardHeader></Card>
+```
+
+### Compound Components
+Share implicit state between related components via context to keep logic encapsulated.
+
+```
+const TabsContext = createContext(undefined)
+
+export function Tabs({ children, defaultTab }) {
+  const [activeTab, setActiveTab] = useState(defaultTab)
+  return (
+    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
+      {children}
+    </TabsContext.Provider>
+  )
+}
+
+export function Tab({ id, children }) {
+  const ctx = useContext(TabsContext)
+  if (!ctx) throw new Error('Tab must be used within Tabs')
+  return (
+    <button 
+      className={ctx.activeTab === id ? 'active' : ''} 
+      onClick={() => ctx.setActiveTab(id)}
+    >
+      {children}
+    </button>
+  )
+}
+```
+
+## 2. Custom Utility Hooks
+
+```
+// Debounce hook for search/expensive inputs
+export function useDebounce(value, delay) {
+  const [debounced, setDebounced] = useState(value)
+  useEffect(() => {
+    const handler = setTimeout(() => setDebounced(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+  return debounced
+}
+
+// Simplified toggle hook
+export function useToggle(initial = false) {
+  const [value, setValue] = useState(initial)
+  const toggle = useCallback(() => setValue(v => !v), [])
+  return [value, toggle]
+}
+```
+
+## 3. Performance Optimization
+
+### Memoization Rules
+- Use `useMemo` for any data transformation or sorting of lists.
+- Use `useCallback` for event handlers passed to components wrapped in `React.memo`.
+
+```
+// useMemo for expensive computations
+const sorted = useMemo(() => items.sort((a, b) => b.score - a.score), [items])
+
+// React.memo for pure leaf components
+export const ItemCard = React.memo(({ item }) => (
+  <div className="item-card"><h3>{item.name}</h3></div>
+))
+```
+
+## 4. Accessibility Patterns
+
+### Keyboard Navigation
+Always handle key events for custom interactive widgets to ensure screen-reader and keyboard compatibility.
+
+```
+const handleKeyDown = (e) => {
+  switch (e.key) {
+    case 'ArrowDown': e.preventDefault(); setIndex(i => Math.min(i + 1, max)); break
+    case 'ArrowUp': e.preventDefault(); setIndex(i => Math.max(i - 1, 0)); break
+    case 'Enter': e.preventDefault(); onSelect(options[index]); break
+    case 'Escape': onClose(); break
+  }
+}
+```
+
+## 5. Error Boundary Pattern
+Wrap complex sections (like third-party widgets) in a safety net to prevent app crashes.
+
+```
+export class ErrorBoundary extends React.Component {
+  state = { hasError: false, error: null }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div className="error-fallback">
+          <h2>Something went wrong</h2>
+          <button onClick={() => this.setState({ hasError: false })}>Try again</button>
+        </div>
+      )
+    }
+    return this.props.children
+  }
+}
+```