@vpxa/aikit 0.1.308 → 0.1.310

package/scaffold/dist/definitions/skills/present.mjs

@@ -1 +1,193 @@
-function e(){return[{file:`SKILL.md`,content:'---\nname: present\ndescription: "Use the AI Kit `present` tool to display rich interactive dashboards, charts, timelines, status boards, and data visualizations in the browser or in-chat. Covers all 32 block types, chart types, actions, annotation system, and template contracts. Load this skill before calling the present tool to ensure professional output."\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [data, analysis]\n  outputs: [dashboards, charts, reports]\n  requires: [aikit]\nargument-hint: "Content to present — data, analysis results, status report, comparison, or interactive MCP App"\n---\n\n# Present Tool — Rich Interactive Dashboards\n\n> **Three-tier authoring model:** (1) Free-form `blocks[]`, (2) Named presets with structured data, (3) Viewer templates for custom HTML/iframes. Use `aikit://schemas/channel-surface` for block catalog, `aikit://present/presets` for preset contracts, `aikit://present/templates` for viewer schemas.\n\nThe tool normalizes all three input tiers into a validated `ChannelSurface` before rendering. Pipeline: **Input -> Normalizer -> ChannelSurface -> Transport Registry -> Render**. Validation errors return structured feedback with fix suggestions — not raw schema dumps.\n\n## 0. Auto-Activation & Feedback\n\n**When you include `actions` or set `response.required: true`, the present tool automatically activates browser transport.** You don\'t need to manually set `preferBrowser`.\n\n**A `💬 Feedback` action is automatically appended to every action array** so users can always provide input. It appears as a text-submit field at the end of the action list. This is added automatically — you do NOT need to include it in your `actions` array.\n\nFor surfaces without actions, the inline MCP App transport is used (renders inside the chat if supported).\n\n## 0b. Error Recovery\n\nWhen the present tool returns an error:\n- **`VALIDATION` errors**: Field-level fix suggestions are returned. Common issues:\n  - `unknown block type`: Check the block type name — a list of closest matches is returned\n  - `schemaVersion !== 1`: Always set `schemaVersion: 1`\n  - `title missing`: Title is always required\n  - `invalid field type`: The fix suggestion tells you the expected type\n- **`RENDER_FAILED` errors**: The block data is valid but rendering failed. Try simplifying the surface or switching to browser transport.\n- **Use `raw` field** for complex payloads (mermaid, code, many blocks) — the `raw` JSON string auto-repair handles common LLM JSON errors (unescaped newlines, trailing commas).\n\n## 1. Presets (Tier 2)\n\nPresets are named data contracts that expand `blocks[]` from structured input. 8 presets registered at runtime via `aikit://present/presets`:\n\n| Preset | Input shape | Expands to |\n|--------|------------|------------|\n| `summary` | `{ title, summary, passed?: number, failed?: number }` | heading, markdown, metrics |\n| `plan` | `{ title, steps: [{ label, checked }] }` | heading, checklist |\n| `understanding` | `{ title, explanation, details?: string }` | heading, markdown, kv |\n| `bug-analyze` | `{ title, severity, status, code?: string, analysis?: string }` | heading, kv, code, markdown |\n| `task-done` | `{ title, items: [{ label, checked }], completed?, total? }` | heading, checklist, metrics |\n| `review` | `{ title, criteria: [{ label, checked }] }` | heading, checklist + actions |\n| `explore` | `{ title, findings: [{ heading, code }] }` | heading, code (per finding) |\n| `decision` | `{ title, recommendation, options?: [{ title, items }] }` | heading, kv, comparison |\n\nEach preset supplies `inputSchema` (JSON Schema), `example` (JSON), and `expandsTo` (block description).\n\n## 2. All 32 Content Blocks\n\nPass content as a `blocks` array of `{ type, title?, value }` objects.\n\n| Category | Type | Value shape | Use for |\n|----------|------|-------------|---------|\n| **Content** | `prompt` | string | Prompt or callout text |\n| | `text` | string | Plain text without markdown parsing |\n| | `heading` | string | Standalone section headings |\n| | `paragraph` | string | Standalone paragraph copy |\n| | `markdown` | string | Prose, headings, code snippets |\n| | `code` | string | Code or diff excerpts |\n| | `list` | string[] | Bullet list items |\n| | `separator` | none | Visual divider |\n| | `diff` | `{ files: [{ path, hunks: [{ header, changes: [{ type, content }] }] }] }` | File diffs with +/- highlights |\n| | `finding` | `{ label: string; description?: string; severity?: string }` | Finding with severity pill (critical/high/medium/low) |\n| **Data** | `table` | `Record[]` or `{ headers, rows }` | Tabular data |\n| | `metrics` | `[{ label, value, trend?, status? }]` | KPI cards |\n| | `kv` | `Record<string, string>` | Key-value pairs |\n| | `tags` | string[] | Tag pills |\n| | `data-table-schema` | `{ fields: [{ name, type, required?, description?, constraints?, indexes? }] }` | Schema table with indexes |\n| | `chart` | `{ chartType, data, xKey?, yKeys? }` | `line | area | bar | horizontal-bar | pie | donut | sparkline | heatmap` |\n| **Visualization** | `cards` | `[{ title, body?, badge?, status? }]` | Summary cards |\n| | `tree` | `{ name, children? }` | Hierarchies |\n| | `timeline` | `[{ title, description?, timestamp?, status? }]` | Event sequences |\n| | `mermaid` | string | Diagrams |\n| | `graph` | `{ nodes: [{id, label?}], edges: [{from, to, label?}] }` | Network graphs |\n| | `comparison` | `[{title, items}]` or `{columns: [{title, items}]}` | Side-by-side comparisons |\n| | `lifecycle-flow` | `{ nodes: [{ id, label, type? }], edges: [{ source, target, label? }] }` | SVG flow diagram |\n| | `component-detail` | `{ name, type?, description?, responsibilities?, interfaces?, dependencies?, metrics?, codeLinks? }` | Component detail view |\n| **Interactive** | `checklist` | `[{ label, checked }]` | Task lists |\n| | `status-board` | `[{category, items}]` or `{items: [{category, items}]}` | Service health boards |\n| | `progress` | `{label, value, max?}` or `{items: [{label, value, max?, color?}]}` | Progress bars |\n| | `docs-browser` | `{ files: [{path, title?, content?, status?}], title? }` | Documentation indexes |\n| | `annotation` | `{ items: [{ label, description?, severity? }] }` | Annotation groups |\n| | `approval` | `{ options: [{ label, value }], comment?: string }` | Approval with options/textarea |\n| | `docs-hub` | `{ title, items: [{ title, description?, status? }] }` | Doc hub card grid |\n| **Layout** | `actions` | `[{ type, id, label, variant?, options? }]` | Inline action group |\n| | `separator` | none | Visual divider |\n\n> **Rules:**\n> - Prefer `table` blocks for tabular data (pipe tables in `markdown` are auto-normalized).\n> - Use `{ chartType, data, xKey, yKeys }`, not Chart.js `{ labels, datasets }`.\n> - Keep `markdown` for prose, headings, and code, not UI structure.\n> - **NEVER use `code` block for structured data** — use `table`, `checklist`, `kv`, or `markdown`.\n> - **NEVER JSON.stringify() data into a `code` or `markdown` block** — use the typed block.\n> - Block `title` is rendered as a section heading above the block (except for `heading` and `finding` types).\n\n### Data → Block Type Quick Reference\n\n| Your data looks like... | Use this block type | NOT this |\n|---|---|---|\n| Array of strings (decisions, findings, steps) | `list` or `markdown` (bullet list) | ~~`code` with JSON array~~ |\n| Key-value pairs (status, config, metadata) | `kv` or `table` (two columns) | ~~`code` with JSON object~~ |\n| Rows × columns (comparisons, components) | `table` | ~~`markdown` with pipe table~~ |\n| Items with done/not-done state | `checklist` | ~~`markdown` with checkmarks~~ |\n| Hierarchical items (file tree, org chart) | `tree` | ~~`code` with indentation~~ |\n| Numeric KPIs with labels | `metrics` | ~~`markdown`~~ |\n| Before/after or option A vs B | `comparison` | ~~two `code` blocks~~ |\n| Findings with severity | `finding` | ~~`markdown`~~ |\n| Approval or decision required | `approval` + `actions` | ~~`markdown` with options~~ |\n\n## 3. Actions & Annotation\n\nAction shape: `{ type, id, label, variant?, options? }`\n\nValid action types: `button | select | multi-select | form-submit | text-submit | confirm | custom`\n\n**Auto-activation:** Any `actions` array triggers browser transport automatically. The `response.required` flag also triggers browser transport.\n\n**Feedback action:** A "💬 Feedback" text-submit action is automatically appended to every action array. This lets users provide input without you having to add it manually.\n\n```json\n{ "actions": [{ "type": "button", "id": "ack", "label": "Acknowledge", "variant": "primary" }] }\n```\n\n## 4. MCP App Templates\n\n| Template | Purpose | Data shape | Returns |\n|----------|---------|------------|---------|\n| `list-sort` | Reorder a ranked list | `{ items: [{ id, label }] }` | Reordered items |\n| `data-table` | Inspect structured rows | `{ columns, rows, stats? }` | Selection/filter |\n| `picker` | Choose items from categories | `{ categories, items }` | Selected IDs |\n| `flame-graph` | Explore hierarchical totals | `{ profile }` | Clicked node |\n| `form` | Collect field values | `{ fields }` | Field map |\n| `checklist` | Interactive checklist | `{ items, title? }` | Checked state |\n| `document` | Structured long-form content | `{ sections, title? }` | Display only |\n| `report` | Synthesized report content | `{ title, sections, metrics?, tables? }` | Display only |\n| `error` | Structured error states | `{ code, message, details?, stack? }` | Display only |\n| `kanban` | Move cards across columns | `{ columns, cards }` | Card move |\n| `timeline` | Ordered milestones | `{ events }` | Display only |\n| `tree` | Browse nested nodes | `{ root }` | Display only |\n| `diff-view` | Show file diffs | `{ files, stats? }` | Display only |\n| `dashboard` | Show metric cards | `{ metrics }` | Display only |\n| `status-board` | Grouped status views | `{ categories }` | Display only |\n\n## 5. Viewer Templates\n\n| Template | Transport | Purpose |\n|----------|-----------|---------|\n| `c4-static@1` | mcp-app | Static architecture diagram |\n| `c4@1` | browser | Interactive architecture diagram |\n| `process-flow-static@1` | mcp-app | Static process flow |\n| `process-flow@1` | browser | Interactive process flow |\n| `tour@1` | browser | Guided walkthrough |\n| `task-plan-static@1` | mcp-app | Static task execution plan |\n| `task-plan@1` | browser | Interactive task plan with ReactFlow |\n\n## 6. Rules\n\n- **Auto-activation**: `actions` or `response.required` → browser transport. No `actions` → inline MCP App.\n- **Feedback**: A Feedback action is auto-appended. You do NOT need to add it.\n- **Error recovery**: Read the `fixSuggestion` field in validation errors — it tells you exactly what to change.\n- Use `raw` field for complex payloads to leverage auto-repair.\n- For custom HTML demos, write an HTML file, serve locally, open with `browser({ action: "open", url, mode: "ui" })`.\n- For surfaces with mixed content types (metrics + chart + table + markdown), combine them in one `blocks` array.\n- For structured data, prefer `table`, `kv`, `checklist`, `metrics` over reformatting in markdown.\n'}]}export{e as default};
+function e(){return[{file:`SKILL.md`,content:`---
+name: present
+description: "Use the AI Kit present tool for rich dashboards, charts, timelines, status boards, data tables, reviews, approvals, and interactive MCP App surfaces. Load before calling present so output uses the right block/template/action contract and stays readable."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: always
+  inputs: [data, analysis]
+  outputs: [dashboards, charts, reports]
+  requires: [aikit]
+argument-hint: "Content to present - data, analysis results, status report, comparison, or interactive MCP App"
+---
+
+# Present Tool
+
+Use present for complex user-facing output: reports, dashboards, evidence maps, plans, reviews, comparisons, approvals, charts, timelines, and interactive selections. Plain text is only for tiny status/questions.
+
+## Authoring Model
+
+Choose one:
+- blocks: direct markdown/heading/table/chart/cards/metrics/checklist/timeline/status-board/etc.
+- template + data: report, task-plan, review, dashboard, diff, checklist, picker, form.
+- raw JSON: complex surfaces where hand-authored object is clearer.
+
+Always include schemaVersion: 1 and title. Use concise description when helpful.
+
+## Selection Guide
+
+| Need | Shape |
+|---|---|
+| Summary/report | report template or heading + markdown/table |
+| Plan/progress | task-plan/checklist/status-board |
+| Metrics/trends | metrics + chart |
+| Compare options | table + kv + recommendation |
+| Review/approval | review template + approval action |
+| Logs/errors | code/error block |
+| Choice | actions select/confirm/button |
+
+## Actions
+
+- Use actions for buttons, selects, multi-selects, confirmations, and text-submit.
+- Browser transport activates automatically when actions or response.required exist.
+- Free-form text input should use text-submit or elicitation when available.
+- Keep action ids stable, labels short, variants meaningful.
+
+## Quality Bar
+
+- One clear title, no giant unstructured markdown dumps.
+- Tables have parallel columns and compact cells.
+- Charts include labels/units and enough context.
+- Approval surfaces state consequence and options clearly.
+- Accessibility: readable order, text equivalents, no color-only meaning.
+- Do not put secrets or huge raw tool output in surfaces.
+
+## Debugging
+
+If validation fails, fix schema shape first. Use schema/preset/template resources only when block contract is unclear.
+
+## References
+
+Load on demand:
+- references/block-catalog.md — Complete 32-block type catalog with value shapes, best block for each data type, and rules.
+- references/presets-templates.md — Preset contracts (8 presets), viewer templates (6), MCP App templates (14), and error recovery patterns.
+`},{file:`references/block-catalog.md`,content:`# Block Catalog — 32 Content Blocks
+
+Pass content as blocks array of { type, title?, value } objects.
+
+## Content Blocks
+
+| Type | Value shape | Use for |
+|------|-------------|---------|
+| prompt | string | Prompt or callout text |
+| text | string | Plain text without markdown parsing |
+| heading | string | Standalone section headings |
+| paragraph | string | Standalone paragraph copy |
+| markdown | string | Prose, headings, code snippets |
+| code | string | Code or diff excerpts |
+| list | string[] | Bullet list items |
+| separator | none | Visual divider |
+| diff | { files: [{ path, hunks }] } | File diffs with +/- highlights |
+| finding | { label, description?, severity? } | Finding with severity pill |
+
+## Data Blocks
+
+| Type | Value shape | Use for |
+|------|-------------|---------|
+| table | Record[] or { headers, rows } | Tabular data |
+| metrics | [{ label, value, trend?, status? }] | KPI cards |
+| kv | Record<string, string> | Key-value pairs |
+| tags | string[] | Tag pills |
+| data-table-schema | { fields: [{ name, type, required? }] } | Schema table |
+| chart | { chartType, data, xKey?, yKeys? } | line/area/bar/horizontal-bar/pie/donut/sparkline/heatmap |
+
+## Visualization Blocks
+
+| Type | Value shape | Use for |
+|------|-------------|---------|
+| cards | [{ title, body?, badge?, status? }] | Summary cards |
+| tree | { name, children? } | Hierarchies |
+| timeline | [{ title, description?, timestamp?, status? }] | Event sequences |
+| mermaid | string | Diagrams |
+| graph | { nodes, edges } | Network graphs |
+| comparison | [{title, items}] or {columns} | Side-by-side comparisons |
+| lifecycle-flow | { nodes, edges } | SVG flow diagram |
+| component-detail | { name, type?, description? } | Component detail view |
+
+## Interactive / Layout
+
+| Type | Value shape | Use for |
+|------|-------------|---------|
+| checklist | [{ label, checked }] | Task lists |
+| status-board | [{category, items}] | Service health |
+| progress | {label, value, max?} | Progress bars |
+| docs-browser | { files } | Documentation indexes |
+| annotation | { items } | Annotation groups |
+| approval | { options, comment? } | Approval with options/textarea |
+| docs-hub | { title, items } | Doc hub card grid |
+| actions | [{ type, id, label }] | Inline action group |
+
+## Data-to-Block Quick Reference
+
+| Your data looks like... | Use this block type |
+|---|---|
+| Array of strings | list or markdown |
+| Key-value pairs | kv or table (2 columns) |
+| Rows x columns | table |
+| Done/not-done state | checklist |
+| Hierarchical items | tree |
+| Numeric KPIs | metrics |
+| Before/after or A vs B | comparison |
+| Findings with severity | finding |
+`},{file:`references/presets-templates.md`,content:`# Presets, Templates, and Error Recovery
+
+## 8 Named Presets
+
+| Preset | Input shape | Expands to |
+|--------|-------------|------------|
+| summary | { title, summary, passed?, failed? } | heading, markdown, metrics |
+| plan | { title, steps } | heading, checklist |
+| understanding | { title, explanation, details? } | heading, markdown, kv |
+| bug-analyze | { title, severity, status, code?, analysis? } | heading, kv, code, markdown |
+| task-done | { title, items, completed?, total? } | heading, checklist, metrics |
+| review | { title, criteria } | heading, checklist + actions |
+| explore | { title, findings } | heading, code |
+| decision | { title, recommendation, options? } | heading, kv, comparison |
+
+Each preset supplies inputSchema (JSON Schema), example (JSON), and expandsTo (block description) via aikit://present/presets.
+
+## 6 Viewer Templates
+
+| Template | Transport | Purpose |
+|----------|-----------|---------|
+| c4@1 | browser | Interactive C4 architecture diagram |
+| c4-static@1 | mcp-app | Static architecture diagram |
+| process-flow@1 | browser | Interactive process flow |
+| process-flow-static@1 | mcp-app | Static process flow |
+| tour@1 | browser | Guided walkthrough |
+| task-plan@1 | browser | Interactive task plan with ReactFlow |
+
+## 14 MCP App Templates
+
+| Template | Purpose | Returns |
+|----------|---------|---------|
+| list-sort | Reorder ranked list | Reordered items |
+| data-table | Inspect structured rows | Selection/filter |
+| picker | Choose items from categories | Selected IDs |
+| flame-graph | Explore hierarchical totals | Clicked node |
+| form | Collect field values | Field map |
+| checklist | Interactive checklist | Checked state |
+| document | Structured long-form content | Display only |
+| report | Synthesized report | Display only |
+| error | Structured error states | Display only |
+| kanban | Move cards across columns | Card move |
+| timeline | Ordered milestones | Display only |
+| tree | Browse nested nodes | Display only |
+| diff-view | Show file diffs | Display only |
+| dashboard | Show metric cards | Display only |
+| status-board | Grouped status views | Display only |
+
+## Error Recovery
+
+When present returns VALIDATION errors:
+- unknown block type: check closest matches in response
+- schemaVersion !== 1: always set schemaVersion: 1
+- title missing: title is always required
+- invalid field type: fix suggestion tells expected type
+
+For RENDER_FAILED errors: data is valid but rendering failed. Simplify surface or switch to browser transport.
+
+Use raw JSON string field for complex payloads — auto-repair handles unescaped newlines and trailing commas.
+
+A Feedback text-submit action is automatically appended to every actions array.
+`}]}export{e as default};

