opencastle 0.9.0 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencastle",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "type": "module",
   "description": "Multi-agent orchestration framework for AI coding assistants",
   "bin": {

package/src/dashboard/node_modules/.vite/deps/_metadata.json

@@ -1,25 +1,25 @@
 {
-  "hash": "d4030ca8",
+  "hash": "7bf3afa3",
   "configHash": "30f8ea04",
-  "lockfileHash": "30f69af6",
-  "browserHash": "5c8328e9",
+  "lockfileHash": "4dee6fd1",
+  "browserHash": "388c1549",
   "optimized": {
     "astro > cssesc": {
       "src": "../../../../../node_modules/cssesc/cssesc.js",
       "file": "astro___cssesc.js",
-      "fileHash": "5802e199",
+      "fileHash": "8b8909d3",
       "needsInterop": true
     },
     "astro > aria-query": {
       "src": "../../../../../node_modules/aria-query/lib/index.js",
       "file": "astro___aria-query.js",
-      "fileHash": "3b8b6441",
+      "fileHash": "6711698e",
       "needsInterop": true
     },
     "astro > axobject-query": {
       "src": "../../../../../node_modules/axobject-query/lib/index.js",
       "file": "astro___axobject-query.js",
-      "fileHash": "12a97af5",
+      "fileHash": "c309d205",
       "needsInterop": true
     }
   },

package/src/orchestrator/customizations/agents/skill-matrix.md

@@ -50,7 +50,9 @@ Agent file                  Skill Matrix                 Skill file
 | `api-layer` | | | API routes, validation, search architecture |
 | `data-pipeline` | | | ETL, scraping, data processing |
 | `testing` | | | Unit/integration tests, coverage, test planning |
-| `e2e-testing` | | | Browser automation, viewport testing, visual validation || `task-management` | | | Issue tracking, naming, priorities, workflow states |
+| `e2e-testing` | | | Browser automation, viewport testing, visual validation |
+| `task-management` | | | Issue tracking, naming, priorities, workflow states |
+
 ### Disciplines
 
 | Slot | Approach | Skill | Description |

package/src/orchestrator/skills/deployment-infrastructure/SKILL.md

@@ -19,6 +19,119 @@ All deployment configuration is project-specific. See [deployment-config.md](../
 - Use short cache durations for frequently changing assets (e.g., favicon: `max-age=86400`)
 - Load the **security-hardening** skill for full header inventory and CSP configuration
 
+## Environment Variable Management
+
+### Layering & Precedence
+
+Environment variables follow a layered override model (lowest to highest priority):
+
+1. `.env` — shared defaults, committed to repo (no secrets)
+2. `.env.local` — developer-specific overrides, git-ignored
+3. `.env.production` / `.env.preview` — environment-specific values
+4. Platform-injected variables — set in hosting dashboard, highest priority
+
+### Validation at Startup
+
+Validate required variables at application startup. Fail fast with clear messages:
+
+```typescript
+// src/lib/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  API_SECRET: z.string().min(32),
+  PUBLIC_SITE_URL: z.string().url(),
+  CRON_SECRET: z.string().min(16),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+### Naming & .gitignore
+
+- `PUBLIC_*` or `NEXT_PUBLIC_*` — safe to expose to the browser
+- `SECRET_*` or `*_SECRET` — server-only, never bundled into client code
+- `CRON_SECRET` — authenticates scheduled job endpoints
+- Use `SCREAMING_SNAKE_CASE` for all variable names
+- Always gitignore `.env.local`, `.env.*.local`, and `.env.production`
+
+## CI/CD Pipeline Patterns
+
+### Branch-Based Deployment
+
+```
+main branch    → Production deployment (auto)
+feature/*      → Preview deployment (auto)
+fix/*          → Preview deployment (auto)
+```
+
+### Generic Pipeline Stages
+
+Every pipeline should include these stages in order:
+
+1. **Install** — restore dependencies from lockfile (`--frozen-lockfile`)
+2. **Lint** — static analysis and formatting checks
+3. **Test** — unit and integration tests with coverage
+4. **Build** — production build (catches type errors and build-time issues)
+5. **Deploy** — push artifacts to hosting platform
+
+### Cron Job Authentication
+
+Protect scheduled endpoints with a shared secret:
+
+```typescript
+// app/api/cron/route.ts
+export async function GET(request: Request) {
+  const authHeader = request.headers.get('authorization');
+  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+  // ... run scheduled task
+  return Response.json({ ok: true });
+}
+```
+
+## Caching Strategy
+
+### Cache Duration Reference
+
+| Asset Type | `Cache-Control` Header | Rationale |
+|---|---|---|
+| Hashed static assets (JS, CSS) | `public, max-age=31536000, immutable` | Content-addressed filenames; safe to cache forever |
+| Images / fonts | `public, max-age=31536000, immutable` | Typically fingerprinted; long-lived |
+| Favicon / manifest | `public, max-age=86400` | Changes rarely but should refresh within a day |
+| HTML pages (SSG) | `public, max-age=0, must-revalidate` | Serve stale while revalidating |
+| API responses | `private, no-cache` | User-specific or frequently changing |
+| Prerendered pages (ISR) | `public, s-maxage=3600, stale-while-revalidate=86400` | CDN caches for 1 hour, serves stale for up to 1 day |
+
+Apply cache headers via framework config (e.g., `headers()` in `next.config.js`) or CDN rules. Match each route pattern to the appropriate duration from the table above.
+
+## Security Headers
+
+Apply these headers globally via framework config or middleware. See the **security-hardening** skill for full CSP configuration.
+
+```javascript
+// Recommended security headers
+const securityHeaders = [
+  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'X-XSS-Protection', value: '1; mode=block' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+  { key: 'Content-Security-Policy', value: "default-src 'self'; script-src 'self' 'unsafe-inline';" },
+];
+```
+
+**Key rules:**
+
+- HSTS `max-age` must be at least 1 year (31536000 seconds) for preload eligibility
+- `X-Frame-Options: DENY` prevents clickjacking — use `SAMEORIGIN` only if you embed your own pages
+- CSP should be as restrictive as possible; expand only when needed, document each exception
+- Disable unused browser features via `Permissions-Policy`
+
 ## Release Process
 
 ### 1. Pre-Release Audit
@@ -31,7 +144,7 @@ All deployment configuration is project-specific. See [deployment-config.md](../
 - Identify features adjacent to changes and spot-check them
 - Run full test suites for all affected projects (not just changed files)
 - Check deployment preview builds for visual regressions
-- Verify critical user flows still work (homepage, search, venue detail)
+- Verify critical user flows still work (e.g., primary navigation, form submissions, authenticated pages)
 
 ### 3. Changelog & Release Notes
 - Generate changelog from commit messages and PR titles since last release
@@ -48,4 +161,32 @@ All deployment configuration is project-specific. See [deployment-config.md](../
 - Confirm deployment succeeded on production
 - Smoke-test production URLs for critical pages
 - Monitor error rates and performance metrics post-release
-- Document rollback steps if issues arise
+- Have rollback steps documented and ready (see § Rollback Procedures)
+
+## Rollback Procedures
+
+**Two rollback strategies** (prefer platform-level when available):
+
+1. **Platform rollback** — promote the last known-good deployment from the hosting dashboard
+2. **Git revert** — `git revert -m 1 HEAD && git push origin main` (triggers a clean redeploy)
+
+### Rollback Checklist
+
+- [ ] Confirm the issue is deployment-related (not a data or third-party issue)
+- [ ] Roll back via platform or git revert — never force-push to `main`
+- [ ] Verify the rollback deployment is healthy (smoke tests)
+- [ ] Notify the team with a summary of what was rolled back and why
+- [ ] Create a post-mortem ticket to investigate root cause
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong | Correct Approach |
+|---|---|---|
+| Hardcoding secrets in source code | Secrets leak via git history, logs, and client bundles | Use environment variables; validate with Zod at startup |
+| Skipping preview deployments | Bugs reach production without visual review | Deploy every branch to a preview environment |
+| Using `Cache-Control: no-store` everywhere | Destroys performance; every request hits origin | Use appropriate cache durations per asset type (see table above) |
+| Force-pushing to `main` to "fix" a bad deploy | Destroys git history; breaks other developers' branches | Use `git revert` to cleanly undo changes |
+| Disabling security headers "temporarily" | Temporary becomes permanent; opens attack surface | Keep headers strict; expand only with documented exceptions |
+| Running builds without `--frozen-lockfile` | Non-deterministic installs; works locally, fails in CI | Always use `--frozen-lockfile` (or equivalent) in CI |
+| Storing `.env.local` in the repository | Developer secrets and tokens leak to all contributors | Add `.env.local` to `.gitignore`; share via secure vault |
+| No startup validation of env vars | App starts but crashes later with cryptic errors | Validate all required variables at boot (fail fast) |

package/src/orchestrator/skills/documentation-standards/SKILL.md

@@ -38,11 +38,9 @@ Generic documentation templates and writing standards. For project-specific dire
 ## Roadmap Update Template
 
 When a feature is completed:
-1. Change status to `COMPLETE`
-2. Add completion date
-3. List modified files
-4. Update the summary table at the top
-5. Move to completed section if applicable
+1. Change status to `COMPLETE` and add completion date
+2. List modified files and update the summary table
+3. Move to completed section if applicable
 
 ## Architecture Decision Record Template
 
@@ -57,16 +55,107 @@ When a feature is completed:
 **Alternatives Considered:** [What else was evaluated]
 ```
 
+## README Template
+
+Use this structure for library or feature-level READMEs:
+
+```markdown
+# Feature / Library Name
+
+One-sentence summary of what this does and why it exists.
+
+## Quick Start
+
+Brief usage example or setup steps.
+
+## Architecture
+
+High-level overview. Include a Mermaid diagram for non-trivial systems.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/handler.ts` | Request handling logic |
+| `src/schema.ts` | Validation schemas |
+```
+
+## Mermaid Diagram Patterns
+
+Keep diagrams focused — one concern per diagram.
+### Flowchart (decision logic, pipelines)
+
+```mermaid
+flowchart TD
+  A[Receive Request] --> B{Authenticated?}
+  B -- Yes --> C[Process Request]
+  B -- No --> D[Return 401]
+  C --> E{Valid Input?}
+  E -- Yes --> F[Execute Action]
+  E -- No --> G[Return 400]
+```
+
+### Sequence Diagram (API flows, multi-service interactions)
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant API
+  participant DB
+  Client->>API: POST /resource
+  API->>DB: INSERT record
+  DB-->>API: OK
+  API-->>Client: 201 Created
+```
+
+### ER Diagram (data models, relationships)
+
+```mermaid
+erDiagram
+  USER ||--o{ ORDER : places
+  ORDER ||--|{ LINE_ITEM : contains
+  USER { string id PK; string email }
+  ORDER { string id PK; date created_at }
+```
+
+### Diagram Guidelines
+
+- Add a title comment (`%% Title: ...`) at the top of complex diagrams
+- Use verb labels on relationship arrows
+- Limit nodes to 10–12 per diagram; split larger systems into sub-diagrams
+- Prefer `flowchart TD` (top-down) for pipelines and `flowchart LR` (left-right) for request flows
+
+## Changelog Entry Template
+
+Follow Conventional Commits format. Group entries by type under a version heading:
+
+```markdown
+## [1.2.0] — YYYY-MM-DD
+
+### Added
+- feat: Add retry logic to API client (#123)
+
+### Fixed
+- fix: Resolve race condition in queue processor (#127)
+
+### Changed
+- refactor: Extract validation into shared module (#125)
+```
+
+### Changelog Rules
+
+- One line per change; reference the PR or issue number
+- Use imperative mood: "Add", "Fix", "Remove" — not "Added", "Fixed"
+- Group under `Added`, `Fixed`, `Changed`, `Removed`, `Deprecated`, `Security`
+- Most recent version at the top
+
 ## Writing Guidelines
 
 - Write clear, concise prose — avoid jargon unless necessary
-- Include diagrams (Mermaid or ASCII) for architecture
-- Link to related files and docs using relative paths
-- Keep line length under 400 characters; break at 80 for readability
-- Use tables for structured data
-- Include "Last Updated" dates on all documents
-- Archive outdated docs rather than deleting
-- Cross-reference between documents when relevant
+- Include Mermaid diagrams for architecture
+- Link to related files using relative paths
+- Use tables for structured data; include "Last Updated" dates on all documents
+- Archive outdated docs rather than deleting; cross-reference between documents
 
 ### Formatting Rules
 
@@ -85,3 +174,27 @@ Include YAML front matter at the beginning of instruction/skill files:
 - `title` / `name`: The title of the document
 - `description`: A brief description of the document content
 - `applyTo`: (for instruction files) Glob pattern for which files the instructions apply to
+
+## Documentation Review Checklist
+
+Before merging docs, verify:
+
+- [ ] **Accuracy** — all code snippets, file paths, and commands are correct and tested
+- [ ] **Completeness** — no TODO placeholders or empty sections remain
+- [ ] **Links** — all internal and external links resolve (no 404s)
+- [ ] **Front matter** — YAML front matter is present and valid
+- [ ] **Formatting** — consistent heading levels, list style, whitespace, and Mermaid renders
+- [ ] **Cross-references** — related docs link to each other; "Last Updated" is current
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Do This Instead |
+|-------------|-------------|-----------------|
+| Wall of text with no headings | Unnavigable; readers skip it | Break into sections with H2/H3 |
+| Duplicating content across files | Copies drift; causes confusion | Link to a single source of truth |
+| Screenshots without alt text | Inaccessible; breaks when UI changes | Use Mermaid diagrams or describe the UI |
+| Documenting implementation details | Becomes stale as code changes | Document intent and contracts |
+| Using absolute file paths | Breaks on other machines | Use relative paths from doc location |
+| Huge monolithic README | Low signal-to-noise | Split into focused docs, link from README |
+| Undated documents | No way to judge currency | Always include "Last Updated" date |
+| Using H1 inside document body | Conflicts with auto-generated title | Start body headings at H2 |

package/src/orchestrator/skills/frontend-design/SKILL.md

@@ -41,4 +41,155 @@ Interpret creatively and make unexpected choices that feel genuinely designed fo
 
 **IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
 
-Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+
+## Design System Foundations
+
+Every design starts with a token layer. Define CSS custom properties that encode the aesthetic direction — never scatter raw values through stylesheets. A well-structured variable system makes the entire interface feel cohesive even as complexity grows.
+
+```css
+/* --- Palette: warm editorial with a punch of citron --- */
+:root {
+  --color-ink:        #1a1614;
+  --color-paper:      #f5f0e8;
+  --color-accent:     #c8e630;        /* citron — the memorable detail */
+  --color-muted:      #9b9083;
+  --color-surface:    #eae3d8;
+  --color-border:     rgba(26, 22, 20, 0.08);
+
+  /* Typography scale — modular ratio 1.25 (Major Third) */
+  --text-sm:   clamp(0.875rem, 0.83rem + 0.22vw, 1rem);
+  --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
+  --text-xl:   clamp(1.563rem, 1.35rem + 1.06vw, 2rem);
+  --text-2xl:  clamp(1.953rem, 1.6rem + 1.77vw, 2.75rem);
+  --text-hero: clamp(2.441rem, 1.8rem + 3.2vw, 4.5rem);
+
+  /* Spacing — 4px base, geometric progression */
+  --space-2: 0.5rem;  --space-4: 1rem;
+  --space-6: 1.5rem;  --space-8: 2rem;
+  --space-16: 4rem;   --space-32: 8rem;
+
+  /* Motion — intentional easing curves, not defaults */
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in-out-back: cubic-bezier(0.68, -0.6, 0.32, 1.6);
+  --duration-fast: 150ms;
+  --duration-normal: 300ms;
+  --duration-slow: 600ms;
+
+  /* Elevation */
+  --shadow-md: 0 4px 16px rgba(26, 22, 20, 0.08);
+  --shadow-lg: 0 12px 48px rgba(26, 22, 20, 0.12);
+}
+```
+
+**Anti-pattern:** Never scatter raw hex/px values through stylesheets. Every value should trace back to a token. Change the palette once and the entire interface follows.
+
+## Component Patterns
+
+### Distinctive Card
+
+A card should never look like a Bootstrap default. Give it tension — an unexpected border treatment, an oversized label, or a hover that reveals hidden depth.
+
+```css
+.card {
+  position: relative;
+  background: var(--color-paper);
+  border: 1px solid var(--color-border);
+  border-left: 4px solid var(--color-accent);
+  padding: var(--space-8) var(--space-6);
+  transition: transform var(--duration-normal) var(--ease-out-expo),
+              box-shadow var(--duration-normal) var(--ease-out-expo);
+}
+
+.card:hover {
+  transform: translateY(-3px);
+  box-shadow: var(--shadow-lg);
+}
+
+.card__label {
+  position: absolute;
+  top: calc(-1 * var(--space-3));
+  left: var(--space-4);
+  background: var(--color-accent);
+  color: var(--color-ink);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  padding: var(--space-1) var(--space-3);
+}
+```
+
+### Hero Section with Staggered Reveal
+
+Orchestrate entrance animations with `animation-delay` for a cinematic first impression. One coordinated sequence beats a dozen scattered `fadeIn`s.
+
+```css
+@keyframes rise {
+  from { opacity: 0; transform: translateY(24px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.hero              { overflow: hidden; padding: var(--space-32) var(--space-8); }
+.hero__eyebrow     { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 100ms; }
+.hero__headline    { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 250ms; }
+.hero__body        { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 400ms; }
+.hero__cta         { animation: rise var(--duration-slow) var(--ease-out-expo) both; animation-delay: 550ms; }
+```
+
+**Anti-pattern:** Don't animate everything. If the nav bounces, the sidebar slides, and the footer pulses — it's visual noise, not design. Motion has a narrative: one orchestrated entrance, then stillness.
+
+## Typography Pairing Examples
+
+Never reach for the same font twice. Each project deserves a pairing chosen for its specific character. These are starting points — not a rotation list.
+
+| Aesthetic | Display | Body | Mood |
+|-----------|---------|------|------|
+| Editorial luxury | Playfair Display | Source Serif 4 | Authoritative, rich serif contrast |
+| Swiss precision | Darker Grotesque | IBM Plex Sans | Sharp, high-contrast grotesque |
+| Warm humanist | Fraunces | Nunito Sans | Friendly optical sizes, approachable |
+| Brutalist edge | Monument Extended | JetBrains Mono | Wide + monospace = raw technical power |
+| Art nouveau organic | Cormorant Garamond | Lora | Flowing, calligraphic sensibility |
+| Retro-futuristic | Syne | Outfit | Geometric boldness meets clean body |
+
+Always include a fallback chain that preserves metrics: `'Fraunces', 'Georgia', serif` not just `'Fraunces', serif`. And never default to the same "safe" choices (Inter, Roboto, system-ui) — if every project looks the same, the typography isn't doing its job.
+
+## Design Quality Checklist
+
+Run this checklist before delivering any frontend work. Every item is a gate — if something fails, the design isn't finished.
+
+### Identity & Cohesion
+- [ ] Can you name the aesthetic direction in 2-3 words? (e.g., "warm editorial," "cold brutalist")
+- [ ] Are color, typography, spacing, and motion all telling the same visual story?
+- [ ] Is there at least one memorable detail — something unexpected that delights?
+
+### Typography
+- [ ] Display and body fonts are distinct and intentionally paired
+- [ ] Type scale uses `clamp()` for fluid responsive sizing — no fixed `px` breakpoints
+- [ ] Line heights are tuned: ~1.1–1.2 for headings, ~1.5–1.7 for body
+- [ ] Letter-spacing is adjusted for uppercase text and small sizes
+
+### Color & Contrast
+- [ ] Palette is defined as CSS custom properties — no raw hex in component styles
+- [ ] There is a clear dominant/accent hierarchy — not five competing colors
+- [ ] Text passes WCAG AA contrast minimums (4.5:1 body, 3:1 large text)
+- [ ] Dark/light theme (if applicable) is not just color inversion — both feel intentional
+
+### Layout & Spacing
+- [ ] Spacing flows from a consistent scale — no random `margin: 37px`
+- [ ] At least one layout choice breaks the expected grid — overlap, bleed, asymmetry
+- [ ] Component padding and gaps use spacing tokens, not ad-hoc values
+- [ ] The design holds at mobile, tablet, and desktop without layout collapse
+
+### Motion & Interaction
+- [ ] Page entrance has a coordinated animation sequence (staggered reveals)
+- [ ] Hover/focus states exist for all interactive elements
+- [ ] Animations use custom easing curves — never `linear` or bare `ease`
+- [ ] Motion serves narrative purpose — no decoration-only animation
+- [ ] `prefers-reduced-motion` is respected with a `@media` query fallback
+
+### Production Readiness
+- [ ] No hardcoded widths that break at unexpected viewports
+- [ ] Images and decorative elements have proper `alt` text or `aria-hidden`
+- [ ] Focus indicators are visible and styled to match the aesthetic
+- [ ] Performance: no layout thrashing from scroll-triggered animations without `will-change`

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

@@ -9,11 +9,9 @@ description: "Next.js App Router best practices for server/client components, ro
 
 ## Project Structure
 
-- **Use `app/` directory** (App Router) for all routes.
+- **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/`.
-- Colocate files near where they're used.
-- **Route Groups**: parentheses `(admin)` — group without affecting URL.
-- **Private Folders**: underscore `_internal` — opt out of routing.
+- **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
@@ -22,39 +20,116 @@ description: "Next.js App Router best practices for server/client components, ro
 
 **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:**
-1. Move all client-only logic into a dedicated Client Component (`'use client'`).
-2. Import and use that Client Component directly in the Server Component.
+**Correct approach:** Move client-only logic into a dedicated `'use client'` component, then import it normally.
 
 ```tsx
-// Server Component
+// Server Component — imports a Client Component directly
 import DashboardNavbar from '@/components/DashboardNavbar';
-
 export default async function DashboardPage() {
-  return (
-    <>
-      <DashboardNavbar /> {/* Client Component */}
-    </>
-  );
+  return <><DashboardNavbar /></>;
 }
 ```
 
-## Component Practices
+## 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>;
+}
+```
 
-- PascalCase for files/exports. camelCase for hooks.
+## 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.
-
-## Naming Conventions
-
-- Folders: `kebab-case`.
-- Components: `PascalCase`. Hooks: `camelCase`. Assets: `kebab-case`.
-- Types/Interfaces: `PascalCase`. Constants: `UPPER_SNAKE_CASE`.
+- Folders: `kebab-case`. Types/Interfaces: `PascalCase`. Constants: `UPPER_SNAKE_CASE`.
 
 ## API Routes (Route Handlers)
 
@@ -65,13 +140,61 @@ export default async function DashboardPage() {
 - 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.
+- 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>` |

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

@@ -7,36 +7,194 @@ description: "Technical SEO patterns for meta tags, structured data, sitemaps, U
 
 # SEO Patterns
 
+## Core Principles
+
+- Every public page MUST have a unique `<title>` and `<meta name="description">`.
+- Structured data MUST validate against Google's Rich Results Test before shipping.
+- Server-render all content critical for indexing — never rely on client-side JS for primary content.
+- Canonical URLs are mandatory on every page to prevent duplicate content issues.
+
 ## Meta Tags & Open Graph
-- `<title>`, `<meta name="description">` for every page template
-- Open Graph tags (`og:title`, `og:description`, `og:image`, `og:type`)
-- Twitter Card tags (`twitter:card`, `twitter:title`, `twitter:image`)
-- Canonical URLs (`<link rel="canonical">`)
-- Robots directives (`noindex`, `nofollow` where appropriate)
+
+Every page template must include the full set of meta tags:
+
+```tsx
+// Next.js App Router — layout or page metadata
+export const metadata: Metadata = {
+  title: 'Product Name — Short Descriptor',
+  description: 'Concise 150-160 char description with primary keyword.',
+  alternates: { canonical: 'https://example.com/page-slug' },
+  openGraph: {
+    title: 'Product Name — Short Descriptor',
+    description: 'Concise description for social sharing.',
+    url: 'https://example.com/page-slug',
+    type: 'website',
+    images: [{ url: 'https://example.com/og-image.jpg', width: 1200, height: 630 }],
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: 'Product Name — Short Descriptor',
+    images: ['https://example.com/og-image.jpg'],
+  },
+  robots: { index: true, follow: true },
+};
+```
+
+### Meta Tag Checklist
+
+- [ ] `<title>` is unique, 50-60 chars, includes primary keyword
+- [ ] `<meta name="description">` is unique, 150-160 chars, includes CTA
+- [ ] `<link rel="canonical">` points to the single authoritative URL
+- [ ] `og:title`, `og:description`, `og:image` (1200×630 px min), `og:type` are set
+- [ ] `twitter:card`, `twitter:title`, `twitter:image` are set
+- [ ] `robots` directives are correct (`noindex` on admin/draft pages only)
 
 ## Structured Data (JSON-LD)
-- **LocalBusiness** / **Restaurant** / **CafeOrCoffeeShop** for venue pages
-- **BreadcrumbList** for navigation hierarchy
-- **WebSite** with **SearchAction** for sitelinks search box
-- **ItemList** for venue listing pages
-- **Organization** for the site entity
-- Validate against schema.org and Google's requirements
+
+Use JSON-LD `<script>` blocks — never microdata or RDFa. Choose schema types based on page purpose:
+
+| Page Type | Schema Type(s) | Required Properties |
+|-----------|----------------|---------------------|
+| Homepage | `WebSite`, `Organization` | `name`, `url`, `searchAction`, `logo` |
+| Detail page | `Product`, `Article`, or domain-specific type | `name`, `description`, `image` |
+| Listing / category page | `ItemList` + `ListItem` | `itemListElement`, `position`, `url` |
+| Breadcrumb navigation | `BreadcrumbList` | `itemListElement`, `position`, `name` |
+| Blog post | `Article` or `BlogPosting` | `headline`, `datePublished`, `author` |
+| FAQ page | `FAQPage` | `mainEntity` with `Question` + `Answer` |
+
+### Example: Breadcrumb + Article
+
+```tsx
+function StructuredData({ breadcrumbs, article }: Props) {
+  const breadcrumbLd = {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: breadcrumbs.map((crumb, i) => ({
+      '@type': 'ListItem',
+      position: i + 1,
+      name: crumb.label,
+      item: crumb.url,
+    })),
+  };
+
+  const articleLd = {
+    '@context': 'https://schema.org',
+    '@type': 'Article',
+    headline: article.title,
+    description: article.summary,
+    image: article.imageUrl,
+    datePublished: article.publishedAt,
+    dateModified: article.updatedAt,
+    author: { '@type': 'Person', name: article.author },
+  };
+
+  return (
+    <>
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(breadcrumbLd) }} />
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(articleLd) }} />
+    </>
+  );
+}
+```
+
+### Validation
+
+- Run every JSON-LD block through [Google's Rich Results Test](https://search.google.com/test/rich-results) before merging.
+- Validate against [schema.org](https://schema.org) definitions for required/recommended properties.
+- Check the Search Console **Enhancements** report after deployment.
 
 ## Sitemap & Crawlability
-- Dynamic XML sitemap generation for all venue pages
-- Sitemap index for large venue counts (705+ and growing)
-- `robots.txt` configuration
-- Internal linking structure
-- Page speed impact on crawl budget
+
+- Generate an XML sitemap dynamically from your data source (CMS, database, filesystem).
+- Use a **sitemap index** when page count exceeds 50,000 URLs or file size exceeds 50 MB.
+- Include `<lastmod>` timestamps — omit if you can't guarantee accuracy.
+- Submit sitemaps via Google Search Console and reference them in `robots.txt`.
+
+### Example: robots.txt
+
+```txt
+User-agent: *
+Allow: /
+Disallow: /admin/
+Disallow: /api/
+Disallow: /preview/
+
+Sitemap: https://example.com/sitemap.xml
+```
+
+### Crawlability Checklist
+
+- [ ] `robots.txt` allows crawling of all public pages
+- [ ] `robots.txt` blocks admin, API, and preview routes
+- [ ] XML sitemap is auto-generated and up to date
+- [ ] Sitemap is referenced in `robots.txt`
+- [ ] Internal links connect all public pages (no orphan pages)
+- [ ] Page load time < 3s (crawl budget efficiency)
 
 ## URL Strategy
-- Clean, keyword-relevant slugs for venue pages
-- Consistent URL patterns across venue categories
-- Redirect handling for renamed/moved venues (301 redirects)
-- Trailing slash consistency
+
+- Use lowercase, hyphen-separated slugs: `/blog/my-post-title`
+- Keep URLs short, keyword-relevant, and human-readable.
+- Enforce trailing-slash consistency (pick one, redirect the other).
+- Implement 301 redirects for any renamed or moved pages.
+
+| Pattern | Good | Bad |
+|---------|------|-----|
+| Slug format | `/products/blue-widget` | `/products/Blue_Widget` |
+| Hierarchy | `/blog/2026/seo-tips` | `/blog?id=42` |
+| Consistency | Always `/path/` or `/path` | Mixed trailing slashes |
+| Parameters | `/products?sort=price` | `/products/sort/price/asc` |
+
+### Redirect Example (Next.js)
+
+```ts
+// next.config.ts
+const nextConfig = {
+  async redirects() {
+    return [
+      { source: '/old-page', destination: '/new-page', permanent: true },
+      { source: '/blog/:slug/amp', destination: '/blog/:slug', permanent: true },
+    ];
+  },
+};
+```
 
 ## Rendering & Indexability
-- Ensure critical content is server-rendered (not client-only)
-- Verify pages are indexable with `fetch as Googlebot`
-- Check hydration doesn't break structured data
-- Image optimization for search (alt text, file names, lazy loading below fold)
+
+- **Server-render** all content that must be indexed — titles, descriptions, body text, structured data.
+- **Client-hydrated** interactive elements (filters, modals) are fine, but content behind JS-only rendering will not be indexed reliably.
+- Use semantic HTML (`<h1>`–`<h6>`, `<article>`, `<nav>`, `<main>`) for crawlers to understand page structure.
+
+### Image SEO
+
+| Attribute | Purpose | Example |
+|-----------|---------|---------|
+| `alt` | Describes image for screen readers + crawlers | `alt="Blue widget on white background"` |
+| `loading` | Lazy-load below-fold images | `loading="lazy"` |
+| `width` / `height` | Prevents layout shift (CLS) | `width={800} height={600}` |
+| File name | Keyword signal | `blue-widget-front.webp` |
+| Format | Performance + quality | Use WebP/AVIF with JPEG fallback |
+
+### Indexability Checklist
+
+- [ ] Primary content renders in initial HTML (view source, not inspect)
+- [ ] `<h1>` is unique per page and contains the primary keyword
+- [ ] Structured data is present in the server-rendered HTML
+- [ ] Images have descriptive `alt` text
+- [ ] No `noindex` on pages that should be indexed
+- [ ] Hydration does not remove or rewrite structured data scripts
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Correct Approach |
+|---|---|---|
+| Duplicate `<title>` across pages | Dilutes ranking signals; confuses crawlers | Unique, keyword-specific title per page |
+| Missing canonical URL | Causes duplicate content penalties | Add `<link rel="canonical">` to every page |
+| Client-only rendered content | Googlebot may not execute JS reliably | Server-render all indexable content |
+| Hardcoded sitemap file | Goes stale as pages are added/removed | Generate sitemap dynamically from data source |
+| Using `noindex` as a "temporary" fix | Often forgotten; pages stay de-indexed | Fix the underlying issue instead |
+| Stuffing keywords in meta tags | Penalized by search engines | Write natural, user-focused descriptions |
+| Missing `alt` text on images | Lost image search traffic + accessibility failure | Descriptive alt text on every meaningful image |
+| Structured data without validation | Silent errors cause rich result loss | Validate with Google Rich Results Test before merge |
+| Blocking CSS/JS in `robots.txt` | Prevents Googlebot from rendering the page | Only block admin/API routes |
+| Mixed trailing slash URLs | Splits link equity between two URLs | Pick one convention, 301-redirect the other |