opencastle 0.32.12 → 0.33.0

package/src/dashboard/public/data/convoys/demo-perf-opt.json

@@ -42,28 +42,28 @@
       "name": "reports/bundle-analysis.json",
       "type": "json",
       "task_id": "perf-t1",
-      "created_at": "2026-03-20T09:16:41.375Z"
+      "created_at": "2026-04-04T06:06:04.354Z"
     },
     {
       "id": "artifact-demo-perf-opt-reports-web-vitals-improvement-md",
       "name": "reports/web-vitals-improvement.md",
       "type": "summary",
       "task_id": "perf-t4",
-      "created_at": "2026-03-20T09:16:41.375Z"
+      "created_at": "2026-04-04T06:06:04.354Z"
     },
     {
       "id": "artifact-demo-perf-opt-src-charts-index-ts",
       "name": "src/charts/index.ts",
       "type": "file",
       "task_id": "perf-t2",
-      "created_at": "2026-03-20T09:16:41.375Z"
+      "created_at": "2026-04-04T06:06:04.354Z"
     },
     {
       "id": "artifact-demo-perf-opt-src-utils-image-loader-ts",
       "name": "src/utils/image-loader.ts",
       "type": "file",
       "task_id": "perf-t3",
-      "created_at": "2026-03-20T09:16:41.375Z"
+      "created_at": "2026-04-04T06:06:04.354Z"
     }
   ],
   "has_more_events": false,

package/src/orchestrator/customizations/stack/sanity-config.md

@@ -0,0 +1,43 @@
+# Sanity CMS Configuration
+
+<!-- Populated by `opencastle init` based on detected Sanity project. -->
+
+Project-specific Sanity CMS details referenced by the `sanity-cms` skill.
+
+## Configuration
+
+<!-- Sanity project ID, dataset, API version, studio location. -->
+
+| Setting | Value |
+|---------|-------|
+| Project ID | |
+| Dataset | |
+| API Version | |
+| Studio Path | |
+
+## Plugins
+
+<!-- List Sanity plugins and their purpose. -->
+
+## Document Types
+
+<!-- List document types with key fields. -->
+
+| Document Type | Key Fields | Description |
+|--------------|------------|-------------|
+| | | |
+
+## GROQ Examples
+
+<!-- Provide representative GROQ query examples. -->
+
+```groq
+// Example: fetch all published documents of a type
+*[_type == "page" && !(_id in path("drafts.**"))]{
+  _id, title, slug
+}
+```
+
+## Key Files
+
+<!-- List key schema, config, and query files. -->

package/src/orchestrator/customizations/stack/supabase-config.md

@@ -0,0 +1,53 @@
+# Supabase Configuration
+
+<!-- Populated by `opencastle init` based on detected Supabase project. -->
+
+Project-specific Supabase details referenced by the `supabase-database` skill.
+
+## Configuration
+
+<!-- Supabase project URL, anon key location, service role key location. -->
+
+| Setting | Value |
+|---------|-------|
+| Project URL | |
+| Anon Key Env | `NEXT_PUBLIC_SUPABASE_URL` |
+| Service Role Env | `SUPABASE_SERVICE_ROLE_KEY` |
+
+## Database Schema
+
+### Core Tables
+
+<!-- List tables with their purpose and RLS status. -->
+
+| Table | Purpose | RLS |
+|-------|---------|-----|
+| | | |
+
+### Role System
+
+<!-- Describe roles and their permissions. -->
+
+| Role | Permissions |
+|------|------------|
+| | |
+
+## Auth Flow
+
+<!-- Authentication pattern: email/password, OAuth providers, session management. -->
+
+## Migration History
+
+<!-- List applied migrations in order. -->
+
+| Migration | Date | Description |
+|-----------|------|-------------|
+| | | |
+
+## RLS Policies
+
+<!-- Document key RLS policies and their purpose. -->
+
+## Key Files
+
+<!-- List key config, migration, and type files. -->

package/src/orchestrator/plugins/astro/REFERENCE.md

@@ -0,0 +1,5 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Astro REFERENCE: SSR config examples, anti-patterns expanded, and content collection validation scripts.
+
+Long-form examples and migration steps live here; `SKILL.md` keeps quick workflows and recommendations.

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

@@ -1,6 +1,6 @@
 ---
 name: astro-framework