package/scaffold/dist/definitions/skills/react.mjs

@@ -12,98 +12,69 @@ metadata:
 
 # React
 
-> Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization. Synthesized from react-dev patterns, react-patterns (React 19), and Vercel React best practices.
+Use for React components, hooks, pages, Server Components, Server Actions, data fetching, performance, and React code review. Pair with typescript and frontend-design when relevant.
 
-## When to Use
+## Mental Model
 
-**MANDATORY** for the Frontend agent on every React task. Also use when:
-- Building React components, hooks, or pages
-- Working with Server Components or Server Actions
-- Optimizing React performance (re-renders, bundle size, data fetching)
-- Reviewing React code for correctness and best practices
+React renders UI from state. Keep render pure, state minimal, effects rare, data flow explicit, and component boundaries aligned with user-facing behavior.
 
-## Thinking Model
+## Component Design
 
-React is a **description language for UI**, not an imperative framework. Think in snapshots, not steps:
-- "Given this state, what should the screen look like?" (declarative)
-- NOT "When this happens, do these 5 things in order" (imperative)
+- Prefer small components with clear props and ownership.
+- Keep derived values out of state; compute or memoize only when needed.
+- Split container/data logic from presentational pieces when it reduces complexity.
+- Preserve accessibility semantics; use buttons/forms/labels before custom roles.
+- Use existing component library and styling conventions.
 
