opencastle 0.10.0 → 0.10.2

package/src/orchestrator/plugins/vercel/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: vercel-deployment
+description: "Vercel deployment workflows, environment management, domain configuration, and build troubleshooting. Use when deploying, checking deployment status, reviewing build logs, or managing environments."
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+
+# Vercel Deployment
+
+Vercel-specific deployment patterns and MCP tool usage. For project-specific deployment architecture, environment variables, and key files, see [deployment-config.md](../../customizations/stack/deployment-config.md).
+
+## Deployment Model
+
+Vercel uses Git-based deployments with automatic preview and production environments:
+
+```
+main branch    → Production deployment (auto)
+feature/*      → Preview deployment (auto)
+fix/*          → Preview deployment (auto)
+```
+
+- Every push creates a deployment — no manual triggers needed
+- Preview deployments get unique URLs for testing
+- Production deploys only from the main branch
+- Rollback by redeploying a previous commit
+
+## MCP Tools
+
+The Vercel MCP server provides these tools through `https://mcp.vercel.com`:
+
+| Tool | Purpose | Primary Agents |
+|------|---------|----------------|
+| `deploy_to_vercel` | Trigger a deployment | DevOps Expert |
+| `get_deployment` | Check deployment status and metadata | DevOps, Release Manager |
+| `get_deployment_build_logs` | Read build output for debugging | DevOps, Release Manager |
+| `get_runtime_logs` | Read runtime logs for debugging | DevOps, Release Manager |
+| `list_deployments` | List recent deployments | DevOps, Release Manager |
+| `get_project` | Get project configuration | DevOps Expert |
+| `list_projects` | List all projects in the team | DevOps Expert |
+| `list_teams` | List available teams | DevOps Expert |
+| `search_vercel_documentation` | Search Vercel docs | DevOps Expert |
+| `check_domain_availability_and_price` | Domain availability check | DevOps Expert |
+
+## Environment Variables
+
+### Vercel Environment Scoping
+
+Vercel supports three environment scopes — set variables for each appropriately:
+
+| Scope | When Applied | Use For |
+|-------|-------------|---------|
+| **Production** | `main` branch deploys | Live secrets, production API keys |
+| **Preview** | All non-production branches | Staging/test API keys |
+| **Development** | `vercel dev` local server | Local development overrides |
+
+### Best Practices
+
+- Set secrets via the Vercel dashboard or CLI — never commit them
+- Use `NEXT_PUBLIC_*` prefix only for variables safe to expose to the browser
+- Verify required env vars exist in all three scopes (production, preview, development)
+- Use `.env.local` for local development; never commit this file
+
+## Build Troubleshooting
+
+When builds fail, follow this workflow:
+
+1. **Read build logs** — use `get_deployment_build_logs` to get the full output
+2. **Check common causes:**
+   - Missing environment variables (works locally but not on Vercel)
+   - Node.js version mismatch (check `engines` in `package.json`)
+   - Build command mismatch (verify in project settings)
+   - Dependency resolution issues (lockfile out of sync)
+3. **Check runtime logs** — use `get_runtime_logs` for post-deploy errors
+4. **Verify deployment status** — use `get_deployment` to check state and error details
+
+## Domain Configuration
+
+- Use `check_domain_availability_and_price` before purchasing
+- Configure domains in the Vercel dashboard
+- Always set up both `www` and apex domain with proper redirects
+- Enable HTTPS (automatic with Vercel)
+- Set appropriate DNS records (CNAME for subdomains, A record for apex)
+
+## Cron Jobs (vercel.json)
+
+```json
+{
+  "crons": [
+    {
+      "path": "/api/cron/task-name",
+      "schedule": "0 */6 * * *"
+    }
+  ]
+}
+```
+
+- Protect cron endpoints with `CRON_SECRET` — Vercel sends it in the `Authorization` header
+- Maximum execution time depends on plan (10s hobby, 60s pro, 900s enterprise)
+- Use `vercel.json` to declare cron schedules — not external schedulers

package/src/orchestrator/plugins/vercel/config.ts