-description: "Astro framework best practices for content-driven sites, islands architecture, routing, integrations, and project structure. Use when creating or modifying Astro pages, layouts, components, or content collections."
+description: "Creates pages/layouts, defines content collections, configures hydration directives, and wires integrations. Use when adding or modifying Astro pages, layouts, components, or content collections. Trigger terms: Astro, content collection, client:load, client:visible, astro:content"
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
@@ -21,23 +21,22 @@ src/
 └── assets/      # processed images
 ```
 
-## Component Model
+## Implement Components
 
-**Default: Zero JS** — `.astro` components render to HTML with no client-side JavaScript.
+**Default: Zero JS** — author `.astro` components that render HTML with no client-side JavaScript where possible.
 
-**Islands Architecture** — Interactive components use `client:*` directives to hydrate only where needed.
+**Islands Architecture** — hydrate interactivity only where needed using `client:*` directives.
 
-### Astro Component Example
+### Component Example (concise)
 
 ```astro
 ---
 interface Props { title: string; description?: string; }
 const { title, description = 'Default description' } = Astro.props;
-const data = await fetch('https://api.example.com/data').then(r => r.json());
 ---
 <section>
   <h2>{title}</h2>
-  {data.items.map((item: { name: string }) => <li>{item.name}</li>)}
+  <p>{description}</p>
 </section>
 <style>
   section { max-width: 800px; margin: 0 auto; }
@@ -46,18 +45,22 @@ const data = await fetch('https://api.example.com/data').then(r => r.json());
 
 ### Client Directives (Islands)
 
-| Directive | When It Hydrates | Use Case |
-|-----------|-----------------|----------|
-| `client:load` | Immediately on page load | Critical interactive UI |
-| `client:idle` | After page is idle | Non-critical UI (analytics widgets) |
-| `client:visible` | When element enters viewport | Below-the-fold components |
-| `client:media="(max-width: 768px)"` | When media query matches | Mobile-only interactivity |
-| `client:only="react"` | Client-only, no SSR | Components that can't server-render |
+Use only the hydration directive required by the interaction to minimize shipped JS. Typical mappings:
 
-## Content Collections
+- `client:load` — immediate hydration for critical interactive widgets
+- `client:idle` — non-critical behavior after page idle
+- `client:visible` — hydrate when visible (lazy)
+- `client:media` — hydrate on media match
+- `client:only` — last resort for non-SSR-able components
 