-The render function is a PURE function of (props, state) → JSX. Side effects live in clearly-marked boundaries (effects, event handlers, server actions).
+## State + Effects
 
-**Server vs Client boundary** — the most common architectural mistake in modern React:
-- Default to Server Components (zero JS shipped, direct data access)
-- Add 'use client' only when you need: event handlers, useState/useEffect, browser APIs
-- The boundary is a CONTRACT — server can render client, client CANNOT import server
+Use local state for local UI, URL state for navigable filters/tabs, server/cache state for remote data, context for stable cross-tree values.
 
-Before coding, decide in this order:
-1. **What is pure UI derivation?** Keep it in render.
-2. **What is interaction state?** Keep it in the smallest client boundary.
-3. **What is data loading or mutation?** Prefer server.
-4. **What is side effect vs event response?** Effects synchronize with outside systems; event handlers respond to user intent.
+Effects are for synchronization with external systems. Avoid effects for derivations, event handling, or copying props into state.
 
-## Decision Flow
+## Hooks
 
-When implementing a React feature, follow this order:
+- Follow exhaustive deps; fix design instead of suppressing rule.
+- Custom hooks own reusable behavior, not arbitrary grouping.
+- useMemo/useCallback only for measured/reasonable identity or expensive computation needs.
+- useRef for mutable instance values that should not trigger render.
 