@@ -7,7 +7,7 @@ export const config: PluginConfig = {
   subCategory: 'deployment',
   label: 'Vercel',
   hint: 'Deployment and hosting platform',
-  skillName: null,
+  skillName: 'vercel-deployment',
   mcpServerKey: 'Vercel',
   mcpConfig: {
     type: 'http',
@@ -27,7 +27,6 @@ export const config: PluginConfig = {
       'vercel/get_runtime_logs', 'vercel/list_deployments', 'vercel/list_projects',
     ],
   },
-  docsUrl: null,
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#vercel',
   officialDocs: 'https://vercel.com/docs',
-  mcpPackage: null,
 };

package/src/orchestrator/plugins/vitest/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: vitest-testing
+description: "Vitest unit and integration testing patterns, configuration, mocking, and coverage. Use when writing unit tests, configuring Vitest, or setting up test coverage."
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
+
+# Vitest Testing
+
+Vitest-specific unit and integration testing patterns. For project-specific test configuration, see [testing-config.md](../../customizations/stack/testing-config.md).
+
+## Commands
+
+```bash
+npx vitest                         # Run in watch mode
+npx vitest run                     # Run once (CI)
+npx vitest run --coverage          # Run with coverage report
+npx vitest run src/utils/          # Run specific directory
+npx vitest run auth.test.ts        # Run specific file
+npx vitest run -t "should validate"  # Filter by test name
+npx vitest --ui                    # Open Vitest UI
+npx vitest --reporter=json         # JSON output for CI
+npx vitest typecheck               # Run type-checking tests
+```
+
+## Test Structure
+
+### File Naming
+
+```
+src/
+├── utils/
+│   ├── format.ts
+│   └── format.test.ts         # Co-located test
+├── components/
+│   ├── Button.tsx
+│   └── Button.test.tsx        # Component test
+└── __tests__/                 # Integration tests
+    └── auth-flow.test.ts
+```
+
+### Writing Tests
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { formatPrice } from './format';
+
+describe('formatPrice', () => {
+  it('should format USD prices', () => {
+    expect(formatPrice(9.99, 'USD')).toBe('$9.99');
+  });
+
+  it('should handle zero', () => {
+    expect(formatPrice(0, 'USD')).toBe('$0.00');
+  });
+
+  it('should throw for negative values', () => {
+    expect(() => formatPrice(-1, 'USD')).toThrow('Price cannot be negative');
+  });
+});
+```
+
+## Mocking
+
+### Module Mocking
+
+```typescript
+import { vi, describe, it, expect } from 'vitest';
+
+// Mock entire module
+vi.mock('./database', () => ({
+  getUser: vi.fn().mockResolvedValue({ id: '1', name: 'Alice' }),
+}));
+
+// Mock specific export
+vi.mock('./config', async (importOriginal) => {
+  const original = await importOriginal<typeof import('./config')>();
+  return { ...original, API_URL: 'http://test-api.example.com' };
+});
+```
+
+### Spy and Stub
+
+```typescript
+import { vi, describe, it, expect } from 'vitest';
+
+describe('notifications', () => {
+  it('should call the API', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(JSON.stringify({ ok: true }))
+    );
+
+    await sendNotification('Hello');
+
+    expect(fetchSpy).toHaveBeenCalledWith('/api/notify', expect.objectContaining({
+      method: 'POST',
+    }));
+
+    fetchSpy.mockRestore();
+  });
+});
+```
+
+### Timer Mocking
+
+```typescript
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+describe('debounce', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('should debounce calls', () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, 300);
+
+    debounced();
+    debounced();
+    debounced();
+
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(300);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+});
+```
+
+## Configuration (vitest.config.ts)
+
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,                    // Use describe/it/expect without imports
+    environment: 'jsdom',             // 'node' | 'jsdom' | 'happy-dom'
+    include: ['src/**/*.test.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: ['src/**/*.test.{ts,tsx}', 'src/**/*.d.ts'],
+      thresholds: {
+        branches: 80,
+        functions: 80,
+        lines: 80,
+        statements: 80,
+      },
+    },
+    setupFiles: ['./src/test-setup.ts'],
+  },
+});
+```
+
+## Best Practices
+
+- Co-locate test files next to source files (`foo.test.ts` next to `foo.ts`)
+- Use `describe` blocks to group related tests
+- Each test should be independent — no shared mutable state between tests
+- Clean up mocks with `vi.restoreAllMocks()` in `afterEach`
+- Use `vi.mock()` at the top level — Vitest hoists mock calls automatically
+- Prefer `toEqual` for objects, `toBe` for primitives
+- Use `test.each` for parameterized tests
+- Set coverage thresholds to prevent regression
+- Use `vi.useFakeTimers()` for time-dependent code — never `setTimeout` in tests
+- Use `--reporter=json` in CI for machine-readable output