-Define in `src/content.config.ts` (Astro v5+) using the Content Layer API:
+## Content Collections — Quick Workflow: add a new collection
+1. Add collection schema in `src/content.config.ts` using `defineCollection` and Zod validators.
+2. Create the folder under `src/content/<collection>` and add one sample `.md` or `.mdx` content file with frontmatter.
+3. Run `pnpm build` and `pnpm dev` → run `node scripts/validate-content.js` (or your project's validation script) to verify typed collection imports.
+4. Add a smoke query in a page that imports the collection (e.g., `const posts = await getCollection('blog')`) and confirm build-time typing.
+5. Validation: ensure `pnpm build` exits zero and TypeScript reports no errors for collection types.
 
+Define collections in `src/content.config.ts` (Astro v5+) using `astro:content` and export typed collections.
 ```ts
 import { defineCollection, z } from 'astro:content';
 import { glob } from 'astro/loaders';
@@ -117,16 +120,6 @@ Use `astro add` for react, tailwind, mdx, sitemap, node, vercel, netlify, cloudf
 - **API routes**: Export `GET`/`POST` handlers from `src/pages/api/*.ts` returning `new Response(...)`.
 - **Actions**: Use `defineAction` in `src/actions/index.ts` for type-safe server mutations with Zod validation.
 
-## Anti-Patterns
-
-| Anti-Pattern | Why It's Wrong | Do This Instead |
-|-------------|---------------|-----------------|
-| `client:load` on every component | Defeats zero-JS benefit, bloats bundle | Use `client:idle` or `client:visible` for non-critical UI |
-| Importing large JS libraries in `.astro` | Runs at build but bundles nothing useful | Import in framework components with `client:*` |
-| Skipping content collections for blog/docs | Manual file handling is error-prone | Use content collections with typed schemas |
-| Hardcoding data in pages | Not maintainable, no type safety | Use content collections or fetch from APIs |
-| Using `client:only` when SSR works | Loses SEO benefits and fast first paint | Use `client:load` or `client:visible` instead |
-| Giant monolithic pages | Hard to maintain and test | Split into layouts + reusable components |
-| Ignoring `astro add` for integrations | Manual config is error-prone | Use `astro add` for official integrations |
-| Missing `alt` on images | Accessibility violation | Always provide descriptive `alt` text |
-| Not using `astro:assets` for images | Missing optimization | Use `<Image>` from `astro:assets` |
+## Anti-Patterns (moved to REFERENCE.md)
+
+Extracted anti-patterns and SSR configuration details are available in `REFERENCE.md` in this directory to keep this skill focused and concise.

package/src/orchestrator/plugins/chrome-devtools/REFERENCE.md

@@ -0,0 +1,9 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: Chrome DevTools MCP commands and responsive checklist
+
+- Full MCP command table with parameter examples and common payload shapes
+- Responsive verification scripts and `evaluate_script()` snippets
+- Performance trace capture and analysis commands

package/src/orchestrator/plugins/chrome-devtools/SKILL.md

@@ -1,27 +1,14 @@
 ---
 name: browser-testing
-description: "Chrome DevTools MCP automation patterns for validating UI changes in real browsers. Use when performing E2E browser testing, validating visual changes, testing user interactions, or debugging UI issues with Chrome DevTools."
+description: "Drive real browsers via Chrome DevTools MCP: navigate pages, capture snapshots, run responsive checks, and collect console/perf traces. Use when the user mentions: 'validate UI change in Chrome', 'capture a screenshot', 'run responsive checks', or 'collect console logs'. Trigger terms: browser testing, DevTools, console logs, screenshot, responsive testing"
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
 
 # Browser Testing with Chrome DevTools MCP
 
-Generic browser testing methodology using Chrome DevTools MCP. For project-specific test app, selectors, suites, and breakpoint config, see [testing-config.md](../../.opencastle/stack/testing-config.md).
+For project-specific test app, selectors, suites, and breakpoint config, see [testing-config.md](../../.opencastle/stack/testing-config.md).
 
-## Purpose
-
-After any UI change, validate in a real browser:
-1. Start dev server if not running.
-2. Navigate to affected pages.
-3. Interact with UI elements (click, fill, filter).
-4. Validate behavior and appearance.
-5. Test edge cases (empty states, errors, boundaries).
-6. Document findings with screenshots and pass/fail.
-
-## Pre-Test Build Verification
-
-**CRITICAL: Always build before browser testing.** Testing stale code wastes time. See [testing-config.md](../../.opencastle/stack/testing-config.md) for the specific build and serve commands.
 
 ## Chrome MCP Tools Reference
 
@@ -85,30 +72,27 @@ mcp_chrome-devtoo_performance_analyze_insight({ insightSetId: 'set_id', insightN
 
 ### 1. Setup
 
-Start the dev server (see [testing-config.md](../../.opencastle/stack/testing-config.md) for app and port).
+Start the dev server.
 
 ### 2. Initial State
 
 ```javascript
 mcp_chrome-devtoo_navigate_page({ type: 'url', url: 'http://localhost:<port>/places' })
 mcp_chrome-devtoo_wait_for({ text: 'places' })
+// If wait_for times out: verify dev server is running and URL is correct
 mcp_chrome-devtoo_evaluate_script({
   function: '() => ({ url: window.location.href, title: document.title })'
 })
 ```
 
-### 3. Test Interactions
+### 3–4. Test Interactions & Edge Cases
 
 ```javascript
 mcp_chrome-devtoo_click({ uid: 'filter_uid' })
 mcp_chrome-devtoo_evaluate_script({
   function: '() => document.querySelectorAll(".place-card").length'
 })
-```
-
-### 4. Test Edge Cases
 
-```javascript
 mcp_chrome-devtoo_navigate_page({
   type: 'url', url: 'http://localhost:<port>/places?q=nonexistent-venue-xyz'
 })
@@ -121,11 +105,12 @@ mcp_chrome-devtoo_evaluate_script({
 
 ```javascript
 mcp_chrome-devtoo_list_console_messages()
+// If errors found: fix source, rebuild, reload page, and re-run from step 2
 ```
 
-### 6. Responsive Breakpoint Testing (MANDATORY)
+### 6. Responsive Breakpoint Testing
 
-**Every UI change MUST be tested at all responsive breakpoints.** Do not test at desktop only — most layout bugs surface at smaller viewports. Define your breakpoints in your project's testing config (e.g., `testing-config.md`).
+Test every UI change at all responsive breakpoints — most layout bugs surface at smaller viewports. Define breakpoints in your project's testing config.
 
 #### How to Resize
 
@@ -138,24 +123,8 @@ mcp_chrome-devtoo_resize_page({ width: 1440, height: 900 })  // Desktop
 
 #### Per-Breakpoint Verification
 
-#### Per-Breakpoint Verification
-
-At **each** breakpoint, check:
-
-- [ ] Layout adapts correctly — no horizontal overflow
-- [ ] Text truncates or wraps cleanly — no overlap
-- [ ] Interactive elements have adequate spacing and touch targets
-- [ ] Navigation and panels collapse/expand as expected
-- [ ] Images and cards resize proportionally
-
-#### Responsive Testing Anti-Patterns
-
-| Anti-Pattern | Correct Approach |
-|---|---|
-| Testing only at desktop width | Test at all project-defined breakpoints |
-| Skipping resize because "it uses Tailwind" | Tailwind classes can be wrong — always verify visually |
-| Only checking layout, not interactions | Test filter drawers, dropdowns, and modals at each size |
-| Taking 3 screenshots (one per breakpoint) | Use `evaluate_script()` to check layout; save screenshots for failures |
+- Verify interactions at each size (not layout only)
+- Prefer `evaluate_script()` assertions over screenshots; reserve screenshots for failures
 
 ## Regression Re-Test Workflow
 
@@ -169,20 +138,6 @@ When re-testing after a fix:
 
 If any test still fails: analyze, fix, repeat. Do NOT stop.
 
-## Validation Checklist
-
-- [ ] Page loads without errors (check console)
-- [ ] Changed component renders correctly
-- [ ] Interactive elements respond to clicks/input
-- [ ] Filters/sorting produce correct results
-- [ ] URL parameters sync with UI state
-- [ ] Empty states display when appropriate
-- [ ] Error states handle gracefully
-- [ ] Loading states appear during async operations
-- [ ] Keyboard navigation works, focus is visible
-- [ ] **Responsive: Tested at Mobile, Tablet, and Desktop breakpoints**
-- [ ] **Responsive: No horizontal overflow at any breakpoint**
-- [ ] **Responsive: Interactions work at every breakpoint (drawers, dropdowns, modals)**
 
 ## Context Management
 

package/src/orchestrator/plugins/contentful/REFERENCE.md

@@ -0,0 +1,16 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Contentful Reference (REFERENCE.md)
+
+Last Updated: 2026-03-31
+
+## Migration & Rollback Patterns
+
+- Best safe rollback: perform migrations in a sandbox environment and validate before promoting to `master`. If a migration is faulty, delete the sandbox and recreate it from `master` then re-run a corrected migration.
+- Advanced rollback: write reverse migrations that undo schema changes (when feasible) and test them in sandbox.
+
+## Validation Checklist
+
+1. Query a representative sample of entries after migration and confirm required fields and unique constraints.
+2. Run the site's build against sandbox content to catch runtime rendering issues.
+3. Run integration tests that depend on the modified content types.

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

@@ -1,45 +1,85 @@
 ---
 name: contentful-cms
-description: "Contentful CMS development patterns, GraphQL/REST API usage, content modeling, and migration best practices. Use when working with Contentful content types, entries, assets, or the Management API."
+description: "Creates Contentful content types, queries entries via GraphQL/REST, runs CLI migrations, and manages assets and locales. Use when building or modifying Contentful content models, writing queries, or migrating content."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Contentful CMS
 
-Generic Contentful CMS development methodology. For project-specific configuration, content types, and API keys, see [cms-config.md](../../.opencastle/stack/cms-config.md).
-
-## Critical Development Rules
-
-1. **Always use Content Types** — define structured content types before creating entries
-2. **Prefer GraphQL API** — use the GraphQL Content API for typed, efficient queries
-3. **Handle localization** — Contentful fields can be localized; always specify locale in queries
-4. **Use environments** — develop in sandbox environments, promote to master via migrations
-5. **Migration scripts** — use the Contentful CLI migration tool for schema changes, never modify content types manually in production
-6. **Rich Text rendering** — use `@contentful/rich-text-react-renderer` for React apps
-7. **Asset handling** — use Contentful's Image API for responsive images with transformations
-8. **Webhook-driven** — use webhooks for cache invalidation and rebuild triggers
-9. **Rate limiting** — respect API rate limits (Content Delivery: 78 req/s, Management: 10 req/s)
-10. **Keep queries in shared library** — queries belong in a shared queries library, never inline in components
+For project-specific configuration, content types, and API keys, see [cms-config.md](../../.opencastle/stack/cms-config.md).
 
 ## Query Patterns
 
 ### GraphQL Content API
-- Use typed GraphQL queries with code generation
 - Leverage `sys.publishedAt` for cache invalidation
 - Use `include` parameter to control link resolution depth
-- Filter with `where` clauses for efficient data fetching
 
-### REST Content Delivery API
-- Use `content_type` parameter to filter by type
-- Use `select` to limit returned fields
-- Use `links_to_entry` for reverse lookups
-- Handle pagination with `skip` and `limit`
+```typescript
+// Example: Typed GraphQL query
+const BLOG_POSTS_QUERY = `
+  query BlogPosts($limit: Int!, $locale: String!) {
+    blogPostCollection(limit: $limit, locale: $locale) {
+      items {
+        sys { id publishedAt }
+        title
+        slug
+        body { json }
+        featuredImage { url width height }
+      }
+    }
+  }
+`;
+```
 
 ## Content Modeling
 
-- Use **references** for relationships between content types
-- Prefer **short text** over **long text** for searchable fields
-- Use **JSON fields** sparingly — prefer structured content types
-- Design for **reusability** — create component content types for shared UI patterns
-- Use **validation rules** on fields to enforce data quality
+```javascript
+// Reference field with validation
+blogPost.createField('author')
+  .type('Link').linkType('Entry')
+  .validations([{ linkContentType: ['person'] }]);
+```
+
+Prefer typed content types over JSON fields; add validation rules to all required fields.
+
+## Migration Workflow
+
+1. Create a sandbox environment using the Contentful web UI or API.
+2. Write a migration script using the Contentful migration library (example below).
+3. Run the migration against the sandbox:
+
+```bash
+contentful space migration --space-id <SPACE_ID> --environment-id sandbox migration.js
+```
+
+4. Validate changes:
+  - Run a small validation script that queries a sample of affected entries and ensures required fields exist.
+   - If validation fails: roll back by deleting the sandbox and recreate from `master` (safe rollback), or write a reverse migration and run it.
+5. When sandbox validation passes, promote the environment or run the migration against `master` during a maintenance window.
+
+```javascript
+// Example: Migration script (migration.js)
+module.exports = function (migration) {
+  const blogPost = migration.createContentType('blogPost')
+    .name('Blog Post')
+    .displayField('title');
+  blogPost.createField('title').type('Symbol').required(true);
+  blogPost.createField('slug').type('Symbol').required(true).validations([{ unique: true }]);
+  blogPost.createField('body').type('RichText');
+};
+```
+
+Validation script example (node):
+
+```js
+// validate.js — exits non-zero on missing fields
+const res = await fetch(`https://cdn.contentful.com/spaces/${SPACE}/environments/sandbox/entries?content_type=blogPost`, {
+  headers: { Authorization: `Bearer ${TOKEN}` },
+});
+const { items } = await res.json();
+for (const item of items) {
+  if (!item.fields.slug) throw new Error(`Missing slug on ${item.sys.id}`);
+}
+console.log('OK —', items.length, 'entries validated');
+```
+
+For longer migration patterns and rollback options see [REFERENCE.md](REFERENCE.md).

package/src/orchestrator/plugins/convex/REFERENCE.md

@@ -0,0 +1,9 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: Convex patterns and safety checks
+
+- Schema migration checklist and `npx convex deploy` notes
+- Query/mutation examples with `returns` validators
+- Backup/rollback using `npx convex export` / `npx convex import`

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

@@ -7,7 +7,7 @@ description: "Convex reactive database patterns, schema design, real-time querie
 
 # Convex Database
 
-Generic Convex development methodology. For project-specific schema, functions, and deployment details, see [database-config.md](../../.opencastle/stack/database-config.md).
+For project-specific schema, functions, and deployment details, see [database-config.md](../../.opencastle/stack/database-config.md).
 
 ## Critical Development Rules
 
@@ -106,3 +106,15 @@ export const create = mutation({
 - Use `npx convex dev` for local development with hot reload
 - Schema changes are automatically migrated
 - Use `npx convex import` / `npx convex export` for data management
+
+## Quick Workflow: Implement a schema change and deploy
+1. Add or modify schema in `convex/schema.ts` and run `npx convex dev` locally; confirm the dev server starts and responds (checkpoint: `http://localhost:8888` or the configured port). Run a small validation script or sample queries to verify schema changes (validation checkpoint).
+2. Write queries/mutations with `returns` validators and unit test against the dev server.
+3. Run `npx convex deploy` to push the change to production.
+4. Verify real-time queries in the app, run a small data migration if required (`convex import/export`), and run a quick smoke check against your app (example):
+
+```bash
+curl -fsS https://<APP_URL>/health || (echo "health check failed" && exit 1)
+```
+
+If an issue occurs: roll back via `npx convex import` of the last good export, fix locally, and re-deploy. After a rollback, re-run the same smoke check to confirm services are restored.

package/src/orchestrator/plugins/cypress/REFERENCE.md

@@ -0,0 +1,5 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Cypress REFERENCE: CI snippets, extended `cypress.config.ts` examples, and selector strategies.
+
+Use this file for large examples referenced from `SKILL.md` to keep the skill concise.