-1. **Server or Client?**
-  - If it needs browser APIs, event handlers, or local interaction state → Client Component.
-  - Everything else starts as a Server Component.
-  - Keep the client boundary as small as possible: interactive leaf, server parent.
+## React 19 / Server
 
-2. **Derived state or stored state?**
-  - If a value can be computed from props/state during render, do NOT store it.
-  - Store only user input, async status, or state you cannot recompute cheaply or correctly.
+- Server Components fetch/read server data and avoid client JS where possible.
+- Client Components handle interactivity, browser APIs, local state, and effects.
+- Keep server/client boundary explicit; do not pass non-serializable values across.
+- Server Actions need validation, auth, and error handling like any endpoint.
 
-3. **Data loading location?**
-  - Initial fetch on server.
-  - Client refetch/cache only when data must stay live after hydration or respond to client events.
+## Performance
 
-4. **Mutation path?**
-  - Forms and mutations: Server Action + validation.
-  - Use \`useActionState\` for submission state/errors.
-  - Add \`useOptimistic\` only when instant feedback materially improves UX.
+Check actual render cause before optimizing. Common fixes:
+- Move state down or split components.
+- Stabilize expensive props only where identity matters.
+- Virtualize long lists.
+- Code split route-heavy UI.
+- Use Suspense/loading boundaries sized to avoid layout shift.
 
-5. **Effect or not?**
-  - If synchronizing with DOM, network subscription, timer, or external API → effect.
-  - If reacting to user input → event handler.
-  - If deriving view state → render logic, not effect.
+## Forms + Errors
 
-6. **Error and loading boundaries?**
-  - Rendering latency → \`<Suspense>\` with a real skeleton.
-  - Render failures → Error Boundary.
-  - Mutation failures → return structured errors from the Server Action.
+- Controlled inputs for dynamic validation; uncontrolled/form actions when simpler.
+- Preserve user input on failure.
+- Show inline field errors and summary for multi-field failures.
+- Error boundaries for render failures; user-safe messages only.
 
-7. **Performance pass?**
-  - Start with correct boundaries and minimal client JS.
-  - Then rely on React Compiler if enabled.
-  - Only then add manual memoization, virtualization, or code splitting where profiling justifies it.
+## Validation Before Done
 
-8. **Extraction pass?**
-  - Business rules → hooks, utilities, or server functions.
-  - Components stay focused on describing UI.
+Run relevant tests/checks. For UI changes, verify browser screenshot/interaction paths when possible: desktop, mobile, keyboard, loading, error, empty states.
 
-## NEVER
+## References
 
-- **NEVER use \`useEffect\` for derived state** — if you can compute it from props/state, compute it inline or with \`useMemo\`. Effects for derivation cause extra renders and race conditions.
-- **NEVER put business logic in components** — components are UI description, not business rules. Extract logic to hooks, utilities, or server functions.
-- **NEVER use \`any\` to silence TypeScript in component props** — use \`unknown\` and narrow, or fix the actual type. \`any\` in props infects the entire component tree.
-- **NEVER create a context for state that only one component reads** — prop drilling 2-3 levels is fine. Context adds re-render cost to EVERY consumer.
-- **NEVER \`await\` inside \`useEffect\` directly** — use an inner async function or a data-fetching library. Direct await creates unhandled promise rejections and races.
-- **NEVER conditionally call hooks** — hooks must be called in the same order every render. If you need conditional logic, move it INSIDE the hook.
-- **NEVER spread props onto DOM elements without filtering** — \`{...props}\` passes unknown attributes to the DOM, causing console warnings and potential XSS vectors.
-- **NEVER render a list without a stable key** — index-as-key causes state corruption on reorder. Use a domain ID or generate a stable key from content.
+Load on demand:
+- references/component-patterns.md — Code examples: extend native, discriminated union, generic, children typing, ref as prop.
+- references/server-actions.md — Full Server Component, Server Action, and optimistic update code examples.
+`},{file:`references/component-patterns.md`,content:`# Component Patterns
 
-## React 19 Quick Reference
+## Extend Native Elements
 
-- \`ref\` as prop — no \`forwardRef\` wrapper for common cases
-- \`use()\` — read promises/context during render
-- \`useActionState\` + \`<form action>\` — form mutations with server actions
-- \`useOptimistic\` + \`useTransition\` — optimistic and non-urgent updates
-- Server Components / Server Actions — default to server, opt into client only when needed
-
-## Component Patterns
-
-### Extend Native Elements
 \`\`\`tsx
 type ButtonProps = React.ComponentProps<"button"> & {
   variant?: "primary" | "secondary" | "ghost";
@@ -115,7 +86,8 @@ function Button({ variant = "primary", size = "md", className, ...props }: Butto
 }
 \`\`\`
 
-### Discriminated Union Props
+## Discriminated Union Props
+
 \`\`\`tsx
 type ModalProps =
   | { variant: "alert"; message: string; onConfirm: () => void }
@@ -129,7 +101,8 @@ function Modal(props: ModalProps) {
 }
 \`\`\`
 
-### Generic Components
+## Generic Components
+
 \`\`\`tsx
 type TableProps<T> = {
   data: T[];
@@ -142,7 +115,8 @@ function Table<T extends Record<string, unknown>>({ data, columns, onRowClick }:
 }
 \`\`\`
 
-### Children Typing
+## Children Typing
+
 - Specific children: \`React.ReactElement<TabProps>[]\`
 - Render prop: \`(data: T) => React.ReactNode\`
 - Text-only API: \`string\`
@@ -157,9 +131,21 @@ function Input({ ref, ...props }: React.ComponentProps<"input">) {
 
 Callback refs can return cleanup functions in React 19. Use that for measurement/subscription teardown instead of scattering cleanup elsewhere.
 
-## Server Components & Actions
+## Event Handler Types
+
+Prefer exact DOM event types at the boundary: \`MouseEvent<HTMLButtonElement>\`, \`ChangeEvent<HTMLInputElement>\`, \`FormEvent<HTMLFormElement>\`. Broad \`SyntheticEvent\` is usually typing too late.
+
+## Hooks Typing
+
+- \`useState\` — model UI state with explicit unions, not booleans that drift out of sync.
+- \`useRef<HTMLInputElement>(null)\` for DOM refs; mutable refs only for non-render state.
+- \`useReducer\` — discriminated union actions when state transitions are non-trivial.
+- Custom hooks returning tuples should use \`as const\`.
+- Context consumers should null-guard and fail fast outside their provider.
+`},{file:`references/server-actions.md`,content:`# Server Components & Actions
+
+## Server Component (default — no directive needed)
 
-### Server Component (default — no directive needed)
 \`\`\`tsx
 import { db } from "@/lib/db";
 
@@ -169,7 +155,8 @@ export default async function UsersPage() {
 }
 \`\`\`
 
-### Client Component (explicit opt-in)
+## Client Component (explicit opt-in)
+
 \`\`\`tsx
 "use client";
 import { useState } from "react";
@@ -180,7 +167,8 @@ export function Counter({ initialCount }: { initialCount: number }) {
 }
 \`\`\`
 
-### Server Action with Form
+## Server Action with Form
+
 \`\`\`tsx
 "use server";
 import { z } from "zod";
@@ -212,7 +200,8 @@ export function CreateUserForm() {
 }
 \`\`\`
 
-### Optimistic Updates
+## Optimistic Updates
+
 \`\`\`tsx
 "use client";
 import { useOptimistic } from "react";
@@ -242,36 +231,4 @@ function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (text: string) =
   );
 }
 \`\`\`
-
-## Event Handler Types
-
-Prefer exact DOM event types at the boundary: \`MouseEvent<HTMLButtonElement>\`, \`ChangeEvent<HTMLInputElement>\`, \`FormEvent<HTMLFormElement>\`. If you start with a broad \`SyntheticEvent\`, you are probably typing too late.
-
-## Hooks Typing
-
-- \`useState\` — model UI state with explicit unions, not booleans that drift out of sync
-- \`useRef<HTMLInputElement>(null)\` for DOM refs; mutable refs only for non-render state
-- \`useReducer\` — discriminated union actions when state transitions are non-trivial
-- Custom hooks returning tuples should use \`as const\`
-- Context consumers should null-guard and fail fast outside their provider
-
-## Performance Rules
-
-### Prevent Async Waterfalls
-\`\`\`tsx
-const user = await getUser(id);
-const posts = await getPosts(user.id);
-
-const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
-\`\`\`
-
-### Performance Checklist
-- Server Components first; ship less JS before optimizing JS
-- \`<Suspense>\` + streaming for slow server work
-- SWR/React Query when client data must stay fresh after hydration
-- React Compiler first, then manual \`useMemo\`/\`useCallback\` only when profiling proves need
-- Virtualize lists >100 items; defer heavy client work with \`useDeferredValue\`
-- Lazy load below-fold components; prefer named imports for tree-shaking
-- Avoid passing large objects across the server/client boundary
-
 `}];export{e as default};