package/src/orchestrator/plugins/vitest/config.ts

@@ -0,0 +1,16 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'vitest',
+  name: 'Vitest',
+  category: 'tech',
+  subCategory: 'testing',
+  label: 'Vitest',
+  hint: 'Vite-native unit and integration testing',
+  skillName: 'vitest-testing',
+  authType: 'none',
+  envVars: [],
+  agentToolMap: {},
+  docsUrl: 'https://www.opencastle.dev/docs/plugins#vitest',
+  officialDocs: 'https://vitest.dev',
+};

package/src/orchestrator/prompts/bootstrap-customizations.prompt.md

@@ -69,7 +69,7 @@ The result is a single unified view of the project's tech stack:
 
 **Still verify:** `repoInfo` detects presence, not configuration details. You still need to read the actual config files for schemas, IDs, routes, etc.
 
-The skill matrix (`.github/customizations/agents/skill-matrix.md`) will already have the `cms` and `database` rows pre-filled based on this selection. The appropriate task management skill (`linear-task-management` for Linear, `jira-management` for Jira) and notifications skill (`slack-notifications` for Slack, `teams-notifications` for Teams) will already be installed. Verify they are correct and fill in any remaining empty rows.
+The skill matrix (`.github/customizations/agents/skill-matrix.json`) will already have the `cms` and `database` binding entries pre-filled based on this selection. The appropriate task management skill (`linear-task-management` for Linear, `jira-management` for Jira) and notifications skill (`slack-notifications` for Slack, `teams-notifications` for Teams) will already be installed. Verify they are correct and fill in any remaining empty bindings.
 
 ## Workflow
 
@@ -130,6 +130,7 @@ Files are organized into subdirectories by domain:
 ├── AGENT-PERFORMANCE.md       # Agent success tracking & log query recipes
 ├── agents/                    # Agent framework config
 │   ├── agent-registry.md
+│   ├── skill-matrix.json
 │   └── skill-matrix.md
 ├── stack/                     # Tech stack config
 │   ├── api-config.md
@@ -173,9 +174,10 @@ Files are organized into subdirectories by domain:
    - Scope descriptions
    - File partition examples
 
-7. **`agents/skill-matrix.md`** — If `.github/skills/` exists with skill definitions:
-   - Map of capability slots to skill names per agent role
-   - Which agents load which skills
+7. **`agents/skill-matrix.json`** — If `.github/skills/` exists with skill definitions:
+   - Capability slot bindings and `directSkills` per agent role (in JSON format)
+   - Which agents load which skills (slots for plugin skills, directSkills for process skills)
+   - Note: `skill-matrix.md` is a companion documentation file — the JSON is the source of truth
 
 #### `stack/` — Tech Stack Config (create only for detected technologies)
 

package/src/orchestrator/prompts/create-skill.prompt.md

@@ -21,7 +21,7 @@ OpenCastle has two kinds of skills with different locations and registration pat
 
 | Type | Location | Bound Via | Purpose |
 |------|----------|-----------|---------|
-| **Process skill** | `skills/<name>/SKILL.md` | Direct reference in agent files | Stack-agnostic methodology (testing workflow, self-improvement, validation gates) |
+| **Process skill** | `skills/<name>/SKILL.md` | `directSkills` in skill-matrix.json | Stack-agnostic methodology (testing workflow, self-improvement, validation gates) |
 | **Plugin skill** | `plugins/<plugin>/SKILL.md` | Capability slot in the skill matrix | Technology-specific knowledge (CMS queries, database patterns, deployment config) |
 
 > **Rule of thumb:** If the skill would need to be rewritten when switching technologies (e.g., Supabase → Convex), it belongs in a **plugin**. If it's useful regardless of stack, it's a **process skill**.
@@ -92,14 +92,13 @@ Registration differs by type:
 
 #### Process Skill
 
