contextos-agents 1.5.0

package/.agents/generated/claude/skills/ui-ux-pro/SKILL.md

@@ -0,0 +1,451 @@
+# ui-ux-pro
+
+## Overview
+
+Professional UI/UX design standard banning AI clichés (pure black #000000, purple-blue gradients, card-in-card nesting). Enforces Tailwind CSS v4 @theme, semantic HSL palettes, and refined micro-interactions.
+
+## When to Use
+
+Activate during planning and implementation of modern web user interfaces, landing pages, SaaS dashboards, and consumer-facing web apps.
+
+## Rules & Patterns
+
+Inspired by [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill).
+
+## Core Principle
+
+> Great design is invisible. Bad design is obvious. You will never produce obvious AI design.
+
+## Pre-flight Check & Brief Inference
+
+Before starting a design implementation:
+
+1. Infer the unwritten constraints of the domain (e.g., if it's a dev tool, assume dark mode, monospaced numbers, dense layout).
+2. Propose a "Design Brief Inference" summarizing the intended aesthetic.
+
+---
+
+## [FAIL] Absolute Prohibitions (Never Do These)
+
+### Typography Anti-Patterns
+
+- **NEVER** use Arial, Helvetica, or system-ui defaults as primary fonts
+- **NEVER** use Inter as the ONLY font — it is the #1 "AI-generated" visual tell when used alone
+  - [PASS] **CORRECT**: If using Inter for primary UI text, ALWAYS pair it with a strong monospace font like `JetBrains Mono` for numbers, code blocks, and technical accents to create a premium SaaS aesthetic (see Vercel, Linear)
+  - [FAIL] **WRONG**: Inter for headings, body, labels, numbers, captions — everything
+- **NEVER** mix more than 2 font families
+- **ALWAYS** import proper fonts from Google Fonts or similar
+
+### Color Anti-Patterns
+
+- **NEVER** use pure black `#000000` — always tint toward brand hue (e.g. `#0A0A0F`)
+- **NEVER** use pure gray `#808080` — tint it (e.g. `#6B7280` has blue undertones)
+- **NEVER** use purple-to-blue gradients — it is the #1 "AI generated" visual tell
+- **NEVER** use neon colors for primary UI (only accents, sparingly)
+- **ALWAYS** use HSL-based semantic palettes with clear naming
+
+### Layout Anti-Patterns
+
+- **NEVER** nest cards inside cards (card-in-card = instant slop flag)
+- **NEVER** put a rounded-square icon tile above every heading
+- **NEVER** center-align long paragraphs (> 2 lines)
+- **NEVER** use gray text on colored backgrounds (contrast failure)
+
+### Animation Anti-Patterns
+
+- **NEVER** use bounce or elastic easing in raw CSS — it feels dated (circa 2014)
+- **NEVER** add animations just to show they work
+- **ALWAYS** use `ease-out` for enter, `ease-in` for exit, `ease-in-out` for continuous
+
+---
+
+## [PASS] Required Standards
+
+### Accessibility Checklist
+
+Before shipping any UI, verify:
+
+- [ ] Text contrast ratio ≥ 4.5:1 for normal text (WCAG AA)
+- [ ] Text contrast ratio ≥ 3:1 for large text (≥ 18px bold or ≥ 24px)
+- [ ] All interactive elements have `aria-label` or visible text
+- [ ] Touch targets are minimum 44×44px (48×48px recommended)
+- [ ] Focus states are visible and styled (not just browser default)
+- [ ] Images have meaningful `alt` text (or `alt=""` if decorative)
+- [ ] Form fields have associated `<label>` elements
+- [ ] Keyboard navigation works without mouse
+- [ ] No color alone conveys information (use icons + text too)
+
+### Semantic Color Palette — shadcn/ui & Tailwind CSS v4 Format
+
+Generate palettes in the format compatible with shadcn/ui's `globals.css`. Always support both light and dark themes as this is the de-facto standard:
+
+```css
+@layer base {
+  :root {
+    --background: 220 13% 98%;
+    --foreground: 220 13% 9%;
+    --card: 220 13% 100%;
+    --card-foreground: 220 13% 9%;
+    --muted: 220 13% 95%;
+    --muted-foreground: 220 9% 46%;
+    --border: 220 13% 90%;
+    --input: 220 13% 90%;
+    --primary: 258 90% 56%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 220 13% 94%;
+    --secondary-foreground: 220 13% 9%;
+    --accent: 258 90% 56%;
+    --accent-foreground: 0 0% 100%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    --ring: 258 90% 56%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 220 13% 9%;
+    --foreground: 210 40% 98%;
+    --card: 220 11% 13%;
+    --card-foreground: 210 40% 98%;
+    --muted: 220 11% 16%;
+    --muted-foreground: 215 16% 65%;
+    --border: 217 19% 22%;
+    --input: 217 19% 22%;
+    --primary: 258 90% 66%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 220 11% 18%;
+    --secondary-foreground: 210 40% 98%;
+    --accent: 258 90% 66%;
+    --accent-foreground: 0 0% 100%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    --ring: 258 90% 66%;
+  }
+}
+```
+
+> **Rule**: NEVER define colors as raw hex/rgb. ALWAYS use HSL space values so Tailwind opacity modifiers (`text-primary/80`) work correctly.
+
+### Spacing System (Tailwind)
+
+Use Tailwind spacing utilities. **Never use arbitrary values** like `gap-[17px]`:
+
+- `gap-1` / `p-1` — 4px micro gaps
+- `gap-2` / `p-2` — 8px component internal
+- `gap-4` / `p-4` — 16px standard padding
+- `gap-6` / `p-6` — 24px section gaps
+- `gap-8` / `p-8` — 32px block separators
+- `gap-12` / `py-12` — 48px section separators
+- `gap-20` / `py-20` — 80px hero spacing
+
+### Typography Scale
+
+Use a modular type scale (1.25 or 1.333 ratio):
+
+```
+xs:  11px / 0.688rem  (text-xs)
+sm:  13px / 0.813rem  (text-sm)
+base: 16px / 1rem     (text-base)
+lg:  20px / 1.25rem   (text-lg)
+xl:  24px / 1.5rem    (text-xl)
+2xl: 32px / 2rem      (text-2xl)
+3xl: 40px / 2.5rem    (text-3xl)
+4xl: 56px / 3.5rem    (text-4xl)
+```
+
+Typography utilities:
+
+- Long headlines: use `text-balance` (prevents orphan words)
+- Body paragraphs: use `text-pretty` (smart line breaks)
+- Number tables: use `tabular-nums` class (not custom CSS)
+
+---
+
+## Design Parameters (Taste Equalizers)
+
+Always set and document the following three parameters (1-10 scale) before starting any design task, to escape generic AI defaults:
+
+- **DESIGN_VARIANCE (1-10)**: Grid and Layout structures.
+  - 1-3 = Clean, centered layouts, standard grids (Enterprise, Docs).
+  - 4-7 = Asymmetric containers, off-grid elements, sticky sidebars (SaaS, Creative tools).
+  - 8-10 = Broken grids, overlapping items, editorial style (Portfolios, Agencies).
+- **MOTION_INTENSITY (1-10)**: Animation depth.
+  - 1-3 = Basic hover states and micro-interactions only.
+  - 4-7 = Page transitions, enter/exit animations, list staggers.
+  - 8-10 = Magnetic elements, complex scroll-triggered animations (GSAP territory).
+- **VISUAL_DENSITY (1-10)**: Information architecture.
+  - 1-3 = Luxury, airy, massive whitespace (Landing pages).
+  - 4-7 = Standard product density (Consumer apps).
+  - 8-10 = Dense, compact, dashboard-style (Pro tools, IDEs, Trading platforms).
+
+## Adaptive Aesthetics (Project Mapping)
+
+Select the base aesthetic based on the project domain:
+
+- **Fintech / Enterprise**: Swiss Minimalism, Neumorphism (High trust, clean, DESIGN_VARIANCE: 2-4).
+- **AI Tools / DevTools**: Dark OLED Luxury, Glassmorphism (Modern, tech-forward, DESIGN_VARIANCE: 5-7).
+- **Creative / Portfolios**: Brutalism, Maximalist, Aurora (Bold, expressive, DESIGN_VARIANCE: 8-10).
+
+## Design Memory & Consistency
+
+**CRITICAL**: You must preserve design decisions between sessions to avoid stylistic drift.
+Whenever you establish core UI tokens (fonts, color scales, border radii, equalizers), write them to `.interface-design/system.md`. In subsequent sessions, ALWAYS read this file before generating new components.
+
+---
+
+## Design Domains
+
+### Product UI (SaaS / Dashboard / App)
+
+- Functional over decorative
+- Dense information where needed (use compact variants)
+- Table zebra striping: use `5%` opacity, not hard borders
+- Data visualization: prefer Chart.js or Recharts, label all axes
+- Loading states: skeleton screens, never spinners alone
+- **Empty States**: ALWAYS design the empty state for every list/table/feed. Never leave a blank screen. Include:
+  1. An illustration or meaningful icon
+  2. A helpful, context-aware message ("No results yet" not "No data")
+  3. A clear primary action CTA ("Create your first project →")
+
+### Marketing / Landing Pages
+
+- Hero: full viewport height, one clear CTA
+- Social proof above the fold when possible
+- CTA buttons: filled primary + ghost secondary (never two filled)
+- Testimonials: real photos, full name, company
+
+### Forms
+
+- Label above field (not placeholder-as-label)
+- Inline validation (show errors on blur, not on submit)
+- Group related fields visually
+- Progress indicator for multi-step flows
+
+---
+
+## Image-First Pipeline (Design Sprints)
+
+If you have access to image generation tools (e.g., DALL-E, Midjourney integrations) and the task involves creating a net-new UI page or component, follow the **Image-First Pipeline**:
+
+1. **Generate**: Create 1-3 reference images ("mockups", "brand boards") of the desired UI using image generation.
+2. **Analyze**: Review the generated images for layout, spacing, and typography choices.
+3. **Implement**: Write the code to match the aesthetic of the generated reference images.
+
+_Do not skip straight to code for major UI overhauls without a visual reference if generation is available._
+
+---
+
+## UI Style Toolkit
+
+### Glassmorphism (Use Sparingly)
+
+```css
+background: rgba(255, 255, 255, 0.05);
+backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 255, 255, 0.1);
+```
+
+### Subtle Shadows (Dark UI)
+
+```css
+/* Card elevation */
+box-shadow: 0 1px 3px rgba(0,0,0,0.4), 0 1px 2px rgba(0,0,0,0.6);
+/* Floating element */
+box-shadow: 0 10px 40px rgba(0,0,0,0.5), 0 0 0 1px rgba(255,255,255,0.05);
+```
+
+### Micro-animations
+
+**CSS (for simple, lightweight elements):**
+
+```css
+/* Standard transition */
+transition: all 0.15s ease-out;
+/* Hover lift */
+transform: translateY(-2px);
+/* Button press */
+transform: scale(0.97);
+/* Fade in */
+@keyframes fadeIn { from { opacity: 0; transform: translateY(8px); } }
+```
+
+**Framer Motion (for complex layout transitions and orchestration):**
+
+For complex UI like modals, popovers, layout shifts, and multi-element orchestration, prefer Framer Motion over raw CSS keyframes. Keep animations quick and purposeful:
+
+```tsx
+// [GOOD] Modal entrance — use highly damped spring for physical feel (like Vercel/Linear)
+<motion.div
+  initial={{ opacity: 0, scale: 0.96, y: 8 }}
+  animate={{ opacity: 1, scale: 1, y: 0 }}
+  exit={{ opacity: 0, scale: 0.96, y: 8 }}
+  transition={{ type: "spring", stiffness: 400, damping: 30 }}
+/>
+
+// [GOOD] List item stagger
+<motion.li
+  initial={{ opacity: 0, x: -8 }}
+  animate={{ opacity: 1, x: 0 }}
+  transition={{ duration: 0.2, ease: "easeOut" }}
+/>
+
+// [BAD] Never use low damping (bouncy feel)
+transition={{ type: "spring", stiffness: 200, damping: 8 }} // WRONG
+```
+
+**Rule**: `duration` must always be `< 0.3s` for micro-interactions. Respect `prefers-reduced-motion`.
+
+---
+
+## Domain Search Guide
+
+When choosing styles, reference these domains:
+
+- `style` — UI style options (glassmorphism, neobrutalism, minimalism)
+- `typography` — Font pairing recommendations  
+- `color` — Color palettes by product type
+- `ux` — Best practices and anti-patterns
+- `gsap` — Animation patterns by intensity (hover, scroll, transition)
+
+## Role Integration
+
+---
+
+## Tailwind CSS v4 (CSS-First Modern Architecture)
+
+In Tailwind CSS v4, styling configuration is native CSS without `tailwind.config.js`:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-primary: #3b82f6;
+  --color-primary-foreground: #ffffff;
+  --color-surface: #0f172a;
+  --color-surface-muted: #1e293b;
+  --font-sans: "Inter", -apple-system, sans-serif;
+  --font-mono: "JetBrains Mono", monospace;
+}
+```
+
+- **Zero JavaScript Config**: Define theme variables directly in CSS `@theme`.
+- **Native CSS Variables**: Use `var(--color-...)` for dynamic runtime theming and dark mode.
+- **Dynamic Viewports**: Use `h-dvh` and `min-h-dvh` for full-height layouts that behave properly on mobile browsers.
+
+---
+
+## Core Web Vitals 2026: INP (Interaction to Next Paint)
+
+- **Target**: INP < 200ms (replaces legacy FID).
+- **Rule**: Never block the main thread for > 50ms during click, keypress, or tap event handlers.
+- Wrap heavy UI updates in `startTransition`:
+
+  ```tsx
+  startTransition(() => {
+    setFilter(newFilter);
+  });
+  ```
+
+- Use Web Workers or chunks for heavy client-side filtering and data processing.
+
+---
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+# UI/UX Pro Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Accessible Icon Button with Visible Focus States
+
+### Anti-pattern: Anti-pattern (Missing accessible name and arbitrary color values)
+
+```tsx
+// BAD: inaccessible to screen readers, missing focus ring, arbitrary hex
+<button className="bg-[#5a4fcf] p-[7px] rounded-[5px]" onClick={onClose}>
+  <XIcon />
+</button>
+```
+
+### Best practice: ContextOS Standard (Semantic token scales & ARIA label)
+
+```tsx
+// GOOD: full keyboard accessibility, semantic tokens, focus-visible ring
+<button
+  type="button"
+  aria-label="Close modal dialog"
+  onClick={onClose}
+  className="inline-flex items-center justify-center rounded-lg p-2 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+>
+  <X className="h-4 w-4" aria-hidden="true" />
+</button>
+```
+
+---
+
+## Example 2: Stat Card Hierarchy
+
+### Anti-pattern: Anti-pattern (Flat low-contrast layout with purple-gradient cliche)
+
+```tsx
+// BAD: cliche AI gradient, poor typographic hierarchy
+<div className="bg-gradient-to-r from-purple-500 to-blue-500 p-4 rounded-xl text-white">
+  <div>Total Revenue</div>
+  <div className="text-xl">$45,231.89</div>
+</div>
+```
+
+### Best practice: ContextOS Standard (Refined editorial typography & subtle depth)
+
+```tsx
+// GOOD: high contrast, monospace numerical accent, subtle border
+<div className="rounded-xl border border-border/50 bg-card p-6 shadow-sm transition-all hover:shadow-md">
+  <div className="flex items-center justify-between">
+    <span className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+      Total Revenue
+    </span>
+    <TrendingUp className="h-4 w-4 text-emerald-500" aria-hidden="true" />
+  </div>
+  <div className="mt-3 flex items-baseline gap-2">
+    <span className="font-mono text-3xl font-semibold tracking-tight text-foreground">
+      $45,231.89
+    </span>
+    <span className="font-mono text-xs font-medium text-emerald-600 dark:text-emerald-400">
+      +14.2%
+    </span>
+  </div>
+</div>
+```
+
+# ui-ux-pro Troubleshooting & Common Mistakes
+
+## 1. Obvious AI Design Tells
+
+- **Symptom**: The interface immediately looks like a generic AI prototype.
+- **Root Cause**: Using Inter alone, pure black (#000000), purple-blue gradients, and rounded icon squares above every title.
+- **Fix**: Use tinted backgrounds (#090A0F), pair primary font with JetBrains Mono for code/numbers, use subtle border highlights.
+
+## 2. Contrast Failures in Secondary Elements
+
+- **Symptom**: Captions, timestamps, and borders are invisible or impossible to read.
+- **Root Cause**: Using flat #666 or #444 grays without testing against actual background luminance.
+- **Fix**: Always test contrast ratios (minimum 4.5:1 for body, 3:1 for graphical boundaries) using semantic theme tokens.
+
+## 3. Nesting Cards Inside Cards
+
+- **Symptom**: Visual claustrophobia and slop aesthetic.
+- **Root Cause**: Putting bordered cards inside other bordered cards.
+- **Fix**: Flatten the hierarchy. Use background surface contrast and negative space instead of border-in-border nesting.

package/.agents/generated/claude/skills/ux-design/SKILL.md

@@ -0,0 +1,168 @@
+# UX Design
+
+## Overview
+
+User experience and interaction design standard. Enforces progressive disclosure, predictable user flows, designed empty/loading/error states, form usability, and keyboard navigation ergonomics.
+
+## When to Use
+
+Activate when designing complex multi-step workflows, onboarding funnels, form validation feedback, error recovery flows, and user journeys.
+
+## Rules & Patterns
+<!-- Source: ux.md -->
+
+## UX Design — Best Practices
+
+## Information Architecture
+
+- **Mental models** — organize content the way users think, not the way your code is structured
+- **Card sorting** — group features into logical categories
+- **Navigation structure** — no more than 3 clicks to any page
+- **Naming** — use user's language, not internal jargon
+
+## User Flows
+
+### Design every state
+
+Every screen has 5 states. Design ALL of them:
+
+1. **Empty state** — first visit, no data yet. Include CTA to get started
+2. **Loading state** — skeleton screens > spinners
+3. **Partial state** — some data, not complete
+4. **Ideal state** — normal usage with data
+5. **Error state** — what went wrong and how to fix it
+
+### Reduce cognitive load
+
+- **Progressive disclosure** — show only what's needed now
+- **Sensible defaults** — pre-fill what you can
+- **Inline help** — tooltips and contextual guidance
+- **Confirmation for destructive actions** — but NOT for every action
+
+## Forms UX
+
+- Show progress for multi-step forms
+- Validate inline (on blur), not on submit
+- Show password requirements as the user types
+- Auto-focus the first input
+- Use appropriate input types (email, tel, date)
+- Disable submit button only when form is submitting, never as "validation"
+
+## Onboarding
+
+- **Quick win** — let users see value within 30 seconds
+- **Minimal signup** — only ask for what's absolutely needed
+- **Progressive onboarding** — teach features as users encounter them
+- **Skip option** — always let users skip tutorials
+
+## Feedback
+
+- Every action needs feedback (success, error, pending)
+- Use toast notifications for non-blocking feedback
+- Use inline messages for form validation
+- Loading states should be < 300ms before showing (avoid flash)
+- Optimistic UI for fast-perceived actions
+
+## Mobile UX
+
+- Touch targets: minimum 44x44px
+- Thumb zones — place primary actions within easy reach
+- Bottom navigation for core actions
+- Pull-to-refresh for content lists
+- Haptic feedback for important actions
+
+## Psychology Principles
+
+- **Fitts's Law** — make important targets large and close
+- **Hick's Law** — reduce choices to reduce decision time
+- **Jakob's Law** — users prefer familiar patterns
+- **Peak-End Rule** — make the last interaction great
+- **Aesthetic-Usability Effect** — beautiful things are perceived as easier to use
+
+## Usability Heuristics (Nielsen)
+
+1. Visibility of system status
+2. Match between system and real world
+3. User control and freedom (undo, escape)
+4. Consistency and standards
+5. Error prevention
+6. Recognition rather than recall
+7. Flexibility and efficiency of use
+8. Aesthetic and minimalist design
+9. Help users recognize and recover from errors
+10. Help and documentation
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+# ux-design Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Destructive Actions
+
+### Anti-pattern: Instant Deletion Without Confirmation or Recovery
+
+```tsx
+// BAD: Immediate delete on click, no confirmation, irreversible data loss
+<button onClick={() => deleteProject(project.id)}>Delete</button>
+```
+
+### Best practice: ContextOS Standard (Two-Step Confirmation or Undo Toast)
+
+```tsx
+// GOOD: Clear confirmation dialog stating exact item name and non-reversible impact
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete Project</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+      <AlertDialogDescription>
+        This action cannot be undone. This will permanently delete <strong>{project.name}</strong>
+        and all associated API keys.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction onClick={handleDelete} className="bg-destructive">
+        Delete permanently
+      </AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+# ux-design Troubleshooting & Common Mistakes
+
+## 1. Mystery Meat Navigation
+
+- **Symptom**: Users don't know what icons do and have to hover to guess.
+- **Root Cause**: Relying on ambiguous icons without text labels or tooltips.
+- **Fix**: Pair icons with text labels wherever space permits; always provide accessible tooltips on icon-only actions.
+
+## 2. Loss of User Input on Interruption
+
+- **Symptom**: User accidentally clicks outside a long modal form and all typed content vanishes.
+- **Root Cause**: Modals closing on backdrop click without checking form dirty state.
+- **Fix**: Prevent dismiss on outside click when form has unsaved modifications, or autosave drafts to local storage.
+
+## 3. Double-Click Submission Bugs
+
+- **Symptom**: Users double-click a submit button on slow network, resulting in duplicate charges or items.
+- **Root Cause**: Form buttons remaining active during in-flight network requests.
+- **Fix**: Disable button and show spinner state as soon as form submission begins.

package/.agents/generated/claude/skills/vercel-optimize/SKILL.md

@@ -0,0 +1,76 @@
+# Vercel Optimize
+
+## Overview
+
+Observability-first Vercel performance and cost reduction optimization skill. Evaluates deployed Next.js, SvelteKit, Nuxt, and Astro projects using production telemetry signals (`signals.json`), deterministic candidate gating, and code scanning to deliver ranked, verified architectural recommendations.
+
+## When to Use
+
+- When tasked with reducing Vercel bills, Function Invocations, Fast Data Transfer, or Build Minutes.
+- When diagnosing slow serverless routes, cold starts, or Edge vs Node runtime mismatches.
+- When evaluating caching opportunities (`stale-while-revalidate`, ISR, CDN edge caching) or Core Web Vitals degradation.
+
+## Rules & Patterns
+
+### 1. Prerequisites & Framework Support
+
+- Vercel CLI v53+ with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api`.
+- Authenticated CLI session (`vercel login`) and linked app directory (`vercel link`).
+- Framework support: Next.js App Router (Full), Pages Router (Supported), SvelteKit (Supported), Nuxt (Supported), Astro (Limited).
+- Security rule: Never put auth tokens in shell commands (`VERCEL_TOKEN=...` is banned in chat/logs).
+
+### 2. Core Doctrine & Gating Pipeline
+
+- **Metrics First:** Recommendations start from Vercel production signals (14-day window), not repo-wide grep.
+- **Deterministic Gates:** `scripts/gate-investigations.mjs` selects code-scope and platform-scope candidates.
+- **Candidate-Bound Scope:** Inspect only files named by a candidate or a route-local import chain.
+- **Version-Aware Citations:** Use only verified citations matching the target framework version.
+- **Specific Cache Policies:** When recommending caching, state the exact cache policy and headers; keep auth-sensitive and error responses dynamic.
+
+### 3. Recommendation Rules
+
+- Every recommendation must trace to a launched candidate and include observed metric evidence.
+- Cite verified files with line numbers when code changes are proposed.
+- Use precise observed performance numbers; avoid customer-facing speculative `$N` savings formulas.
+- Do not recommend duration reductions for Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`).
+
+## Code Examples
+
+```typescript
+// [GOOD] Next.js Route Segment Config for Caching & Edge Runtime
+export const dynamic = 'force-static';
+export const revalidate = 3600; // Cache at Edge for 1 hour
+
+export default async function CachedCatalogPage() {
+  const products = await getCatalogData();
+  return <CatalogGrid items={products} />;
+}
+```
+
+```bash
+# Running the signals collection and gate
+node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json"
+node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
+node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"
+```
+
+## Validation Checklist
+
+- [ ] Project is properly linked with valid team/personal scope (`vercel link`).
+- [ ] Production metrics signals collected across 14-day window before inspecting code.
+- [ ] No secrets or tokens passed in command line arguments.
+- [ ] Recommendations grounded in specific verified file paths and line numbers.
+- [ ] Unsafe or auth-sensitive paths kept strictly dynamic.
+
+## Common Mistakes
+
+- Inspecting repository source code before metric signals exist.
+- Hardcoding `VERCEL_TOKEN` into terminal commands or prompt logs.
+- Recommending duration reductions on long-lived streaming routes or workflow runners.
+- Applying static caching to user-specific or authenticated routes.
+
+## Integration Notes
+
+- Complements `nextjs` and `react-best-practices` for server-side optimization.
+- Pairs with `performance` and `security` skills.