-1. **Add to the skill matrix** — Add a row to the **Process Skills (Always Direct)** table in `.github/customizations/agents/skill-matrix.md`
-2. **Reference in agent files** — Add to the `Direct Skills` section of each agent that should use it
-3. **Optional: reference in instructions** — If the skill should be loaded by default, add it to the appropriate `.github/instructions/` file
+1. **Add to the skill matrix** — Add the skill name to the `directSkills` array of each relevant agent in `.github/customizations/agents/skill-matrix.json`
+2. **Optional: reference in instructions** — If the skill should be loaded by default, add it to the appropriate `.github/instructions/` file
 
 #### Plugin Skill
 
 1. **Set `skillName` in the plugin's `config.ts`** — This connects the skill to the plugin
-2. **Update the skill matrix** — Set the Skill column for the matching capability slot row in `.github/customizations/agents/skill-matrix.md`
+2. **Update the skill matrix** — Add an entry to the matching capability slot's `entries` array in `.github/customizations/agents/skill-matrix.json`
 3. **No agent changes needed** — Agents resolve plugin skills through capability slots automatically
 
 ### Step 5: Validate
@@ -109,8 +108,8 @@ Registration differs by type:
 - [ ] Description is a single line (no line breaks)
 - [ ] Content follows the template structure
 - [ ] No overlap with existing skills
-- [ ] Skill matrix updated (process skill table or capability slot binding)
-- [ ] For process skills: at least one agent references the skill directly
+- [ ] Skill matrix updated (`directSkills` array or capability slot binding)
+- [ ] For process skills: at least one agent's `directSkills` array includes it in skill-matrix.json
 - [ ] For plugin skills: `config.ts` `skillName` matches the `name` in frontmatter
 
 ## Quality Guidelines

package/src/orchestrator/skills/agent-hooks/SKILL.md

@@ -32,7 +32,7 @@ Session Lifecycle:
 2. **Check for checkpoint** — If `.github/customizations/SESSION-CHECKPOINT.md` exists, read it. Resume from last known state instead of re-analyzing.
 3. **Check pending approvals** — If the checkpoint has a `## Pending Approvals` section, check for replies using the configured messaging provider's MCP tools (e.g., `conversations_replies` for Slack). Read `.opencastle.json` → `stack.teamTools` to determine the provider. If no messaging is configured, skip this step.
 4. **Check dead letter queue** — Scan `.github/customizations/AGENT-FAILURES.md` for pending failures related to the current scope.
-5. **Validate skill-matrix bindings** — Open `.github/customizations/agents/skill-matrix.md` and check whether the **Primary Stack** and **Tooling** tables have any filled-in rows (non-empty Technology/Skill columns). If all bindings are empty, **warn the user** that the bootstrap hasn't been run and capability slots will not resolve. Suggest running the *"Bootstrap Customizations"* prompt first. Do NOT silently continue with empty bindings.
+5. **Validate skill-matrix bindings** — Open `.github/customizations/agents/skill-matrix.json` and check whether the `bindings` object has any slots with non-empty `entries` arrays. If all entries are empty, **warn the user** that the bootstrap hasn't been run and capability slots will not resolve. Suggest running the *"Bootstrap Customizations"* prompt first. Do NOT silently continue with empty bindings.
 6. **Load domain skills** — Based on the task description, load the appropriate skills before writing code. Don't start coding without the relevant skill loaded.
 
 ### Template for Delegation Prompts
@@ -43,7 +43,7 @@ Include this reminder in every delegation:
 **Session Start:** Read `.github/customizations/LESSONS-LEARNED.md` before starting.
 Check `.github/customizations/SESSION-CHECKPOINT.md` for prior state and pending approvals.
 If pending approvals exist, check for replies via the messaging provider.
-Validate `.github/customizations/agents/skill-matrix.md` — warn if skill bindings are empty (bootstrap not run).
+Validate `.github/customizations/agents/skill-matrix.json` — warn if skill bindings are empty (bootstrap not run).
 Load relevant skills before writing code.
 ```
 

package/src/orchestrator/skills/memory-merger/SKILL.md

@@ -53,7 +53,7 @@ Each lesson has a natural home in the instruction/skill hierarchy:
 | `deployment` | `.github/skills/deployment-infrastructure/SKILL.md` |
 | `delegation` | `.github/agents/team-lead.agent.md` or `.github/skills/team-lead-reference/SKILL.md` |
 | `testing` | `.github/skills/testing-workflow/SKILL.md` |
-| `ui-library` / `framework` | The skill mapped by the corresponding slot in the skill matrix |
+| `ui` / `framework` | The skill mapped by the `framework` slot or the `react-development` direct skill |
 | Cross-cutting pattern | `.github/instructions/general.instructions.md` |
 
 ### Step 3: Draft the Merge

package/src/orchestrator/skills/nextjs-patterns/SKILL.md

@@ -1,200 +0,0 @@
----
-name: nextjs-patterns
-description: "Next.js App Router best practices for server/client components, routing, API routes, and project structure. Use when creating or modifying Next.js pages, layouts, route handlers, or Server Actions."
----
-
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .github/customizations/ directory instead. -->
-
-# Next.js Patterns (2025)
-
-## Project Structure
-
-- **Use `app/` directory** (App Router) for all routes; colocate files near where they're used.
-- Top-level: `app/`, `public/`, `lib/`, `components/`, `contexts/`, `styles/`, `hooks/`, `types/`.
-- **Route Groups** `(admin)` — group without affecting URL. **Private Folders** `_internal` — opt out of routing.
-- Feature folders for large apps: `app/dashboard/`, `app/auth/`.
-
-## Server and Client Components
-
-**Default: Server Components** — data fetching, heavy logic, non-interactive UI.
-
-**Client Components** — add `'use client'` at top. Use for interactivity, state, browser APIs.
-
-### Decision Table
-
-| Need | Component Type | Why |
-|------|---------------|-----|
-| Fetch data at request time | Server | Direct DB/API access, no client waterfall |
-| Read cookies/headers | Server | Available only on the server |
-| Interactive UI (clicks, inputs) | Client | Requires event handlers |
-| Use `useState` / `useEffect` | Client | React hooks need client runtime |
-| Access browser APIs (localStorage, geolocation) | Client | Not available on server |
-| Render static/non-interactive content | Server | Smaller bundle, faster paint |
-| Show loading spinners for async children | Server (with `<Suspense>`) | Streams HTML progressively |
-
-### Critical Rule
-
-**Never use `next/dynamic` with `{ ssr: false }` inside a Server Component.** This causes build/runtime errors.
-
-**Correct approach:** Move client-only logic into a dedicated `'use client'` component, then import it normally.
-
-```tsx
-// Server Component — imports a Client Component directly
-import DashboardNavbar from '@/components/DashboardNavbar';
-export default async function DashboardPage() {
-  return <><DashboardNavbar /></>;
-}
-```
-
-## Data Fetching Patterns
-
-### Server-Side Fetching
-
-Fetch directly in `async` Server Components. Next.js deduplicates identical `fetch` calls.
-
-```tsx
-export default async function ProjectsPage() {
-  const projects = await fetch('https://api.example.com/projects', {
-    next: { revalidate: 60 }, // ISR: revalidate every 60s
-  }).then((res) => res.json());
-  return <ul>{projects.map((p: { id: string; name: string }) => <li key={p.id}>{p.name}</li>)}</ul>;
-}
-```
-
-### Server Actions (mutations)
-
-Define with `'use server'`. Call from Client Components via `action` or `startTransition`.
-
-```tsx
-// lib/actions.ts
-'use server';
-import { revalidatePath } from 'next/cache';
-export async function createItem(formData: FormData) {
-  const name = formData.get('name') as string;
-  await db.items.create({ data: { name } });
-  revalidatePath('/items');
-}
-```
-
-```tsx
-// components/CreateItemForm.tsx — calls the Server Action
-'use client';
-import { createItem } from '@/lib/actions';
-export default function CreateItemForm() {
-  return <form action={createItem}><input name="name" required /><button type="submit">Add</button></form>;
-}
-```
-
-## Error Handling
-
-Each route segment can export `error.tsx` (must be a Client Component) and `not-found.tsx`.
-
-```tsx
-// app/dashboard/error.tsx — must be a Client Component
-'use client';
-export default function DashboardError({ error, reset }: { error: Error; reset: () => void }) {
-  return <div role="alert"><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;
-}
-```
-
-```tsx
-// app/projects/[id]/page.tsx — use notFound() to trigger not-found.tsx
-import { notFound } from 'next/navigation';
-export default async function ProjectPage({ params }: { params: { id: string } }) {
-  const project = await getProject(params.id);
-  if (!project) notFound();
-  return <h1>{project.name}</h1>;
-}
-```
-
-## Middleware
-
-Place `middleware.ts` at the project root (next to `app/`). Runs before every matched request.
-
-```ts
-import { NextResponse, type NextRequest } from 'next/server';
-export function middleware(request: NextRequest) {
-  const token = request.cookies.get('session')?.value;
-  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
-    return NextResponse.redirect(new URL('/login', request.url));
-  }
-  return NextResponse.next();
-}
-export const config = { matcher: ['/dashboard/:path*', '/settings/:path*'] };
-```
-
-## Component Practices & Naming
-
-- PascalCase for component files/exports. camelCase for hooks.
-- Shared components in `components/`. Route-specific in route folder.
-- TypeScript interfaces for props. Explicit types and defaults.
-- Co-locate tests with components.
-- Folders: `kebab-case`. Types/Interfaces: `PascalCase`. Constants: `UPPER_SNAKE_CASE`.
-
-## API Routes (Route Handlers)
-
-- Location: `app/api/` (e.g., `app/api/users/route.ts`).
-- Export async functions named after HTTP verbs (`GET`, `POST`, etc.).
-- Use Web `Request`/`Response` APIs. `NextRequest`/`NextResponse` for advanced features.
-- Dynamic segments: `[param]`.
-- Validate with Zod/Yup. Return appropriate status codes.
-- Protect sensitive routes with middleware or server-side session checks.
-
-## Performance Patterns
-
-### Dynamic Imports (Client Components only)
-
-Lazy-load heavy Client Components to reduce initial bundle size.
-
-```tsx
-'use client';
-import dynamic from 'next/dynamic';
-const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
-  loading: () => <p>Loading chart…</p>,
-});
-```
-
-### Parallel Data Fetching
-
-Initiate independent fetches simultaneously — don't `await` sequentially.
-
-```tsx
-export default async function DashboardPage() {
-  const [metrics, activity] = await Promise.all([getMetrics(), getRecentActivity()]);
-  return <><MetricsPanel data={metrics} /><ActivityFeed items={activity} /></>;
-}
-```
-
-### Streaming with Suspense
-
-Wrap slow data sections in `<Suspense>` so the shell renders immediately.
-
-```tsx
-import { Suspense } from 'react';
-export default function Layout({ children }: { children: React.ReactNode }) {
-  return <main><Suspense fallback={<p>Loading…</p>}>{children}</Suspense></main>;
-}
-```
-
-## General Best Practices
-
-- TypeScript with `strict` mode. ESLint with official Next.js config.
-- Secrets in `.env.local` — never committed.
-- Built-in Image and Font optimization.
-- Suspense and loading states for async data.
-- Avoid large client bundles — keep logic in Server Components.
-- Semantic HTML and ARIA attributes.
-- Do NOT create example/demo files unless explicitly requested.
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It's Wrong | Do This Instead |
-|-------------|---------------|-----------------|
-| `'use client'` on every component | Bloats JS bundle, defeats RSC benefits | Default to Server Components; add `'use client'` only when needed |
-| Sequential `await` for independent data | Creates a waterfall, slows page load | Use `Promise.all()` for parallel fetches |
-| `next/dynamic` with `ssr: false` in Server Components | Build/runtime crash | Extract to a Client Component, import normally |
-| Fetching in `useEffect` when server fetch works | Extra client roundtrip, loading flash | Fetch in the Server Component or use Server Actions |
-| Giant `layout.tsx` with all providers | Hard to test, couples unrelated concerns | Split providers into a `Providers` Client Component |
-| Catching errors without `error.tsx` | Unhandled errors crash the page | Add `error.tsx` per route segment |
-| Hardcoding secrets in source files | Security risk, leaks in version control | Use `.env.local` and `process.env` |
-| Skipping `loading.tsx` / `<Suspense>` | Blank screen while data loads | Add `loading.tsx` or wrap in `<Suspense>` |