Skip to content

Open-source status page, incident response and uptime monitoring

Docs update content (#1916)

Thibault Le Ouaye28e5f60abc7
diff --git a/.agents/skills/copywriting/SKILL.md b/.agents/skills/copywriting/SKILL.md
deleted file mode 100644
index d49f6e3e8..000000000
--- a/.agents/skills/copywriting/SKILL.md
+++ /dev/null
@@ -1,251 +0,0 @@
----
-name: copywriting
-version: 1.0.0
-description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro.
----
-
-# Copywriting
-
-You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.
-
-## Before Writing
-
-**Check for product marketing context first:**
-If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
-
-Gather this context (ask if not provided):
-
-### 1. Page Purpose
-- What type of page? (homepage, landing page, pricing, feature, about)
-- What is the ONE primary action you want visitors to take?
-
-### 2. Audience
-- Who is the ideal customer?
-- What problem are they trying to solve?
-- What objections or hesitations do they have?
-- What language do they use to describe their problem?
-
-### 3. Product/Offer
-- What are you selling or offering?
-- What makes it different from alternatives?
-- What's the key transformation or outcome?
-- Any proof points (numbers, testimonials, case studies)?
-
-### 4. Context
-- Where is traffic coming from? (ads, organic, email)
-- What do visitors already know before arriving?
-
----
-
-## Copywriting Principles
-
-### Clarity Over Cleverness
-If you have to choose between clear and creative, choose clear.
-
-### Benefits Over Features
-Features: What it does. Benefits: What that means for the customer.
-
-### Specificity Over Vagueness
-- Vague: "Save time on your workflow"
-- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"
-
-### Customer Language Over Company Language
-Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets.
-
-### One Idea Per Section
-Each section should advance one argument. Build a logical flow down the page.
-
----
-
-## Writing Style Rules
-
-### Core Principles
-
-1. **Simple over complex** — "Use" not "utilize," "help" not "facilitate"
-2. **Specific over vague** — Avoid "streamline," "optimize," "innovative"
-3. **Active over passive** — "We generate reports" not "Reports are generated"
-4. **Confident over qualified** — Remove "almost," "very," "really"
-5. **Show over tell** — Describe the outcome instead of using adverbs
-6. **Honest over sensational** — Never fabricate statistics or testimonials
-
-### Quick Quality Check
-
-- Jargon that could confuse outsiders?
-- Sentences trying to do too much?
-- Passive voice constructions?
-- Exclamation points? (remove them)
-- Marketing buzzwords without substance?
-
-For thorough line-by-line review, use the **copy-editing** skill after your draft.
-
----
-
-## Best Practices
-
-### Be Direct
-Get to the point. Don't bury the value in qualifications.
-
-❌ Slack lets you share files instantly, from documents to images, directly in your conversations
-
-✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires.
-
-### Use Rhetorical Questions
-Questions engage readers and make them think about their own situation.
-- "Hate returning stuff to Amazon?"
-- "Tired of chasing approvals?"
-
-### Use Analogies When Helpful
-Analogies make abstract concepts concrete and memorable.
-
-### Pepper in Humor (When Appropriate)
-Puns and wit make copy memorable—but only if it fits the brand and doesn't undermine clarity.
-
----
-
-## Page Structure Framework
-
-### Above the Fold
-
-**Headline**
-- Your single most important message
-- Communicate core value proposition
-- Specific > generic
-
-**Example formulas:**
-- "{Achieve outcome} without {pain point}"
-- "The {category} for {audience}"
-- "Never {unpleasant event} again"
-- "{Question highlighting main pain point}"
-
-**For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md)
-
-**For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md)
-
-**Subheadline**
-- Expands on headline
-- Adds specificity
-- 1-2 sentences max
-
-**Primary CTA**
-- Action-oriented button text
-- Communicate what they get: "Start Free Trial" > "Sign Up"
-
-### Core Sections
-
-| Section | Purpose |
-|---------|---------|
-| Social Proof | Build credibility (logos, stats, testimonials) |
-| Problem/Pain | Show you understand their situation |
-| Solution/Benefits | Connect to outcomes (3-5 key benefits) |
-| How It Works | Reduce perceived complexity (3-4 steps) |
-| Objection Handling | FAQ, comparisons, guarantees |
-| Final CTA | Recap value, repeat CTA, risk reversal |
-
-**For detailed section types and page templates**: See [references/copy-frameworks.md](references/copy-frameworks.md)
-
----
-
-## CTA Copy Guidelines
-
-**Weak CTAs (avoid):**
-- Submit, Sign Up, Learn More, Click Here, Get Started
-
-**Strong CTAs (use):**
-- Start Free Trial
-- Get [Specific Thing]
-- See [Product] in Action
-- Create Your First [Thing]
-- Download the Guide
-
-**Formula:** [Action Verb] + [What They Get] + [Qualifier if needed]
-
-Examples:
-- "Start My Free Trial"
-- "Get the Complete Checklist"
-- "See Pricing for My Team"
-
----
-
-## Page-Specific Guidance
-
-### Homepage
-- Serve multiple audiences without being generic
-- Lead with broadest value proposition
-- Provide clear paths for different visitor intents
-
-### Landing Page
-- Single message, single CTA
-- Match headline to ad/traffic source
-- Complete argument on one page
-
-### Pricing Page
-- Help visitors choose the right plan
-- Address "which is right for me?" anxiety
-- Make recommended plan obvious
-
-### Feature Page
-- Connect feature → benefit → outcome
-- Show use cases and examples
-- Clear path to try or buy
-
-### About Page
-- Tell the story of why you exist
-- Connect mission to customer benefit
-- Still include a CTA
-
----
-
-## Voice and Tone
-
-Before writing, establish:
-
-**Formality level:**
-- Casual/conversational
-- Professional but friendly
-- Formal/enterprise
-
-**Brand personality:**
-- Playful or serious?
-- Bold or understated?
-- Technical or accessible?
-
-Maintain consistency, but adjust intensity:
-- Headlines can be bolder
-- Body copy should be clearer
-- CTAs should be action-oriented
-
----
-
-## Output Format
-
-When writing copy, provide:
-
-### Page Copy
-Organized by section:
-- Headline, Subheadline, CTA
-- Section headers and body copy
-- Secondary CTAs
-
-### Annotations
-For key elements, explain:
-- Why you made this choice
-- What principle it applies
-
-### Alternatives
-For headlines and CTAs, provide 2-3 options:
-- Option A: [copy] — [rationale]
-- Option B: [copy] — [rationale]
-
-### Meta Content (if relevant)
-- Page title (for SEO)
-- Meta description
-
----
-
-## Related Skills
-
-- **copy-editing**: For polishing existing copy (use after your draft)
-- **page-cro**: If page structure/strategy needs work, not just copy
-- **email-sequence**: For email copywriting
-- **popup-cro**: For popup and modal copy
-- **ab-test-setup**: To test copy variations
diff --git a/.agents/skills/copywriting/references/copy-frameworks.md b/.agents/skills/copywriting/references/copy-frameworks.md
deleted file mode 100644
index 9957b96f0..000000000
--- a/.agents/skills/copywriting/references/copy-frameworks.md
+++ /dev/null
@@ -1,338 +0,0 @@
-# Copy Frameworks Reference
-
-Headline formulas, page section types, and structural templates.
-
-## Headline Formulas
-
-### Outcome-Focused
-
-**{Achieve desirable outcome} without {pain point}**
-> Understand how users are really experiencing your site without drowning in numbers
-
-**{Achieve desirable outcome} by {how product makes it possible}**
-> Generate more leads by seeing which companies visit your site
-
-**Turn {input} into {outcome}**
-> Turn your hard-earned sales into repeat customers
-
-**[Achieve outcome] in [timeframe]**
-> Get your tax refund in 10 days
-
----
-
-### Problem-Focused
-
-**Never {unpleasant event} again**
-> Never miss a sales opportunity again
-
-**{Question highlighting the main pain point}**
-> Hate returning stuff to Amazon?
-
-**Stop [pain]. Start [pleasure].**
-> Stop chasing invoices. Start getting paid on time.
-
----
-
-### Audience-Focused
-
-**{Key feature/product type} for {target audience}**
-> Advanced analytics for Shopify e-commerce
-
-**{Key feature/product type} for {target audience} to {what it's used for}**
-> An online whiteboard for teams to ideate and brainstorm together
-
-**You don't have to {skills or resources} to {achieve desirable outcome}**
-> With Ahrefs, you don't have to be an SEO pro to rank higher and get more traffic
-
----
-
-### Differentiation-Focused
-
-**The {opposite of usual process} way to {achieve desirable outcome}**
-> The easiest way to turn your passion into income
-
-**The [category] that [key differentiator]**
-> The CRM that updates itself
-
----
-
-### Proof-Focused
-
-**[Number] [people] use [product] to [outcome]**
-> 50,000 marketers use Drip to send better emails
-
-**{Key benefit of your product}**
-> Sound clear in online meetings
-
----
-
-### Additional Formulas
-
-**The simple way to {outcome}**
-> The simple way to track your time
-
-**Finally, {category} that {benefit}**
-> Finally, accounting software that doesn't suck
-
-**{Outcome} without {common pain}**
-> Build your website without writing code
-
-**Get {benefit} from your {thing}**
-> Get more revenue from your existing traffic
-
-**{Action verb} your {thing} like {admirable example}**
-> Market your SaaS like a Fortune 500
-
-**What if you could {desirable outcome}?**
-> What if you could close deals 30% faster?
-
-**Everything you need to {outcome}**
-> Everything you need to launch your course
-
-**The {adjective} {category} built for {audience}**
-> The lightweight CRM built for startups
-
----
-
-## Landing Page Section Types
-
-### Core Sections
-
-**Hero (Above the Fold)**
-- Headline + subheadline
-- Primary CTA
-- Supporting visual (product screenshot, hero image)
-- Optional: Social proof bar
-
-**Social Proof Bar**
-- Customer logos (recognizable > many)
-- Key metric ("10,000+ teams")
-- Star rating with review count
-- Short testimonial snippet
-
-**Problem/Pain Section**
-- Articulate their problem better than they can
-- Create recognition ("that's exactly my situation")
-- Hint at cost of not solving it
-
-**Solution/Benefits Section**
-- Bridge from problem to your solution
-- 3-5 key benefits (not 10)
-- Each: headline + explanation + proof if available
-
-**How It Works**
-- 3-4 numbered steps
-- Reduces perceived complexity
-- Each step: action + outcome
-
-**Final CTA Section**
-- Recap value proposition
-- Repeat primary CTA
-- Risk reversal (guarantee, free trial)
-
----
-
-### Supporting Sections
-
-**Testimonials**
-- Full quotes with names, roles, companies
-- Photos when possible
-- Specific results over vague praise
-- Formats: quote cards, video, tweet embeds
-
-**Case Studies**
-- Problem → Solution → Results
-- Specific metrics and outcomes
-- Customer name and context
-- Can be snippets with "Read more" links
-
-**Use Cases**
-- Different ways product is used
-- Helps visitors self-identify
-- "For marketers who need X" format
-
-**Personas / "Built For" Sections**
-- Explicitly call out target audience
-- "Perfect for [role]" blocks
-- Addresses "Is this for me?" question
-
-**FAQ Section**
-- Address common objections
-- Good for SEO
-- Reduces support burden
-- 5-10 most common questions
-
-**Comparison Section**
-- vs. competitors (name them or don't)
-- vs. status quo (spreadsheets, manual processes)
-- Tables or side-by-side format
-
-**Integrations / Partners**
-- Logos of tools you connect with
-- "Works with your stack" messaging
-- Builds credibility
-
-**Founder Story / Manifesto**
-- Why you built this
-- What you believe
-- Emotional connection
-- Differentiates from faceless competitors
-
-**Demo / Product Tour**
-- Interactive demos
-- Video walkthroughs
-- GIF previews
-- Shows product in action
-
-**Pricing Preview**
-- Teaser even on non-pricing pages
-- Starting price or "from $X/mo"
-- Moves decision-makers forward
-
-**Guarantee / Risk Reversal**
-- Money-back guarantee
-- Free trial terms
-- "Cancel anytime"
-- Reduces friction
-
-**Stats Section**
-- Key metrics that build credibility
-- "10,000+ customers"
-- "4.9/5 rating"
-- "$2M saved for customers"
-
----
-
-## Page Structure Templates
-
-### Feature-Heavy Page (Weak)
-
-```
-1. Hero
-2. Feature 1
-3. Feature 2
-4. Feature 3
-5. Feature 4
-6. CTA
-```
-
-This is a list, not a persuasive narrative.
-
----
-
-### Varied, Engaging Page (Strong)
-
-```
-1. Hero with clear value prop
-2. Social proof bar (logos or stats)
-3. Problem/pain section
-4. How it works (3 steps)
-5. Key benefits (2-3, not 10)
-6. Testimonial
-7. Use cases or personas
-8. Comparison to alternatives
-9. Case study snippet
-10. FAQ
-11. Final CTA with guarantee
-```
-
-This tells a story and addresses objections.
-
----
-
-### Compact Landing Page
-
-```
-1. Hero (headline, subhead, CTA, image)
-2. Social proof bar
-3. 3 key benefits with icons
-4. Testimonial
-5. How it works (3 steps)
-6. Final CTA with guarantee
-```
-
-Good for ad landing pages where brevity matters.
-
----
-
-### Enterprise/B2B Landing Page
-
-```
-1. Hero (outcome-focused headline)
-2. Logo bar (recognizable companies)
-3. Problem section (business pain)
-4. Solution overview
-5. Use cases by role/department
-6. Security/compliance section
-7. Integration logos
-8. Case study with metrics
-9. ROI/value section
-10. Contact/demo CTA
-```
-
-Addresses enterprise buyer concerns.
-
----
-
-### Product Launch Page
-
-```
-1. Hero with launch announcement
-2. Video demo or walkthrough
-3. Feature highlights (3-5)
-4. Before/after comparison
-5. Early testimonials
-6. Launch pricing or early access offer
-7. CTA with urgency
-```
-
-Good for ProductHunt, launches, or announcements.
-
----
-
-## Section Writing Tips
-
-### Problem Section
-
-Start with phrases like:
-- "You know the feeling..."
-- "If you're like most [role]..."
-- "Every day, [audience] struggles with..."
-- "We've all been there..."
-
-Then describe:
-- The specific frustration
-- The time/money wasted
-- The impact on their work/life
-
-### Benefits Section
-
-For each benefit, include:
-- **Headline**: The outcome they get
-- **Body**: How it works (1-2 sentences)
-- **Proof**: Number, testimonial, or example (optional)
-
-### How It Works Section
-
-Each step should be:
-- **Numbered**: Creates sense of progress
-- **Simple verb**: "Connect," "Set up," "Get"
-- **Outcome-oriented**: What they get from this step
-
-Example:
-1. Connect your tools (takes 2 minutes)
-2. Set your preferences
-3. Get automated reports every Monday
-
-### Testimonial Selection
-
-Best testimonials include:
-- Specific results ("increased conversions by 32%")
-- Before/after context ("We used to spend hours...")
-- Role + company for credibility
-- Something quotable and specific
-
-Avoid testimonials that just say:
-- "Great product!"
-- "Love it!"
-- "Easy to use!"
diff --git a/.agents/skills/copywriting/references/natural-transitions.md b/.agents/skills/copywriting/references/natural-transitions.md
deleted file mode 100644
index 929116faa..000000000
--- a/.agents/skills/copywriting/references/natural-transitions.md
+++ /dev/null
@@ -1,252 +0,0 @@
-# Natural Transitions
-
-Transitional phrases to guide readers through your content. Good signposting improves readability, user engagement, and helps search engines understand content structure.
-
-Adapted from: University of Manchester Academic Phrasebank (2023), Plain English Campaign, web content best practices
-
----
-
-## Previewing Content Structure
-
-Use to orient readers and set expectations:
-
-- Here's what we'll cover...
-- This guide walks you through...
-- Below, you'll find...
-- We'll start with X, then move to Y...
-- First, let's look at...
-- Let's break this down step by step.
-- The sections below explain...
-
----
-
-## Introducing a New Topic
-
-- When it comes to X,...
-- Regarding X,...
-- Speaking of X,...
-- Now let's talk about X.
-- Another key factor is...
-- X is worth exploring because...
-
----
-
-## Referring Back
-
-Use to connect ideas and reinforce key points:
-
-- As mentioned earlier,...
-- As we covered above,...
-- Remember when we discussed X?
-- Building on that point,...
-- Going back to X,...
-- Earlier, we explained that...
-
----
-
-## Moving Between Sections
-
-- Now let's look at...
-- Next up:...
-- Moving on to...
-- With that covered, let's turn to...
-- Now that you understand X, here's Y.
-- That brings us to...
-
----
-
-## Indicating Addition
-
-- Also,...
-- Plus,...
-- On top of that,...
-- What's more,...
-- Another benefit is...
-- Beyond that,...
-- In addition,...
-- There's also...
-
-**Note:** Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused.
-
----
-
-## Indicating Contrast
-
-- However,...
-- But,...
-- That said,...
-- On the flip side,...
-- In contrast,...
-- Unlike X, Y...
-- While X is true, Y...
-- Despite this,...
-
----
-
-## Indicating Similarity
-
-- Similarly,...
-- Likewise,...
-- In the same way,...
-- Just like X, Y also...
-- This mirrors...
-- The same applies to...
-
----
-
-## Indicating Cause and Effect
-
-- So,...
-- This means...
-- As a result,...
-- That's why...
-- Because of this,...
-- This leads to...
-- The outcome?...
-- Here's what happens:...
-
----
-
-## Giving Examples
-
-- For example,...
-- For instance,...
-- Here's an example:...
-- Take X, for instance.
-- Consider this:...
-- A good example is...
-- To illustrate,...
-- Like when...
-- Say you want to...
-
----
-
-## Emphasising Key Points
-
-- Here's the key takeaway:...
-- The important thing is...
-- What matters most is...
-- Don't miss this:...
-- Pay attention to...
-- This is critical:...
-- The bottom line?...
-
----
-
-## Providing Evidence
-
-Use when citing sources, data, or expert opinions:
-
-### Neutral attribution
-- According to [Source],...
-- [Source] reports that...
-- Research shows that...
-- Data from [Source] indicates...
-- A study by [Source] found...
-
-### Expert quotes
-- As [Expert] puts it,...
-- [Expert] explains,...
-- In the words of [Expert],...
-- [Expert] notes that...
-
-### Supporting claims
-- This is backed by...
-- Evidence suggests...
-- The numbers confirm...
-- This aligns with findings from...
-
----
-
-## Summarising Sections
-
-- To recap,...
-- Here's the short version:...
-- In short,...
-- The takeaway?...
-- So what does this mean?...
-- Let's pull this together:...
-- Quick summary:...
-
----
-
-## Concluding Content
-
-- Wrapping up,...
-- The bottom line is...
-- Here's what to do next:...
-- To sum up,...
-- Final thoughts:...
-- Ready to get started?...
-- Now it's your turn.
-
-**Note:** Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing.
-
----
-
-## Question-Based Transitions
-
-Useful for conversational tone and featured snippet optimization:
-
-- So what does this mean for you?
-- But why does this matter?
-- How do you actually do this?
-- What's the catch?
-- Sound complicated? It's not.
-- Wondering where to start?
-- Still not sure? Here's the breakdown.
-
----
-
-## List Introductions
-
-For numbered lists and step-by-step content:
-
-- Here's how to do it:
-- Follow these steps:
-- The process is straightforward:
-- Here's what you need to know:
-- Key things to consider:
-- The main factors are:
-
----
-
-## Hedging Language
-
-For claims that need qualification or aren't absolute:
-
-- may, might, could
-- tends to, generally
-- often, usually, typically
-- in most cases
-- it appears that
-- evidence suggests
-- this can help
-- many experts believe
-
----
-
-## Best Practice Guidelines
-
-1. **Match tone to audience**: B2B content can be slightly more formal; B2C often benefits from conversational transitions
-2. **Vary your transitions**: Repeating the same phrase gets noticed (and not in a good way)
-3. **Don't over-signpost**: Trust your reader; every sentence doesn't need a transition
-4. **Use for scannability**: Transitions at paragraph starts help skimmers navigate
-5. **Keep it natural**: Read aloud; if it sounds forced, simplify
-6. **Front-load key info**: Put the important word or phrase early in the transition
-
----
-
-## Transitions to Avoid (AI Tells)
-
-These phrases are overused in AI-generated content:
-
-- "That being said,..."
-- "It's worth noting that..."
-- "At its core,..."
-- "In today's digital landscape,..."
-- "When it comes to the realm of..."
-- "This begs the question..."
-- "Let's delve into..."
-
-See the seo-audit skill's `references/ai-writing-detection.md` for a complete list of AI writing tells.
diff --git a/.agents/skills/find-skills/SKILL.md b/.agents/skills/find-skills/SKILL.md
deleted file mode 100644
index c797184ee..000000000
--- a/.agents/skills/find-skills/SKILL.md
+++ /dev/null
@@ -1,133 +0,0 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Search for Skills
-
-Run the find command with a relevant query:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-The command will return results like:
-
-```
-Install with npx skills add <owner/repo@skill>
-
-vercel-labs/agent-skills@vercel-react-best-practices
-└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 3: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install command they can run
-3. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "vercel-react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-
-To install it:
-npx skills add vercel-labs/agent-skills@vercel-react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 4: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category | Example Queries |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing | testing, jest, playwright, e2e |
-| DevOps | deploy, docker, kubernetes, ci-cd |
-| Documentation | docs, readme, changelog, api-docs |
-| Code Quality | review, lint, refactor, best-practices |
-| Design | ui, ux, design-system, accessibility |
-| Productivity | workflow, automation, git |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```
diff --git a/.agents/skills/hono/SKILL.md b/.agents/skills/hono/SKILL.md
deleted file mode 100644
index 8b00a0e53..000000000
--- a/.agents/skills/hono/SKILL.md
+++ /dev/null
@@ -1,90 +0,0 @@
----
-name: hono
-description: Efficiently develop Hono applications using Hono CLI. Supports documentation search, API reference lookup, request testing, and bundle optimization.
----
-
-# Hono Skill
-
-Develop Hono applications efficiently using Hono CLI (`@hono/cli`).
-
-## Setup
-
-You can use Hono CLI without global installation via npx:
-
-```bash
-npx @hono/cli <command>
-```
-
-Or install globally (optional):
-
-```bash
-npm install -g @hono/cli
-```
-
-## Commands for AI
-
-### 1. Search Documentation
-
-```bash
-hono search "<query>" --pretty
-```
-
-Search for Hono APIs and features. Use `--pretty` for human-readable output.
-
-### 2. View Documentation
-
-```bash
-hono docs [path]
-```
-
-Display detailed documentation for a specific path found in search results.
-
-**Examples:**
-
-```bash
-hono docs /docs/api/context
-hono docs /docs/api/hono
-hono docs /docs/helpers/factory
-```
-
-### 3. Request Testing
-
-```bash
-# GET request
-hono request [file] -P /path
-
-# POST request
-hono request [file] -X POST -P /api/users -d '{"name": "test"}'
-
-# Request with headers
-hono request [file] -H "Authorization: Bearer token" -P /api/protected
-```
-
-Uses `app.request()` internally, so no server startup required for testing.
-
-### 4. Optimization & Bundling
-
-```bash
-# Bundle optimization
-hono optimize [entry] -o dist/index.js
-
-# With minification
-hono optimize [entry] -o dist/index.js --minify
-
-# Specify target (cloudflare-workers, deno, etc.)
-hono optimize [entry] -t cloudflare-workers
-```
-
-## Development Workflow
-
-1. **Research**: Use `hono search` → `hono docs` to investigate APIs and features
-2. **Implement**: Write the code
-3. **Test**: Use `hono request` to test endpoints
-4. **Optimize**: Use `hono optimize` for production builds when needed
-
-## Guidelines
-
-- Always search with `hono search` before implementing unfamiliar APIs
-- Use `--pretty` flag with `hono search` (default output is JSON)
-- `hono request` works without starting an HTTP server
-- Search for middleware usage with `hono search "middleware name"`
diff --git a/.agents/skills/seo-audit/SKILL.md b/.agents/skills/seo-audit/SKILL.md
deleted file mode 100644
index 0e5b37279..000000000
--- a/.agents/skills/seo-audit/SKILL.md
+++ /dev/null
@@ -1,394 +0,0 @@
----
-name: seo-audit
-version: 1.0.0
-description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," or "SEO health check." For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup.
----
-
-# SEO Audit
-
-You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.
-
-## Initial Assessment
-
-**Check for product marketing context first:**
-If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
-
-Before auditing, understand:
-
-1. **Site Context**
- - What type of site? (SaaS, e-commerce, blog, etc.)
- - What's the primary business goal for SEO?
- - What keywords/topics are priorities?
-
-2. **Current State**
- - Any known issues or concerns?
- - Current organic traffic level?
- - Recent changes or migrations?
-
-3. **Scope**
- - Full site audit or specific pages?
- - Technical + on-page, or one focus area?
- - Access to Search Console / analytics?
-
----
-
-## Audit Framework
-
-### Priority Order
-1. **Crawlability & Indexation** (can Google find and index it?)
-2. **Technical Foundations** (is the site fast and functional?)
-3. **On-Page Optimization** (is content optimized?)
-4. **Content Quality** (does it deserve to rank?)
-5. **Authority & Links** (does it have credibility?)
-
----
-
-## Technical SEO Audit
-
-### Crawlability
-
-**Robots.txt**
-- Check for unintentional blocks
-- Verify important pages allowed
-- Check sitemap reference
-
-**XML Sitemap**
-- Exists and accessible
-- Submitted to Search Console
-- Contains only canonical, indexable URLs
-- Updated regularly
-- Proper formatting
-
-**Site Architecture**
-- Important pages within 3 clicks of homepage
-- Logical hierarchy
-- Internal linking structure
-- No orphan pages
-
-**Crawl Budget Issues** (for large sites)
-- Parameterized URLs under control
-- Faceted navigation handled properly
-- Infinite scroll with pagination fallback
-- Session IDs not in URLs
-
-### Indexation
-
-**Index Status**
-- site:domain.com check
-- Search Console coverage report
-- Compare indexed vs. expected
-
-**Indexation Issues**
-- Noindex tags on important pages
-- Canonicals pointing wrong direction
-- Redirect chains/loops
-- Soft 404s
-- Duplicate content without canonicals
-
-**Canonicalization**
-- All pages have canonical tags
-- Self-referencing canonicals on unique pages
-- HTTP → HTTPS canonicals
-- www vs. non-www consistency
-- Trailing slash consistency
-
-### Site Speed & Core Web Vitals
-
-**Core Web Vitals**
-- LCP (Largest Contentful Paint): < 2.5s
-- INP (Interaction to Next Paint): < 200ms
-- CLS (Cumulative Layout Shift): < 0.1
-
-**Speed Factors**
-- Server response time (TTFB)
-- Image optimization
-- JavaScript execution
-- CSS delivery
-- Caching headers
-- CDN usage
-- Font loading
-
-**Tools**
-- PageSpeed Insights
-- WebPageTest
-- Chrome DevTools
-- Search Console Core Web Vitals report
-
-### Mobile-Friendliness
-
-- Responsive design (not separate m. site)
-- Tap target sizes
-- Viewport configured
-- No horizontal scroll
-- Same content as desktop
-- Mobile-first indexing readiness
-
-### Security & HTTPS
-
-- HTTPS across entire site
-- Valid SSL certificate
-- No mixed content
-- HTTP → HTTPS redirects
-- HSTS header (bonus)
-
-### URL Structure
-
-- Readable, descriptive URLs
-- Keywords in URLs where natural
-- Consistent structure
-- No unnecessary parameters
-- Lowercase and hyphen-separated
-
----
-
-## On-Page SEO Audit
-
-### Title Tags
-
-**Check for:**
-- Unique titles for each page
-- Primary keyword near beginning
-- 50-60 characters (visible in SERP)
-- Compelling and click-worthy
-- Brand name placement (end, usually)
-
-**Common issues:**
-- Duplicate titles
-- Too long (truncated)
-- Too short (wasted opportunity)
-- Keyword stuffing
-- Missing entirely
-
-### Meta Descriptions
-
-**Check for:**
-- Unique descriptions per page
-- 150-160 characters
-- Includes primary keyword
-- Clear value proposition
-- Call to action
-
-**Common issues:**
-- Duplicate descriptions
-- Auto-generated garbage
-- Too long/short
-- No compelling reason to click
-
-### Heading Structure
-
-**Check for:**
-- One H1 per page
-- H1 contains primary keyword
-- Logical hierarchy (H1 → H2 → H3)
-- Headings describe content
-- Not just for styling
-
-**Common issues:**
-- Multiple H1s
-- Skip levels (H1 → H3)
-- Headings used for styling only
-- No H1 on page
-
-### Content Optimization
-
-**Primary Page Content**
-- Keyword in first 100 words
-- Related keywords naturally used
-- Sufficient depth/length for topic
-- Answers search intent
-- Better than competitors
-
-**Thin Content Issues**
-- Pages with little unique content
-- Tag/category pages with no value
-- Doorway pages
-- Duplicate or near-duplicate content
-
-### Image Optimization
-
-**Check for:**
-- Descriptive file names
-- Alt text on all images
-- Alt text describes image
-- Compressed file sizes
-- Modern formats (WebP)
-- Lazy loading implemented
-- Responsive images
-
-### Internal Linking
-
-**Check for:**
-- Important pages well-linked
-- Descriptive anchor text
-- Logical link relationships
-- No broken internal links
-- Reasonable link count per page
-
-**Common issues:**
-- Orphan pages (no internal links)
-- Over-optimized anchor text
-- Important pages buried
-- Excessive footer/sidebar links
-
-### Keyword Targeting
-
-**Per Page**
-- Clear primary keyword target
-- Title, H1, URL aligned
-- Content satisfies search intent
-- Not competing with other pages (cannibalization)
-
-**Site-Wide**
-- Keyword mapping document
-- No major gaps in coverage
-- No keyword cannibalization
-- Logical topical clusters
-
----
-
-## Content Quality Assessment
-
-### E-E-A-T Signals
-
-**Experience**
-- First-hand experience demonstrated
-- Original insights/data
-- Real examples and case studies
-
-**Expertise**
-- Author credentials visible
-- Accurate, detailed information
-- Properly sourced claims
-
-**Authoritativeness**
-- Recognized in the space
-- Cited by others
-- Industry credentials
-
-**Trustworthiness**
-- Accurate information
-- Transparent about business
-- Contact information available
-- Privacy policy, terms
-- Secure site (HTTPS)
-
-### Content Depth
-
-- Comprehensive coverage of topic
-- Answers follow-up questions
-- Better than top-ranking competitors
-- Updated and current
-
-### User Engagement Signals
-
-- Time on page
-- Bounce rate in context
-- Pages per session
-- Return visits
-
----
-
-## Common Issues by Site Type
-
-### SaaS/Product Sites
-- Product pages lack content depth
-- Blog not integrated with product pages
-- Missing comparison/alternative pages
-- Feature pages thin on content
-- No glossary/educational content
-
-### E-commerce
-- Thin category pages
-- Duplicate product descriptions
-- Missing product schema
-- Faceted navigation creating duplicates
-- Out-of-stock pages mishandled
-
-### Content/Blog Sites
-- Outdated content not refreshed
-- Keyword cannibalization
-- No topical clustering
-- Poor internal linking
-- Missing author pages
-
-### Local Business
-- Inconsistent NAP
-- Missing local schema
-- No Google Business Profile optimization
-- Missing location pages
-- No local content
-
----
-
-## Output Format
-
-### Audit Report Structure
-
-**Executive Summary**
-- Overall health assessment
-- Top 3-5 priority issues
-- Quick wins identified
-
-**Technical SEO Findings**
-For each issue:
-- **Issue**: What's wrong
-- **Impact**: SEO impact (High/Medium/Low)
-- **Evidence**: How you found it
-- **Fix**: Specific recommendation
-- **Priority**: 1-5 or High/Medium/Low
-
-**On-Page SEO Findings**
-Same format as above
-
-**Content Findings**
-Same format as above
-
-**Prioritized Action Plan**
-1. Critical fixes (blocking indexation/ranking)
-2. High-impact improvements
-3. Quick wins (easy, immediate benefit)
-4. Long-term recommendations
-
----
-
-## References
-
-- [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid (em dashes, overused phrases, filler words)
-- [AEO & GEO Patterns](references/aeo-geo-patterns.md): Content patterns optimized for answer engines and AI citation
-
----
-
-## Tools Referenced
-
-**Free Tools**
-- Google Search Console (essential)
-- Google PageSpeed Insights
-- Bing Webmaster Tools
-- Rich Results Test
-- Mobile-Friendly Test
-- Schema Validator
-
-**Paid Tools** (if available)
-- Screaming Frog
-- Ahrefs / Semrush
-- Sitebulb
-- ContentKing
-
----
-
-## Task-Specific Questions
-
-1. What pages/keywords matter most?
-2. Do you have Search Console access?
-3. Any recent changes or migrations?
-4. Who are your top organic competitors?
-5. What's your current organic traffic baseline?
-
----
-
-## Related Skills
-
-- **programmatic-seo**: For building SEO pages at scale
-- **schema-markup**: For implementing structured data
-- **page-cro**: For optimizing pages for conversion (not just ranking)
-- **analytics-tracking**: For measuring SEO performance
diff --git a/.agents/skills/seo-audit/references/aeo-geo-patterns.md b/.agents/skills/seo-audit/references/aeo-geo-patterns.md
deleted file mode 100644
index 9f4eb0907..000000000
--- a/.agents/skills/seo-audit/references/aeo-geo-patterns.md
+++ /dev/null
@@ -1,279 +0,0 @@
-# AEO and GEO Content Patterns
-
-Reusable content block patterns optimized for answer engines and AI citation.
-
----
-
-## Answer Engine Optimization (AEO) Patterns
-
-These patterns help content appear in featured snippets, AI Overviews, voice search results, and answer boxes.
-
-### Definition Block
-
-Use for "What is [X]?" queries.
-
-```markdown
-## What is [Term]?
-
-[Term] is [concise 1-sentence definition]. [Expanded 1-2 sentence explanation with key characteristics]. [Brief context on why it matters or how it's used].
-```
-
-**Example:**
-```markdown
-## What is Answer Engine Optimization?
-
-Answer Engine Optimization (AEO) is the practice of structuring content so AI-powered systems can easily extract and present it as direct answers to user queries. Unlike traditional SEO that focuses on ranking in search results, AEO optimizes for featured snippets, AI Overviews, and voice assistant responses. This approach has become essential as over 60% of Google searches now end without a click.
-```
-
-### Step-by-Step Block
-
-Use for "How to [X]" queries. Optimal for list snippets.
-
-```markdown
-## How to [Action/Goal]
-
-[1-sentence overview of the process]
-
-1. **[Step Name]**: [Clear action description in 1-2 sentences]
-2. **[Step Name]**: [Clear action description in 1-2 sentences]
-3. **[Step Name]**: [Clear action description in 1-2 sentences]
-4. **[Step Name]**: [Clear action description in 1-2 sentences]
-5. **[Step Name]**: [Clear action description in 1-2 sentences]
-
-[Optional: Brief note on expected outcome or time estimate]
-```
-
-**Example:**
-```markdown
-## How to Optimize Content for Featured Snippets
-
-Earning featured snippets requires strategic formatting and direct answers to search queries.
-
-1. **Identify snippet opportunities**: Use tools like Semrush or Ahrefs to find keywords where competitors have snippets you could capture.
-2. **Match the snippet format**: Analyze whether the current snippet is a paragraph, list, or table, and format your content accordingly.
-3. **Answer the question directly**: Provide a clear, concise answer (40-60 words for paragraph snippets) immediately after the question heading.
-4. **Add supporting context**: Expand on your answer with examples, data, and expert insights in the following paragraphs.
-5. **Use proper heading structure**: Place your target question as an H2 or H3, with the answer immediately following.
-
-Most featured snippets appear within 2-4 weeks of publishing well-optimized content.
-```
-
-### Comparison Table Block
-
-Use for "[X] vs [Y]" queries. Optimal for table snippets.
-
-```markdown
-## [Option A] vs [Option B]: [Brief Descriptor]
-
-| Feature | [Option A] | [Option B] |
-|---------|------------|------------|
-| [Criteria 1] | [Value/Description] | [Value/Description] |
-| [Criteria 2] | [Value/Description] | [Value/Description] |
-| [Criteria 3] | [Value/Description] | [Value/Description] |
-| [Criteria 4] | [Value/Description] | [Value/Description] |
-| Best For | [Use case] | [Use case] |
-
-**Bottom line**: [1-2 sentence recommendation based on different needs]
-```
-
-### Pros and Cons Block
-
-Use for evaluation queries: "Is [X] worth it?", "Should I [X]?"
-
-```markdown
-## Advantages and Disadvantages of [Topic]
-
-[1-sentence overview of the evaluation context]
-
-### Pros
-
-- **[Benefit category]**: [Specific explanation]
-- **[Benefit category]**: [Specific explanation]
-- **[Benefit category]**: [Specific explanation]
-
-### Cons
-
-- **[Drawback category]**: [Specific explanation]
-- **[Drawback category]**: [Specific explanation]
-- **[Drawback category]**: [Specific explanation]
-
-**Verdict**: [1-2 sentence balanced conclusion with recommendation]
-```
-
-### FAQ Block
-
-Use for topic pages with multiple common questions. Essential for FAQ schema.
-
-```markdown
-## Frequently Asked Questions
-
-### [Question phrased exactly as users search]?
-
-[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
-
-### [Question phrased exactly as users search]?
-
-[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
-
-### [Question phrased exactly as users search]?
-
-[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
-```
-
-**Tips for FAQ questions:**
-- Use natural question phrasing ("How do I..." not "How does one...")
-- Include question words: what, how, why, when, where, who, which
-- Match "People Also Ask" queries from search results
-- Keep answers between 50-100 words
-
-### Listicle Block
-
-Use for "Best [X]", "Top [X]", "[Number] ways to [X]" queries.
-
-```markdown
-## [Number] Best [Items] for [Goal/Purpose]
-
-[1-2 sentence intro establishing context and selection criteria]
-
-### 1. [Item Name]
-
-[Why it's included in 2-3 sentences with specific benefits]
-
-### 2. [Item Name]
-
-[Why it's included in 2-3 sentences with specific benefits]
-
-### 3. [Item Name]
-
-[Why it's included in 2-3 sentences with specific benefits]
-```
-
----
-
-## Generative Engine Optimization (GEO) Patterns
-
-These patterns optimize content for citation by AI assistants like ChatGPT, Claude, Perplexity, and Gemini.
-
-### Statistic Citation Block
-
-Statistics increase AI citation rates by 15-30%. Always include sources.
-
-```markdown
-[Claim statement]. According to [Source/Organization], [specific statistic with number and timeframe]. [Context for why this matters].
-```
-
-**Example:**
-```markdown
-Mobile optimization is no longer optional for SEO success. According to Google's 2024 Core Web Vitals report, 70% of web traffic now comes from mobile devices, and pages failing mobile usability standards see 24% higher bounce rates. This makes mobile-first indexing a critical ranking factor.
-```
-
-### Expert Quote Block
-
-Named expert attribution adds credibility and increases citation likelihood.
-
-```markdown
-"[Direct quote from expert]," says [Expert Name], [Title/Role] at [Organization]. [1 sentence of context or interpretation].
-```
-
-**Example:**
-```markdown
-"The shift from keyword-driven search to intent-driven discovery represents the most significant change in SEO since mobile-first indexing," says Rand Fishkin, Co-founder of SparkToro. This perspective highlights why content strategies must evolve beyond traditional keyword optimization.
-```
-
-### Authoritative Claim Block
-
-Structure claims for easy AI extraction with clear attribution.
-
-```markdown
-[Topic] [verb: is/has/requires/involves] [clear, specific claim]. [Source] [confirms/reports/found] that [supporting evidence]. This [explains/means/suggests] [implication or action].
-```
-
-**Example:**
-```markdown
-E-E-A-T is the cornerstone of Google's content quality evaluation. Google's Search Quality Rater Guidelines confirm that trust is the most critical factor, stating that "untrustworthy pages have low E-E-A-T no matter how experienced, expert, or authoritative they may seem." This means content creators must prioritize transparency and accuracy above all other optimization tactics.
-```
-
-### Self-Contained Answer Block
-
-Create quotable, standalone statements that AI can extract directly.
-
-```markdown
-**[Topic/Question]**: [Complete, self-contained answer that makes sense without additional context. Include specific details, numbers, or examples in 2-3 sentences.]
-```
-
-**Example:**
-```markdown
-**Ideal blog post length for SEO**: The optimal length for SEO blog posts is 1,500-2,500 words for competitive topics. This range allows comprehensive topic coverage while maintaining reader engagement. HubSpot research shows long-form content earns 77% more backlinks than short articles, directly impacting search rankings.
-```
-
-### Evidence Sandwich Block
-
-Structure claims with evidence for maximum credibility.
-
-```markdown
-[Opening claim statement].
-
-Evidence supporting this includes:
-- [Data point 1 with source]
-- [Data point 2 with source]
-- [Data point 3 with source]
-
-[Concluding statement connecting evidence to actionable insight].
-```
-
----
-
-## Domain-Specific GEO Tactics
-
-Different content domains benefit from different authority signals.
-
-### Technology Content
-- Emphasize technical precision and correct terminology
-- Include version numbers and dates for software/tools
-- Reference official documentation
-- Add code examples where relevant
-
-### Health/Medical Content
-- Cite peer-reviewed studies with publication details
-- Include expert credentials (MD, RN, etc.)
-- Note study limitations and context
-- Add "last reviewed" dates
-
-### Financial Content
-- Reference regulatory bodies (SEC, FTC, etc.)
-- Include specific numbers with timeframes
-- Note that information is educational, not advice
-- Cite recognized financial institutions
-
-### Legal Content
-- Cite specific laws, statutes, and regulations
-- Reference jurisdiction clearly
-- Include professional disclaimers
-- Note when professional consultation is advised
-
-### Business/Marketing Content
-- Include case studies with measurable results
-- Reference industry research and reports
-- Add percentage changes and timeframes
-- Quote recognized thought leaders
-
----
-
-## Voice Search Optimization
-
-Voice queries are conversational and question-based. Optimize for these patterns:
-
-### Question Formats for Voice
-- "What is..."
-- "How do I..."
-- "Where can I find..."
-- "Why does..."
-- "When should I..."
-- "Who is..."
-
-### Voice-Optimized Answer Structure
-- Lead with direct answer (under 30 words ideal)
-- Use natural, conversational language
-- Avoid jargon unless targeting expert audience
-- Include local context where relevant
-- Structure for single spoken response
diff --git a/.agents/skills/seo-audit/references/ai-writing-detection.md b/.agents/skills/seo-audit/references/ai-writing-detection.md
deleted file mode 100644
index ffa5dce80..000000000
--- a/.agents/skills/seo-audit/references/ai-writing-detection.md
+++ /dev/null
@@ -1,190 +0,0 @@
-# AI Writing Detection
-
-Words, phrases, and punctuation patterns commonly associated with AI-generated text. Avoid these to ensure writing sounds natural and human.
-
-Sources: Grammarly (2025), Microsoft 365 Life Hacks (2025), GPTHuman (2025), Walter Writes (2025), Textero (2025), Plagiarism Today (2025), Rolling Stone (2025), MDPI Blog (2025)
-
----
-
-## Em Dashes: The Primary AI Tell
-
-**The em dash (—) has become one of the most reliable markers of AI-generated content.**
-
-Em dashes are longer than hyphens (-) and are used for emphasis, interruptions, or parenthetical information. While they have legitimate uses in writing, AI models drastically overuse them.
-
-### Why Em Dashes Signal AI Writing
-- AI models were trained on edited books, academic papers, and style guides where em dashes appear frequently
-- AI uses em dashes as a shortcut for sentence variety instead of commas, colons, or parentheses
-- Most human writers rarely use em dashes because they don't exist as a standard keyboard key
-- The overuse is so consistent that it has become the unofficial signature of ChatGPT writing
-
-### What To Do Instead
-| Instead of | Use |
-|------------|-----|
-| The results—which were surprising—showed... | The results, which were surprising, showed... |
-| This approach—unlike traditional methods—allows... | This approach, unlike traditional methods, allows... |
-| The study found—as expected—that... | The study found, as expected, that... |
-| Communication skills—both written and verbal—are essential | Communication skills (both written and verbal) are essential |
-
-### Guidelines
-- Use commas for most parenthetical information
-- Use colons to introduce explanations or lists
-- Use parentheses for supplementary information
-- Reserve em dashes for rare, deliberate emphasis only
-- If you find yourself using more than one em dash per page, revise
-
----
-
-## Overused Verbs
-
-| Avoid | Use Instead |
-|-------|-------------|
-| delve (into) | explore, examine, investigate, look at |
-| leverage | use, apply, draw on |
-| optimise | improve, refine, enhance |
-| utilise | use |
-| facilitate | help, enable, support |
-| foster | encourage, support, develop, nurture |
-| bolster | strengthen, support, reinforce |
-| underscore | emphasise, highlight, stress |
-| unveil | reveal, show, introduce, present |
-| navigate | manage, handle, work through |
-| streamline | simplify, make more efficient |
-| enhance | improve, strengthen |
-| endeavour | try, attempt, effort |
-| ascertain | find out, determine, establish |
-| elucidate | explain, clarify, make clear |
-
----
-
-## Overused Adjectives
-
-| Avoid | Use Instead |
-|-------|-------------|
-| robust | strong, reliable, thorough, solid |
-| comprehensive | complete, thorough, full, detailed |
-| pivotal | key, critical, central, important |
-| crucial | important, key, essential, critical |
-| vital | important, essential, necessary |
-| transformative | significant, important, major |
-| cutting-edge | new, advanced, recent, modern |
-| groundbreaking | new, original, significant |
-| innovative | new, original, creative |
-| seamless | smooth, easy, effortless |
-| intricate | complex, detailed, complicated |
-| nuanced | subtle, complex, detailed |
-| multifaceted | complex, varied, diverse |
-| holistic | complete, whole, comprehensive |
-
----
-
-## Overused Transitions and Connectors
-
-| Avoid | Use Instead |
-|-------|-------------|
-| furthermore | also, in addition, and |
-| moreover | also, and, besides |
-| notwithstanding | despite, even so, still |
-| that being said | however, but, still |
-| at its core | essentially, fundamentally, basically |
-| to put it simply | in short, simply put |
-| it is worth noting that | note that, importantly |
-| in the realm of | in, within, regarding |
-| in the landscape of | in, within |
-| in today's [anything] | currently, now, today |
-
----
-
-## Phrases That Signal AI Writing
-
-### Opening Phrases to Avoid
-- "In today's fast-paced world..."
-- "In today's digital age..."
-- "In an era of..."
-- "In the ever-evolving landscape of..."
-- "In the realm of..."
-- "It's important to note that..."
-- "Let's delve into..."
-- "Imagine a world where..."
-
-### Transitional Phrases to Avoid
-- "That being said..."
-- "With that in mind..."
-- "It's worth mentioning that..."
-- "At its core..."
-- "To put it simply..."
-- "In essence..."
-- "This begs the question..."
-
-### Concluding Phrases to Avoid
-- "In conclusion..."
-- "To sum up..."
-- "By [doing X], you can [achieve Y]..."
-- "In the final analysis..."
-- "All things considered..."
-- "At the end of the day..."
-
-### Structural Patterns to Avoid
-- "Whether you're a [X], [Y], or [Z]..." (listing three examples after "whether")
-- "It's not just [X], it's also [Y]..."
-- "Think of [X] as [elaborate metaphor]..."
-- Starting sentences with "By" followed by a gerund: "By understanding X, you can Y..."
-
----
-
-## Filler Words and Empty Intensifiers
-
-These words often add nothing to meaning. Remove them or find specific alternatives:
-
-- absolutely
-- actually
-- basically
-- certainly
-- clearly
-- definitely
-- essentially
-- extremely
-- fundamentally
-- incredibly
-- interestingly
-- naturally
-- obviously
-- quite
-- really
-- significantly
-- simply
-- surely
-- truly
-- ultimately
-- undoubtedly
-- very
-
----
-
-## Academic-Specific AI Tells
-
-| Avoid | Use Instead |
-|-------|-------------|
-| shed light on | clarify, explain, reveal |
-| pave the way for | enable, allow, make possible |
-| a myriad of | many, numerous, various |
-| a plethora of | many, numerous, several |
-| paramount | very important, essential, critical |
-| pertaining to | about, regarding, concerning |
-| prior to | before |
-| subsequent to | after |
-| in light of | because of, given, considering |
-| with respect to | about, regarding, for |
-| in terms of | regarding, for, about |
-| the fact that | that (or rewrite sentence) |
-
----
-
-## How to Self-Check
-
-1. Read your text aloud. If phrases sound unnatural in speech, revise them
-2. Ask: "Would I say this in a conversation with a colleague?"
-3. Check for repetitive sentence structures
-4. Look for clusters of the words listed above
-5. Ensure varied sentence lengths (not all similar length)
-6. Verify each intensifier adds genuine meaning
diff --git a/.agents/skills/skill-creator/LICENSE.txt b/.agents/skills/skill-creator/LICENSE.txt
deleted file mode 100644
index 7a4a3ea24..000000000
--- a/.agents/skills/skill-creator/LICENSE.txt
+++ /dev/null
@@ -1,202 +0,0 @@
-
- Apache License
- Version 2.0, January 2004
- http://www.apache.org/licenses/
-
- TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
- 1. Definitions.
-
- "License" shall mean the terms and conditions for use, reproduction,
- and distribution as defined by Sections 1 through 9 of this document.
-
- "Licensor" shall mean the copyright owner or entity authorized by
- the copyright owner that is granting the License.
-
- "Legal Entity" shall mean the union of the acting entity and all
- other entities that control, are controlled by, or are under common
- control with that entity. For the purposes of this definition,
- "control" means (i) the power, direct or indirect, to cause the
- direction or management of such entity, whether by contract or
- otherwise, or (ii) ownership of fifty percent (50%) or more of the
- outstanding shares, or (iii) beneficial ownership of such entity.
-
- "You" (or "Your") shall mean an individual or Legal Entity
- exercising permissions granted by this License.
-
- "Source" form shall mean the preferred form for making modifications,
- including but not limited to software source code, documentation
- source, and configuration files.
-
- "Object" form shall mean any form resulting from mechanical
- transformation or translation of a Source form, including but
- not limited to compiled object code, generated documentation,
- and conversions to other media types.
-
- "Work" shall mean the work of authorship, whether in Source or
- Object form, made available under the License, as indicated by a
- copyright notice that is included in or attached to the work
- (an example is provided in the Appendix below).
-
- "Derivative Works" shall mean any work, whether in Source or Object
- form, that is based on (or derived from) the Work and for which the
- editorial revisions, annotations, elaborations, or other modifications
- represent, as a whole, an original work of authorship. For the purposes
- of this License, Derivative Works shall not include works that remain
- separable from, or merely link (or bind by name) to the interfaces of,
- the Work and Derivative Works thereof.
-
- "Contribution" shall mean any work of authorship, including
- the original version of the Work and any modifications or additions
- to that Work or Derivative Works thereof, that is intentionally
- submitted to Licensor for inclusion in the Work by the copyright owner
- or by an individual or Legal Entity authorized to submit on behalf of
- the copyright owner. For the purposes of this definition, "submitted"
- means any form of electronic, verbal, or written communication sent
- to the Licensor or its representatives, including but not limited to
- communication on electronic mailing lists, source code control systems,
- and issue tracking systems that are managed by, or on behalf of, the
- Licensor for the purpose of discussing and improving the Work, but
- excluding communication that is conspicuously marked or otherwise
- designated in writing by the copyright owner as "Not a Contribution."
-
- "Contributor" shall mean Licensor and any individual or Legal Entity
- on behalf of whom a Contribution has been received by Licensor and
- subsequently incorporated within the Work.
-
- 2. Grant of Copyright License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- copyright license to reproduce, prepare Derivative Works of,
- publicly display, publicly perform, sublicense, and distribute the
- Work and such Derivative Works in Source or Object form.
-
- 3. Grant of Patent License. Subject to the terms and conditions of
- this License, each Contributor hereby grants to You a perpetual,
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
- (except as stated in this section) patent license to make, have made,
- use, offer to sell, sell, import, and otherwise transfer the Work,
- where such license applies only to those patent claims licensable
- by such Contributor that are necessarily infringed by their
- Contribution(s) alone or by combination of their Contribution(s)
- with the Work to which such Contribution(s) was submitted. If You
- institute patent litigation against any entity (including a
- cross-claim or counterclaim in a lawsuit) alleging that the Work
- or a Contribution incorporated within the Work constitutes direct
- or contributory patent infringement, then any patent licenses
- granted to You under this License for that Work shall terminate
- as of the date such litigation is filed.
-
- 4. Redistribution. You may reproduce and distribute copies of the
- Work or Derivative Works thereof in any medium, with or without
- modifications, and in Source or Object form, provided that You
- meet the following conditions:
-
- (a) You must give any other recipients of the Work or
- Derivative Works a copy of this License; and
-
- (b) You must cause any modified files to carry prominent notices
- stating that You changed the files; and
-
- (c) You must retain, in the Source form of any Derivative Works
- that You distribute, all copyright, patent, trademark, and
- attribution notices from the Source form of the Work,
- excluding those notices that do not pertain to any part of
- the Derivative Works; and
-
- (d) If the Work includes a "NOTICE" text file as part of its
- distribution, then any Derivative Works that You distribute must
- include a readable copy of the attribution notices contained
- within such NOTICE file, excluding those notices that do not
- pertain to any part of the Derivative Works, in at least one
- of the following places: within a NOTICE text file distributed
- as part of the Derivative Works; within the Source form or
- documentation, if provided along with the Derivative Works; or,
- within a display generated by the Derivative Works, if and
- wherever such third-party notices normally appear. The contents
- of the NOTICE file are for informational purposes only and
- do not modify the License. You may add Your own attribution
- notices within Derivative Works that You distribute, alongside
- or as an addendum to the NOTICE text from the Work, provided
- that such additional attribution notices cannot be construed
- as modifying the License.
-
- You may add Your own copyright statement to Your modifications and
- may provide additional or different license terms and conditions
- for use, reproduction, or distribution of Your modifications, or
- for any such Derivative Works as a whole, provided Your use,
- reproduction, and distribution of the Work otherwise complies with
- the conditions stated in this License.
-
- 5. Submission of Contributions. Unless You explicitly state otherwise,
- any Contribution intentionally submitted for inclusion in the Work
- by You to the Licensor shall be under the terms and conditions of
- this License, without any additional terms or conditions.
- Notwithstanding the above, nothing herein shall supersede or modify
- the terms of any separate license agreement you may have executed
- with Licensor regarding such Contributions.
-
- 6. Trademarks. This License does not grant permission to use the trade
- names, trademarks, service marks, or product names of the Licensor,
- except as required for reasonable and customary use in describing the
- origin of the Work and reproducing the content of the NOTICE file.
-
- 7. Disclaimer of Warranty. Unless required by applicable law or
- agreed to in writing, Licensor provides the Work (and each
- Contributor provides its Contributions) on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied, including, without limitation, any warranties or conditions
- of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
- PARTICULAR PURPOSE. You are solely responsible for determining the
- appropriateness of using or redistributing the Work and assume any
- risks associated with Your exercise of permissions under this License.
-
- 8. Limitation of Liability. In no event and under no legal theory,
- whether in tort (including negligence), contract, or otherwise,
- unless required by applicable law (such as deliberate and grossly
- negligent acts) or agreed to in writing, shall any Contributor be
- liable to You for damages, including any direct, indirect, special,
- incidental, or consequential damages of any character arising as a
- result of this License or out of the use or inability to use the
- Work (including but not limited to damages for loss of goodwill,
- work stoppage, computer failure or malfunction, or any and all
- other commercial damages or losses), even if such Contributor
- has been advised of the possibility of such damages.
-
- 9. Accepting Warranty or Additional Liability. While redistributing
- the Work or Derivative Works thereof, You may choose to offer,
- and charge a fee for, acceptance of support, warranty, indemnity,
- or other liability obligations and/or rights consistent with this
- License. However, in accepting such obligations, You may act only
- on Your own behalf and on Your sole responsibility, not on behalf
- of any other Contributor, and only if You agree to indemnify,
- defend, and hold each Contributor harmless for any liability
- incurred by, or claims asserted against, such Contributor by reason
- of your accepting any such warranty or additional liability.
-
- END OF TERMS AND CONDITIONS
-
- APPENDIX: How to apply the Apache License to your work.
-
- To apply the Apache License to your work, attach the following
- boilerplate notice, with the fields enclosed by brackets "[]"
- replaced with your own identifying information. (Don't include
- the brackets!) The text should be enclosed in the appropriate
- comment syntax for the file format. We also recommend that a
- file or class name and description of purpose be included on the
- same "printed page" as the copyright notice for easier
- identification within third-party archives.
-
- Copyright [yyyy] [name of copyright owner]
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
\ No newline at end of file
diff --git a/.agents/skills/skill-creator/SKILL.md b/.agents/skills/skill-creator/SKILL.md
deleted file mode 100644
index b7f86598b..000000000
--- a/.agents/skills/skill-creator/SKILL.md
+++ /dev/null
@@ -1,356 +0,0 @@
----
-name: skill-creator
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
-license: Complete terms in LICENSE.txt
----
-
-# Skill Creator
-
-This skill provides guidance for creating effective skills.
-
-## About Skills
-
-Skills are modular, self-contained packages that extend Claude's capabilities by providing
-specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
-domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
-equipped with procedural knowledge that no model can fully possess.
-
-### What Skills Provide
-
-1. Specialized workflows - Multi-step procedures for specific domains
-2. Tool integrations - Instructions for working with specific file formats or APIs
-3. Domain expertise - Company-specific knowledge, schemas, business logic
-4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
-
-## Core Principles
-
-### Concise is Key
-
-The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
-
-**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
-
-Prefer concise examples over verbose explanations.
-
-### Set Appropriate Degrees of Freedom
-
-Match the level of specificity to the task's fragility and variability:
-
-**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
-
-**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
-
-**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
-
-Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
-
-### Anatomy of a Skill
-
-Every skill consists of a required SKILL.md file and optional bundled resources:
-
-```
-skill-name/
-├── SKILL.md (required)
-│ ├── YAML frontmatter metadata (required)
-│ │ ├── name: (required)
-│ │ └── description: (required)
-│ └── Markdown instructions (required)
-└── Bundled Resources (optional)
- ├── scripts/ - Executable code (Python/Bash/etc.)
- ├── references/ - Documentation intended to be loaded into context as needed
- └── assets/ - Files used in output (templates, icons, fonts, etc.)
-```
-
-#### SKILL.md (required)
-
-Every SKILL.md consists of:
-
-- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Claude reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
-- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
-
-#### Bundled Resources (optional)
-
-##### Scripts (`scripts/`)
-
-Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
-
-- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
-- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
-- **Benefits**: Token efficient, deterministic, may be executed without loading into context
-- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
-
-##### References (`references/`)
-
-Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
-
-- **When to include**: For documentation that Claude should reference while working
-- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
-- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
-- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
-- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
-- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
-
-##### Assets (`assets/`)
-
-Files not intended to be loaded into context, but rather used within the output Claude produces.
-
-- **When to include**: When the skill needs files that will be used in the final output
-- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
-- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
-- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
-
-#### What to Not Include in a Skill
-
-A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
-
-- README.md
-- INSTALLATION_GUIDE.md
-- QUICK_REFERENCE.md
-- CHANGELOG.md
-- etc.
-
-The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
-
-### Progressive Disclosure Design Principle
-
-Skills use a three-level loading system to manage context efficiently:
-
-1. **Metadata (name + description)** - Always in context (~100 words)
-2. **SKILL.md body** - When skill triggers (<5k words)
-3. **Bundled resources** - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
-
-#### Progressive Disclosure Patterns
-
-Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
-
-**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
-
-**Pattern 1: High-level guide with references**
-
-```markdown
-# PDF Processing
-
-## Quick start
-
-Extract text with pdfplumber:
-[code example]
-
-## Advanced features
-
-- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
-- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
-- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
-```
-
-Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
-
-**Pattern 2: Domain-specific organization**
-
-For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
-
-```
-bigquery-skill/
-├── SKILL.md (overview and navigation)
-└── reference/
- ├── finance.md (revenue, billing metrics)
- ├── sales.md (opportunities, pipeline)
- ├── product.md (API usage, features)
- └── marketing.md (campaigns, attribution)
-```
-
-When a user asks about sales metrics, Claude only reads sales.md.
-
-Similarly, for skills supporting multiple frameworks or variants, organize by variant:
-
-```
-cloud-deploy/
-├── SKILL.md (workflow + provider selection)
-└── references/
- ├── aws.md (AWS deployment patterns)
- ├── gcp.md (GCP deployment patterns)
- └── azure.md (Azure deployment patterns)
-```
-
-When the user chooses AWS, Claude only reads aws.md.
-
-**Pattern 3: Conditional details**
-
-Show basic content, link to advanced content:
-
-```markdown
-# DOCX Processing
-
-## Creating documents
-
-Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
-
-## Editing documents
-
-For simple edits, modify the XML directly.
-
-**For tracked changes**: See [REDLINING.md](REDLINING.md)
-**For OOXML details**: See [OOXML.md](OOXML.md)
-```
-
-Claude reads REDLINING.md or OOXML.md only when the user needs those features.
-
-**Important guidelines:**
-
-- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
-- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
-
-## Skill Creation Process
-
-Skill creation involves these steps:
-
-1. Understand the skill with concrete examples
-2. Plan reusable skill contents (scripts, references, assets)
-3. Initialize the skill (run init_skill.py)
-4. Edit the skill (implement resources and write SKILL.md)
-5. Package the skill (run package_skill.py)
-6. Iterate based on real usage
-
-Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
-
-### Step 1: Understanding the Skill with Concrete Examples
-
-Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
-
-To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
-
-For example, when building an image-editor skill, relevant questions include:
-
-- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
-- "Can you give some examples of how this skill would be used?"
-- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
-- "What would a user say that should trigger this skill?"
-
-To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
-
-Conclude this step when there is a clear sense of the functionality the skill should support.
-
-### Step 2: Planning the Reusable Skill Contents
-
-To turn concrete examples into an effective skill, analyze each example by:
-
-1. Considering how to execute on the example from scratch
-2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
-
-Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
-
-1. Rotating a PDF requires re-writing the same code each time
-2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
-
-Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
-
-1. Writing a frontend webapp requires the same boilerplate HTML/React each time
-2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
-
-Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
-
-1. Querying BigQuery requires re-discovering the table schemas and relationships each time
-2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
-
-To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
-
-### Step 3: Initializing the Skill
-
-At this point, it is time to actually create the skill.
-
-Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
-
-When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
-
-Usage:
-
-```bash
-scripts/init_skill.py <skill-name> --path <output-directory>
-```
-
-The script:
-
-- Creates the skill directory at the specified path
-- Generates a SKILL.md template with proper frontmatter and TODO placeholders
-- Creates example resource directories: `scripts/`, `references/`, and `assets/`
-- Adds example files in each directory that can be customized or deleted
-
-After initialization, customize or remove the generated SKILL.md and example files as needed.
-
-### Step 4: Edit the Skill
-
-When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
-
-#### Learn Proven Design Patterns
-
-Consult these helpful guides based on your skill's needs:
-
-- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
-- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
-
-These files contain established best practices for effective skill design.
-
-#### Start with Reusable Skill Contents
-
-To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
-
-Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
-
-Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
-
-#### Update SKILL.md
-
-**Writing Guidelines:** Always use imperative/infinitive form.
-
-##### Frontmatter
-
-Write the YAML frontmatter with `name` and `description`:
-
-- `name`: The skill name
-- `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
- - Include both what the Skill does and specific triggers/contexts for when to use it.
- - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
- - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
-
-Do not include any other fields in YAML frontmatter.
-
-##### Body
-
-Write instructions for using the skill and its bundled resources.
-
-### Step 5: Packaging a Skill
-
-Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
-
-```bash
-scripts/package_skill.py <path/to/skill-folder>
-```
-
-Optional output directory specification:
-
-```bash
-scripts/package_skill.py <path/to/skill-folder> ./dist
-```
-
-The packaging script will:
-
-1. **Validate** the skill automatically, checking:
-
- - YAML frontmatter format and required fields
- - Skill naming conventions and directory structure
- - Description completeness and quality
- - File organization and resource references
-
-2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
-
-If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
-
-### Step 6: Iterate
-
-After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
-
-**Iteration workflow:**
-
-1. Use the skill on real tasks
-2. Notice struggles or inefficiencies
-3. Identify how SKILL.md or bundled resources should be updated
-4. Implement changes and test again
diff --git a/.agents/skills/skill-creator/references/output-patterns.md b/.agents/skills/skill-creator/references/output-patterns.md
deleted file mode 100644
index 073ddda5f..000000000
--- a/.agents/skills/skill-creator/references/output-patterns.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Output Patterns
-
-Use these patterns when skills need to produce consistent, high-quality output.
-
-## Template Pattern
-
-Provide templates for output format. Match the level of strictness to your needs.
-
-**For strict requirements (like API responses or data formats):**
-
-```markdown
-## Report structure
-
-ALWAYS use this exact template structure:
-
-# [Analysis Title]
-
-## Executive summary
-[One-paragraph overview of key findings]
-
-## Key findings
-- Finding 1 with supporting data
-- Finding 2 with supporting data
-- Finding 3 with supporting data
-
-## Recommendations
-1. Specific actionable recommendation
-2. Specific actionable recommendation
-```
-
-**For flexible guidance (when adaptation is useful):**
-
-```markdown
-## Report structure
-
-Here is a sensible default format, but use your best judgment:
-
-# [Analysis Title]
-
-## Executive summary
-[Overview]
-
-## Key findings
-[Adapt sections based on what you discover]
-
-## Recommendations
-[Tailor to the specific context]
-
-Adjust sections as needed for the specific analysis type.
-```
-
-## Examples Pattern
-
-For skills where output quality depends on seeing examples, provide input/output pairs:
-
-```markdown
-## Commit message format
-
-Generate commit messages following these examples:
-
-**Example 1:**
-Input: Added user authentication with JWT tokens
-Output:
-```
-feat(auth): implement JWT-based authentication
-
-Add login endpoint and token validation middleware
-```
-
-**Example 2:**
-Input: Fixed bug where dates displayed incorrectly in reports
-Output:
-```
-fix(reports): correct date formatting in timezone conversion
-
-Use UTC timestamps consistently across report generation
-```
-
-Follow this style: type(scope): brief description, then detailed explanation.
-```
-
-Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
diff --git a/.agents/skills/skill-creator/references/workflows.md b/.agents/skills/skill-creator/references/workflows.md
deleted file mode 100644
index a350c3cc8..000000000
--- a/.agents/skills/skill-creator/references/workflows.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Workflow Patterns
-
-## Sequential Workflows
-
-For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:
-
-```markdown
-Filling a PDF form involves these steps:
-
-1. Analyze the form (run analyze_form.py)
-2. Create field mapping (edit fields.json)
-3. Validate mapping (run validate_fields.py)
-4. Fill the form (run fill_form.py)
-5. Verify output (run verify_output.py)
-```
-
-## Conditional Workflows
-
-For tasks with branching logic, guide Claude through decision points:
-
-```markdown
-1. Determine the modification type:
- **Creating new content?** → Follow "Creation workflow" below
- **Editing existing content?** → Follow "Editing workflow" below
-
-2. Creation workflow: [steps]
-3. Editing workflow: [steps]
-```
\ No newline at end of file
diff --git a/.agents/skills/skill-creator/scripts/init_skill.py b/.agents/skills/skill-creator/scripts/init_skill.py
deleted file mode 100755
index 329ad4e5a..000000000
--- a/.agents/skills/skill-creator/scripts/init_skill.py
+++ /dev/null
@@ -1,303 +0,0 @@
-#!/usr/bin/env python3
-"""
-Skill Initializer - Creates a new skill from template
-
-Usage:
- init_skill.py <skill-name> --path <path>
-
-Examples:
- init_skill.py my-new-skill --path skills/public
- init_skill.py my-api-helper --path skills/private
- init_skill.py custom-skill --path /custom/location
-"""
-
-import sys
-from pathlib import Path
-
-
-SKILL_TEMPLATE = """---
-name: {skill_name}
-description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
----
-
-# {skill_title}
-
-## Overview
-
-[TODO: 1-2 sentences explaining what this skill enables]
-
-## Structuring This Skill
-
-[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
-
-**1. Workflow-Based** (best for sequential processes)
-- Works well when there are clear step-by-step procedures
-- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
-- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
-
-**2. Task-Based** (best for tool collections)
-- Works well when the skill offers different operations/capabilities
-- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
-- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
-
-**3. Reference/Guidelines** (best for standards or specifications)
-- Works well for brand guidelines, coding standards, or requirements
-- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
-- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
-
-**4. Capabilities-Based** (best for integrated systems)
-- Works well when the skill provides multiple interrelated features
-- Example: Product Management with "Core Capabilities" → numbered capability list
-- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
-
-Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
-
-Delete this entire "Structuring This Skill" section when done - it's just guidance.]
-
-## [TODO: Replace with the first main section based on chosen structure]
-
-[TODO: Add content here. See examples in existing skills:
-- Code samples for technical skills
-- Decision trees for complex workflows
-- Concrete examples with realistic user requests
-- References to scripts/templates/references as needed]
-
-## Resources
-
-This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
-
-### scripts/
-Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
-
-**Examples from other skills:**
-- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
-- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
-
-**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
-
-**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
-
-### references/
-Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
-
-**Examples from other skills:**
-- Product management: `communication.md`, `context_building.md` - detailed workflow guides
-- BigQuery: API reference documentation and query examples
-- Finance: Schema documentation, company policies
-
-**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
-
-### assets/
-Files not intended to be loaded into context, but rather used within the output Claude produces.
-
-**Examples from other skills:**
-- Brand styling: PowerPoint template files (.pptx), logo files
-- Frontend builder: HTML/React boilerplate project directories
-- Typography: Font files (.ttf, .woff2)
-
-**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
-
----
-
-**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
-"""
-
-EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
-"""
-Example helper script for {skill_name}
-
-This is a placeholder script that can be executed directly.
-Replace with actual implementation or delete if not needed.
-
-Example real scripts from other skills:
-- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
-- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
-"""
-
-def main():
- print("This is an example script for {skill_name}")
- # TODO: Add actual script logic here
- # This could be data processing, file conversion, API calls, etc.
-
-if __name__ == "__main__":
- main()
-'''
-
-EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
-
-This is a placeholder for detailed reference documentation.
-Replace with actual reference content or delete if not needed.
-
-Example real reference docs from other skills:
-- product-management/references/communication.md - Comprehensive guide for status updates
-- product-management/references/context_building.md - Deep-dive on gathering context
-- bigquery/references/ - API references and query examples
-
-## When Reference Docs Are Useful
-
-Reference docs are ideal for:
-- Comprehensive API documentation
-- Detailed workflow guides
-- Complex multi-step processes
-- Information too lengthy for main SKILL.md
-- Content that's only needed for specific use cases
-
-## Structure Suggestions
-
-### API Reference Example
-- Overview
-- Authentication
-- Endpoints with examples
-- Error codes
-- Rate limits
-
-### Workflow Guide Example
-- Prerequisites
-- Step-by-step instructions
-- Common patterns
-- Troubleshooting
-- Best practices
-"""
-
-EXAMPLE_ASSET = """# Example Asset File
-
-This placeholder represents where asset files would be stored.
-Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
-
-Asset files are NOT intended to be loaded into context, but rather used within
-the output Claude produces.
-
-Example asset files from other skills:
-- Brand guidelines: logo.png, slides_template.pptx
-- Frontend builder: hello-world/ directory with HTML/React boilerplate
-- Typography: custom-font.ttf, font-family.woff2
-- Data: sample_data.csv, test_dataset.json
-
-## Common Asset Types
-
-- Templates: .pptx, .docx, boilerplate directories
-- Images: .png, .jpg, .svg, .gif
-- Fonts: .ttf, .otf, .woff, .woff2
-- Boilerplate code: Project directories, starter files
-- Icons: .ico, .svg
-- Data files: .csv, .json, .xml, .yaml
-
-Note: This is a text placeholder. Actual assets can be any file type.
-"""
-
-
-def title_case_skill_name(skill_name):
- """Convert hyphenated skill name to Title Case for display."""
- return ' '.join(word.capitalize() for word in skill_name.split('-'))
-
-
-def init_skill(skill_name, path):
- """
- Initialize a new skill directory with template SKILL.md.
-
- Args:
- skill_name: Name of the skill
- path: Path where the skill directory should be created
-
- Returns:
- Path to created skill directory, or None if error
- """
- # Determine skill directory path
- skill_dir = Path(path).resolve() / skill_name
-
- # Check if directory already exists
- if skill_dir.exists():
- print(f"❌ Error: Skill directory already exists: {skill_dir}")
- return None
-
- # Create skill directory
- try:
- skill_dir.mkdir(parents=True, exist_ok=False)
- print(f"✅ Created skill directory: {skill_dir}")
- except Exception as e:
- print(f"❌ Error creating directory: {e}")
- return None
-
- # Create SKILL.md from template
- skill_title = title_case_skill_name(skill_name)
- skill_content = SKILL_TEMPLATE.format(
- skill_name=skill_name,
- skill_title=skill_title
- )
-
- skill_md_path = skill_dir / 'SKILL.md'
- try:
- skill_md_path.write_text(skill_content)
- print("✅ Created SKILL.md")
- except Exception as e:
- print(f"❌ Error creating SKILL.md: {e}")
- return None
-
- # Create resource directories with example files
- try:
- # Create scripts/ directory with example script
- scripts_dir = skill_dir / 'scripts'
- scripts_dir.mkdir(exist_ok=True)
- example_script = scripts_dir / 'example.py'
- example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
- example_script.chmod(0o755)
- print("✅ Created scripts/example.py")
-
- # Create references/ directory with example reference doc
- references_dir = skill_dir / 'references'
- references_dir.mkdir(exist_ok=True)
- example_reference = references_dir / 'api_reference.md'
- example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
- print("✅ Created references/api_reference.md")
-
- # Create assets/ directory with example asset placeholder
- assets_dir = skill_dir / 'assets'
- assets_dir.mkdir(exist_ok=True)
- example_asset = assets_dir / 'example_asset.txt'
- example_asset.write_text(EXAMPLE_ASSET)
- print("✅ Created assets/example_asset.txt")
- except Exception as e:
- print(f"❌ Error creating resource directories: {e}")
- return None
-
- # Print next steps
- print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
- print("\nNext steps:")
- print("1. Edit SKILL.md to complete the TODO items and update the description")
- print("2. Customize or delete the example files in scripts/, references/, and assets/")
- print("3. Run the validator when ready to check the skill structure")
-
- return skill_dir
-
-
-def main():
- if len(sys.argv) < 4 or sys.argv[2] != '--path':
- print("Usage: init_skill.py <skill-name> --path <path>")
- print("\nSkill name requirements:")
- print(" - Hyphen-case identifier (e.g., 'data-analyzer')")
- print(" - Lowercase letters, digits, and hyphens only")
- print(" - Max 40 characters")
- print(" - Must match directory name exactly")
- print("\nExamples:")
- print(" init_skill.py my-new-skill --path skills/public")
- print(" init_skill.py my-api-helper --path skills/private")
- print(" init_skill.py custom-skill --path /custom/location")
- sys.exit(1)
-
- skill_name = sys.argv[1]
- path = sys.argv[3]
-
- print(f"🚀 Initializing skill: {skill_name}")
- print(f" Location: {path}")
- print()
-
- result = init_skill(skill_name, path)
-
- if result:
- sys.exit(0)
- else:
- sys.exit(1)
-
-
-if __name__ == "__main__":
- main()
diff --git a/.agents/skills/skill-creator/scripts/package_skill.py b/.agents/skills/skill-creator/scripts/package_skill.py
deleted file mode 100755
index 5cd36cb16..000000000
--- a/.agents/skills/skill-creator/scripts/package_skill.py
+++ /dev/null
@@ -1,110 +0,0 @@
-#!/usr/bin/env python3
-"""
-Skill Packager - Creates a distributable .skill file of a skill folder
-
-Usage:
- python utils/package_skill.py <path/to/skill-folder> [output-directory]
-
-Example:
- python utils/package_skill.py skills/public/my-skill
- python utils/package_skill.py skills/public/my-skill ./dist
-"""
-
-import sys
-import zipfile
-from pathlib import Path
-from quick_validate import validate_skill
-
-
-def package_skill(skill_path, output_dir=None):
- """
- Package a skill folder into a .skill file.
-
- Args:
- skill_path: Path to the skill folder
- output_dir: Optional output directory for the .skill file (defaults to current directory)
-
- Returns:
- Path to the created .skill file, or None if error
- """
- skill_path = Path(skill_path).resolve()
-
- # Validate skill folder exists
- if not skill_path.exists():
- print(f"❌ Error: Skill folder not found: {skill_path}")
- return None
-
- if not skill_path.is_dir():
- print(f"❌ Error: Path is not a directory: {skill_path}")
- return None
-
- # Validate SKILL.md exists
- skill_md = skill_path / "SKILL.md"
- if not skill_md.exists():
- print(f"❌ Error: SKILL.md not found in {skill_path}")
- return None
-
- # Run validation before packaging
- print("🔍 Validating skill...")
- valid, message = validate_skill(skill_path)
- if not valid:
- print(f"❌ Validation failed: {message}")
- print(" Please fix the validation errors before packaging.")
- return None
- print(f"✅ {message}\n")
-
- # Determine output location
- skill_name = skill_path.name
- if output_dir:
- output_path = Path(output_dir).resolve()
- output_path.mkdir(parents=True, exist_ok=True)
- else:
- output_path = Path.cwd()
-
- skill_filename = output_path / f"{skill_name}.skill"
-
- # Create the .skill file (zip format)
- try:
- with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
- # Walk through the skill directory
- for file_path in skill_path.rglob('*'):
- if file_path.is_file():
- # Calculate the relative path within the zip
- arcname = file_path.relative_to(skill_path.parent)
- zipf.write(file_path, arcname)
- print(f" Added: {arcname}")
-
- print(f"\n✅ Successfully packaged skill to: {skill_filename}")
- return skill_filename
-
- except Exception as e:
- print(f"❌ Error creating .skill file: {e}")
- return None
-
-
-def main():
- if len(sys.argv) < 2:
- print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
- print("\nExample:")
- print(" python utils/package_skill.py skills/public/my-skill")
- print(" python utils/package_skill.py skills/public/my-skill ./dist")
- sys.exit(1)
-
- skill_path = sys.argv[1]
- output_dir = sys.argv[2] if len(sys.argv) > 2 else None
-
- print(f"📦 Packaging skill: {skill_path}")
- if output_dir:
- print(f" Output directory: {output_dir}")
- print()
-
- result = package_skill(skill_path, output_dir)
-
- if result:
- sys.exit(0)
- else:
- sys.exit(1)
-
-
-if __name__ == "__main__":
- main()
diff --git a/.agents/skills/skill-creator/scripts/quick_validate.py b/.agents/skills/skill-creator/scripts/quick_validate.py
deleted file mode 100755
index d9fbeb75e..000000000
--- a/.agents/skills/skill-creator/scripts/quick_validate.py
+++ /dev/null
@@ -1,95 +0,0 @@
-#!/usr/bin/env python3
-"""
-Quick validation script for skills - minimal version
-"""
-
-import sys
-import os
-import re
-import yaml
-from pathlib import Path
-
-def validate_skill(skill_path):
- """Basic validation of a skill"""
- skill_path = Path(skill_path)
-
- # Check SKILL.md exists
- skill_md = skill_path / 'SKILL.md'
- if not skill_md.exists():
- return False, "SKILL.md not found"
-
- # Read and validate frontmatter
- content = skill_md.read_text()
- if not content.startswith('---'):
- return False, "No YAML frontmatter found"
-
- # Extract frontmatter
- match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
- if not match:
- return False, "Invalid frontmatter format"
-
- frontmatter_text = match.group(1)
-
- # Parse YAML frontmatter
- try:
- frontmatter = yaml.safe_load(frontmatter_text)
- if not isinstance(frontmatter, dict):
- return False, "Frontmatter must be a YAML dictionary"
- except yaml.YAMLError as e:
- return False, f"Invalid YAML in frontmatter: {e}"
-
- # Define allowed properties
- ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}
-
- # Check for unexpected properties (excluding nested keys under metadata)
- unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
- if unexpected_keys:
- return False, (
- f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
- f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
- )
-
- # Check required fields
- if 'name' not in frontmatter:
- return False, "Missing 'name' in frontmatter"
- if 'description' not in frontmatter:
- return False, "Missing 'description' in frontmatter"
-
- # Extract name for validation
- name = frontmatter.get('name', '')
- if not isinstance(name, str):
- return False, f"Name must be a string, got {type(name).__name__}"
- name = name.strip()
- if name:
- # Check naming convention (hyphen-case: lowercase with hyphens)
- if not re.match(r'^[a-z0-9-]+$', name):
- return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
- if name.startswith('-') or name.endswith('-') or '--' in name:
- return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
- # Check name length (max 64 characters per spec)
- if len(name) > 64:
- return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
-
- # Extract and validate description
- description = frontmatter.get('description', '')
- if not isinstance(description, str):
- return False, f"Description must be a string, got {type(description).__name__}"
- description = description.strip()
- if description:
- # Check for angle brackets
- if '<' in description or '>' in description:
- return False, "Description cannot contain angle brackets (< or >)"
- # Check description length (max 1024 characters per spec)
- if len(description) > 1024:
- return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
-
- return True, "Skill is valid!"
-
-if __name__ == "__main__":
- if len(sys.argv) != 2:
- print("Usage: python quick_validate.py <skill_directory>")
- sys.exit(1)
-
- valid, message = validate_skill(sys.argv[1])
- print(message)
- sys.exit(0 if valid else 1)
\ No newline at end of file
diff --git a/.agents/skills/vercel-composition-patterns/AGENTS.md b/.agents/skills/vercel-composition-patterns/AGENTS.md
deleted file mode 100644
index 558bf9aa1..000000000
--- a/.agents/skills/vercel-composition-patterns/AGENTS.md
+++ /dev/null
@@ -1,946 +0,0 @@
-# React Composition Patterns
-
-**Version 1.0.0**
-Engineering
-January 2026
-
-> **Note:**
-> This document is mainly for agents and LLMs to follow when maintaining,
-> generating, or refactoring React codebases using composition. Humans
-> may also find it useful, but guidance here is optimized for automation
-> and consistency by AI-assisted workflows.
-
----
-
-## Abstract
-
-Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.
-
----
-
-## Table of Contents
-
-1. [Component Architecture](#1-component-architecture) — **HIGH**
- - 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)
- - 1.2 [Use Compound Components](#12-use-compound-components)
-2. [State Management](#2-state-management) — **MEDIUM**
- - 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)
- - 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)
- - 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)
-3. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**
- - 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)
- - 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)
-4. [React 19 APIs](#4-react-19-apis) — **MEDIUM**
- - 4.1 [React 19 API Changes](#41-react-19-api-changes)
-
----
-
-## 1. Component Architecture
-
-**Impact: HIGH**
-
-Fundamental patterns for structuring components to avoid prop
-proliferation and enable flexible composition.
-
-### 1.1 Avoid Boolean Prop Proliferation
-
-**Impact: CRITICAL (prevents unmaintainable component variants)**
-
-Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
-
-component behavior. Each boolean doubles possible states and creates
-
-unmaintainable conditional logic. Use composition instead.
-
-**Incorrect: boolean props create exponential complexity**
-
-```tsx
-function Composer({
- onSubmit,
- isThread,
- channelId,
- isDMThread,
- dmId,
- isEditing,
- isForwarding,
-}: Props) {
- return (
- <form>
- <Header />
- <Input />
- {isDMThread ? (
- <AlsoSendToDMField id={dmId} />
- ) : isThread ? (
- <AlsoSendToChannelField id={channelId} />
- ) : null}
- {isEditing ? (
- <EditActions />
- ) : isForwarding ? (
- <ForwardActions />
- ) : (
- <DefaultActions />
- )}
- <Footer onSubmit={onSubmit} />
- </form>
- )
-}
-```
-
-**Correct: composition eliminates conditionals**
-
-```tsx
-// Channel composer
-function ChannelComposer() {
- return (
- <Composer.Frame>
- <Composer.Header />
- <Composer.Input />
- <Composer.Footer>
- <Composer.Attachments />
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
- )
-}
-
-// Thread composer - adds "also send to channel" field
-function ThreadComposer({ channelId }: { channelId: string }) {
- return (
- <Composer.Frame>
- <Composer.Header />
- <Composer.Input />
- <AlsoSendToChannelField id={channelId} />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
- )
-}
-
-// Edit composer - different footer actions
-function EditComposer() {
- return (
- <Composer.Frame>
- <Composer.Input />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.CancelEdit />
- <Composer.SaveEdit />
- </Composer.Footer>
- </Composer.Frame>
- )
-}
-```
-
-Each variant is explicit about what it renders. We can share internals without
-
-sharing a single monolithic parent.
-
-### 1.2 Use Compound Components
-
-**Impact: HIGH (enables flexible composition without prop drilling)**
-
-Structure complex components as compound components with a shared context. Each
-
-subcomponent accesses shared state via context, not props. Consumers compose the
-
-pieces they need.
-
-**Incorrect: monolithic component with render props**
-
-```tsx
-function Composer({
- renderHeader,
- renderFooter,
- renderActions,
- showAttachments,
- showFormatting,
- showEmojis,
-}: Props) {
- return (
- <form>
- {renderHeader?.()}
- <Input />
- {showAttachments && <Attachments />}
- {renderFooter ? (
- renderFooter()
- ) : (
- <Footer>
- {showFormatting && <Formatting />}
- {showEmojis && <Emojis />}
- {renderActions?.()}
- </Footer>
- )}
- </form>
- )
-}
-```
-
-**Correct: compound components with shared context**
-
-```tsx
-const ComposerContext = createContext<ComposerContextValue | null>(null)
-
-function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
- return (
- <ComposerContext value={{ state, actions, meta }}>
- {children}
- </ComposerContext>
- )
-}
-
-function ComposerFrame({ children }: { children: React.ReactNode }) {
- return <form>{children}</form>
-}
-
-function ComposerInput() {
- const {
- state,
- actions: { update },
- meta: { inputRef },
- } = use(ComposerContext)
- return (
- <TextInput
- ref={inputRef}
- value={state.input}
- onChangeText={(text) => update((s) => ({ ...s, input: text }))}
- />
- )
-}
-
-function ComposerSubmit() {
- const {
- actions: { submit },
- } = use(ComposerContext)
- return <Button onPress={submit}>Send</Button>
-}
-
-// Export as compound component
-const Composer = {
- Provider: ComposerProvider,
- Frame: ComposerFrame,
- Input: ComposerInput,
- Submit: ComposerSubmit,
- Header: ComposerHeader,
- Footer: ComposerFooter,
- Attachments: ComposerAttachments,
- Formatting: ComposerFormatting,
- Emojis: ComposerEmojis,
-}
-```
-
-**Usage:**
-
-```tsx
-<Composer.Provider state={state} actions={actions} meta={meta}>
- <Composer.Frame>
- <Composer.Header />
- <Composer.Input />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
-</Composer.Provider>
-```
-
-Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
-
----
-
-## 2. State Management
-
-**Impact: MEDIUM**
-
-Patterns for lifting state and managing shared context across
-composed components.
-
-### 2.1 Decouple State Management from UI
-
-**Impact: MEDIUM (enables swapping state implementations without changing UI)**
-
-The provider component should be the only place that knows how state is managed.
-
-UI components consume the context interface—they don't know if state comes from
-
-useState, Zustand, or a server sync.
-
-**Incorrect: UI coupled to state implementation**
-
-```tsx
-function ChannelComposer({ channelId }: { channelId: string }) {
- // UI component knows about global state implementation
- const state = useGlobalChannelState(channelId)
- const { submit, updateInput } = useChannelSync(channelId)
-
- return (
- <Composer.Frame>
- <Composer.Input
- value={state.input}
- onChange={(text) => sync.updateInput(text)}
- />
- <Composer.Submit onPress={() => sync.submit()} />
- </Composer.Frame>
- )
-}
-```
-
-**Correct: state management isolated in provider**
-
-```tsx
-// Provider handles all state management details
-function ChannelProvider({
- channelId,
- children,
-}: {
- channelId: string
- children: React.ReactNode
-}) {
- const { state, update, submit } = useGlobalChannel(channelId)
- const inputRef = useRef(null)
-
- return (
- <Composer.Provider
- state={state}
- actions={{ update, submit }}
- meta={{ inputRef }}
- >
- {children}
- </Composer.Provider>
- )
-}
-
-// UI component only knows about the context interface
-function ChannelComposer() {
- return (
- <Composer.Frame>
- <Composer.Header />
- <Composer.Input />
- <Composer.Footer>
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
- )
-}
-
-// Usage
-function Channel({ channelId }: { channelId: string }) {
- return (
- <ChannelProvider channelId={channelId}>
- <ChannelComposer />
- </ChannelProvider>
- )
-}
-```
-
-**Different providers, same UI:**
-
-```tsx
-// Local state for ephemeral forms
-function ForwardMessageProvider({ children }) {
- const [state, setState] = useState(initialState)
- const forwardMessage = useForwardMessage()
-
- return (
- <Composer.Provider
- state={state}
- actions={{ update: setState, submit: forwardMessage }}
- >
- {children}
- </Composer.Provider>
- )
-}
-
-// Global synced state for channels
-function ChannelProvider({ channelId, children }) {
- const { state, update, submit } = useGlobalChannel(channelId)
-
- return (
- <Composer.Provider state={state} actions={{ update, submit }}>
- {children}
- </Composer.Provider>
- )
-}
-```
-
-The same `Composer.Input` component works with both providers because it only
-
-depends on the context interface, not the implementation.
-
-### 2.2 Define Generic Context Interfaces for Dependency Injection
-
-**Impact: HIGH (enables dependency-injectable state across use-cases)**
-
-Define a **generic interface** for your component context with three parts:
-
-`state`, `actions`, and `meta`. This interface is a contract that any provider
-
-can implement—enabling the same UI components to work with completely different
-
-state implementations.
-
-**Core principle:** Lift state, compose internals, make state
-
-dependency-injectable.
-
-**Incorrect: UI coupled to specific state implementation**
-
-```tsx
-function ComposerInput() {
- // Tightly coupled to a specific hook
- const { input, setInput } = useChannelComposerState()
- return <TextInput value={input} onChangeText={setInput} />
-}
-```
-
-**Correct: generic interface enables dependency injection**
-
-```tsx
-// Define a GENERIC interface that any provider can implement
-interface ComposerState {
- input: string
- attachments: Attachment[]
- isSubmitting: boolean
-}
-
-interface ComposerActions {
- update: (updater: (state: ComposerState) => ComposerState) => void
- submit: () => void
-}
-
-interface ComposerMeta {
- inputRef: React.RefObject<TextInput>
-}
-
-interface ComposerContextValue {
- state: ComposerState
- actions: ComposerActions
- meta: ComposerMeta
-}
-
-const ComposerContext = createContext<ComposerContextValue | null>(null)
-```
-
-**UI components consume the interface, not the implementation:**
-
-```tsx
-function ComposerInput() {
- const {
- state,
- actions: { update },
- meta,
- } = use(ComposerContext)
-
- // This component works with ANY provider that implements the interface
- return (
- <TextInput
- ref={meta.inputRef}
- value={state.input}
- onChangeText={(text) => update((s) => ({ ...s, input: text }))}
- />
- )
-}
-```
-
-**Different providers implement the same interface:**
-
-```tsx
-// Provider A: Local state for ephemeral forms
-function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
- const [state, setState] = useState(initialState)
- const inputRef = useRef(null)
- const submit = useForwardMessage()
-
- return (
- <ComposerContext
- value={{
- state,
- actions: { update: setState, submit },
- meta: { inputRef },
- }}
- >
- {children}
- </ComposerContext>
- )
-}
-
-// Provider B: Global synced state for channels
-function ChannelProvider({ channelId, children }: Props) {
- const { state, update, submit } = useGlobalChannel(channelId)
- const inputRef = useRef(null)
-
- return (
- <ComposerContext
- value={{
- state,
- actions: { update, submit },
- meta: { inputRef },
- }}
- >
- {children}
- </ComposerContext>
- )
-}
-```
-
-**The same composed UI works with both:**
-
-```tsx
-// Works with ForwardMessageProvider (local state)
-<ForwardMessageProvider>
- <Composer.Frame>
- <Composer.Input />
- <Composer.Submit />
- </Composer.Frame>
-</ForwardMessageProvider>
-
-// Works with ChannelProvider (global synced state)
-<ChannelProvider channelId="abc">
- <Composer.Frame>
- <Composer.Input />
- <Composer.Submit />
- </Composer.Frame>
-</ChannelProvider>
-```
-
-**Custom UI outside the component can access state and actions:**
-
-```tsx
-function ForwardMessageDialog() {
- return (
- <ForwardMessageProvider>
- <Dialog>
- {/* The composer UI */}
- <Composer.Frame>
- <Composer.Input placeholder="Add a message, if you'd like." />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- </Composer.Footer>
- </Composer.Frame>
-
- {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
- <MessagePreview />
-
- {/* Actions at the bottom of the dialog */}
- <DialogActions>
- <CancelButton />
- <ForwardButton />
- </DialogActions>
- </Dialog>
- </ForwardMessageProvider>
- )
-}
-
-// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
-function ForwardButton() {
- const {
- actions: { submit },
- } = use(ComposerContext)
- return <Button onPress={submit}>Forward</Button>
-}
-
-// This preview lives OUTSIDE Composer.Frame but can read composer's state!
-function MessagePreview() {
- const { state } = use(ComposerContext)
- return <Preview message={state.input} attachments={state.attachments} />
-}
-```
-
-The provider boundary is what matters—not the visual nesting. Components that
-
-need shared state don't have to be inside the `Composer.Frame`. They just need
-
-to be within the provider.
-
-The `ForwardButton` and `MessagePreview` are not visually inside the composer
-
-box, but they can still access its state and actions. This is the power of
-
-lifting state into providers.
-
-The UI is reusable bits you compose together. The state is dependency-injected
-
-by the provider. Swap the provider, keep the UI.
-
-### 2.3 Lift State into Provider Components
-
-**Impact: HIGH (enables state sharing outside component boundaries)**
-
-Move state management into dedicated provider components. This allows sibling
-
-components outside the main UI to access and modify state without prop drilling
-
-or awkward refs.
-
-**Incorrect: state trapped inside component**
-
-```tsx
-function ForwardMessageComposer() {
- const [state, setState] = useState(initialState)
- const forwardMessage = useForwardMessage()
-
- return (
- <Composer.Frame>
- <Composer.Input />
- <Composer.Footer />
- </Composer.Frame>
- )
-}
-
-// Problem: How does this button access composer state?
-function ForwardMessageDialog() {
- return (
- <Dialog>
- <ForwardMessageComposer />
- <MessagePreview /> {/* Needs composer state */}
- <DialogActions>
- <CancelButton />
- <ForwardButton /> {/* Needs to call submit */}
- </DialogActions>
- </Dialog>
- )
-}
-```
-
-**Incorrect: useEffect to sync state up**
-
-```tsx
-function ForwardMessageDialog() {
- const [input, setInput] = useState('')
- return (
- <Dialog>
- <ForwardMessageComposer onInputChange={setInput} />
- <MessagePreview input={input} />
- </Dialog>
- )
-}
-
-function ForwardMessageComposer({ onInputChange }) {
- const [state, setState] = useState(initialState)
- useEffect(() => {
- onInputChange(state.input) // Sync on every change 😬
- }, [state.input])
-}
-```
-
-**Incorrect: reading state from ref on submit**
-
-```tsx
-function ForwardMessageDialog() {
- const stateRef = useRef(null)
- return (
- <Dialog>
- <ForwardMessageComposer stateRef={stateRef} />
- <ForwardButton onPress={() => submit(stateRef.current)} />
- </Dialog>
- )
-}
-```
-
-**Correct: state lifted to provider**
-
-```tsx
-function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
- const [state, setState] = useState(initialState)
- const forwardMessage = useForwardMessage()
- const inputRef = useRef(null)
-
- return (
- <Composer.Provider
- state={state}
- actions={{ update: setState, submit: forwardMessage }}
- meta={{ inputRef }}
- >
- {children}
- </Composer.Provider>
- )
-}
-
-function ForwardMessageDialog() {
- return (
- <ForwardMessageProvider>
- <Dialog>
- <ForwardMessageComposer />
- <MessagePreview /> {/* Custom components can access state and actions */}
- <DialogActions>
- <CancelButton />
- <ForwardButton /> {/* Custom components can access state and actions */}
- </DialogActions>
- </Dialog>
- </ForwardMessageProvider>
- )
-}
-
-function ForwardButton() {
- const { actions } = use(Composer.Context)
- return <Button onPress={actions.submit}>Forward</Button>
-}
-```
-
-The ForwardButton lives outside the Composer.Frame but still has access to the
-
-submit action because it's within the provider. Even though it's a one-off
-
-component, it can still access the composer's state and actions from outside the
-
-UI itself.
-
-**Key insight:** Components that need shared state don't have to be visually
-
-nested inside each other—they just need to be within the same provider.
-
----
-
-## 3. Implementation Patterns
-
-**Impact: MEDIUM**
-
-Specific techniques for implementing compound components and
-context providers.
-
-### 3.1 Create Explicit Component Variants
-
-**Impact: MEDIUM (self-documenting code, no hidden conditionals)**
-
-Instead of one component with many boolean props, create explicit variant
-
-components. Each variant composes the pieces it needs. The code documents
-
-itself.
-
-**Incorrect: one component, many modes**
-
-```tsx
-// What does this component actually render?
-<Composer
- isThread
- isEditing={false}
- channelId='abc'
- showAttachments
- showFormatting={false}
-/>
-```
-
-**Correct: explicit variants**
-
-```tsx
-// Immediately clear what this renders
-<ThreadComposer channelId="abc" />
-
-// Or
-<EditMessageComposer messageId="xyz" />
-
-// Or
-<ForwardMessageComposer messageId="123" />
-```
-
-Each implementation is unique, explicit and self-contained. Yet they can each
-
-use shared parts.
-
-**Implementation:**
-
-```tsx
-function ThreadComposer({ channelId }: { channelId: string }) {
- return (
- <ThreadProvider channelId={channelId}>
- <Composer.Frame>
- <Composer.Input />
- <AlsoSendToChannelField channelId={channelId} />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
- </ThreadProvider>
- )
-}
-
-function EditMessageComposer({ messageId }: { messageId: string }) {
- return (
- <EditMessageProvider messageId={messageId}>
- <Composer.Frame>
- <Composer.Input />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.CancelEdit />
- <Composer.SaveEdit />
- </Composer.Footer>
- </Composer.Frame>
- </EditMessageProvider>
- )
-}
-
-function ForwardMessageComposer({ messageId }: { messageId: string }) {
- return (
- <ForwardMessageProvider messageId={messageId}>
- <Composer.Frame>
- <Composer.Input placeholder="Add a message, if you'd like." />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.Mentions />
- </Composer.Footer>
- </Composer.Frame>
- </ForwardMessageProvider>
- )
-}
-```
-
-Each variant is explicit about:
-
-- What provider/state it uses
-
-- What UI elements it includes
-
-- What actions are available
-
-No boolean prop combinations to reason about. No impossible states.
-
-### 3.2 Prefer Composing Children Over Render Props
-
-**Impact: MEDIUM (cleaner composition, better readability)**
-
-Use `children` for composition instead of `renderX` props. Children are more
-
-readable, compose naturally, and don't require understanding callback
-
-signatures.
-
-**Incorrect: render props**
-
-```tsx
-function Composer({
- renderHeader,
- renderFooter,
- renderActions,
-}: {
- renderHeader?: () => React.ReactNode
- renderFooter?: () => React.ReactNode
- renderActions?: () => React.ReactNode
-}) {
- return (
- <form>
- {renderHeader?.()}
- <Input />
- {renderFooter ? renderFooter() : <DefaultFooter />}
- {renderActions?.()}
- </form>
- )
-}
-
-// Usage is awkward and inflexible
-return (
- <Composer
- renderHeader={() => <CustomHeader />}
- renderFooter={() => (
- <>
- <Formatting />
- <Emojis />
- </>
- )}
- renderActions={() => <SubmitButton />}
- />
-)
-```
-
-**Correct: compound components with children**
-
-```tsx
-function ComposerFrame({ children }: { children: React.ReactNode }) {
- return <form>{children}</form>
-}
-
-function ComposerFooter({ children }: { children: React.ReactNode }) {
- return <footer className='flex'>{children}</footer>
-}
-
-// Usage is flexible
-return (
- <Composer.Frame>
- <CustomHeader />
- <Composer.Input />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <SubmitButton />
- </Composer.Footer>
- </Composer.Frame>
-)
-```
-
-**When render props are appropriate:**
-
-```tsx
-// Render props work well when you need to pass data back
-<List
- data={items}
- renderItem={({ item, index }) => <Item item={item} index={index} />}
-/>
-```
-
-Use render props when the parent needs to provide data or state to the child.
-
-Use children when composing static structure.
-
----
-
-## 4. React 19 APIs
-
-**Impact: MEDIUM**
-
-React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
-
-### 4.1 React 19 API Changes
-
-**Impact: MEDIUM (cleaner component definitions and context usage)**
-
-> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
-
-In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
-
-**Incorrect: forwardRef in React 19**
-
-```tsx
-const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
- return <TextInput ref={ref} {...props} />
-})
-```
-
-**Correct: ref as a regular prop**
-
-```tsx
-function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
- return <TextInput ref={ref} {...props} />
-}
-```
-
-**Incorrect: useContext in React 19**
-
-```tsx
-const value = useContext(MyContext)
-```
-
-**Correct: use instead of useContext**
-
-```tsx
-const value = use(MyContext)
-```
-
-`use()` can also be called conditionally, unlike `useContext()`.
-
----
-
-## References
-
-1. [https://react.dev](https://react.dev)
-2. [https://react.dev/learn/passing-data-deeply-with-context](https://react.dev/learn/passing-data-deeply-with-context)
-3. [https://react.dev/reference/react/use](https://react.dev/reference/react/use)
diff --git a/.agents/skills/vercel-composition-patterns/SKILL.md b/.agents/skills/vercel-composition-patterns/SKILL.md
deleted file mode 100644
index d07025bf9..000000000
--- a/.agents/skills/vercel-composition-patterns/SKILL.md
+++ /dev/null
@@ -1,89 +0,0 @@
----
-name: vercel-composition-patterns
-description:
- React composition patterns that scale. Use when refactoring components with
- boolean prop proliferation, building flexible component libraries, or
- designing reusable APIs. Triggers on tasks involving compound components,
- render props, context providers, or component architecture. Includes React 19
- API changes.
-license: MIT
-metadata:
- author: vercel
- version: '1.0.0'
----
-
-# React Composition Patterns
-
-Composition patterns for building flexible, maintainable React components. Avoid
-boolean prop proliferation by using compound components, lifting state, and
-composing internals. These patterns make codebases easier for both humans and AI
-agents to work with as they scale.
-
-## When to Apply
-
-Reference these guidelines when:
-
-- Refactoring components with many boolean props
-- Building reusable component libraries
-- Designing flexible component APIs
-- Reviewing component architecture
-- Working with compound components or context providers
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-| -------- | ----------------------- | ------ | --------------- |
-| 1 | Component Architecture | HIGH | `architecture-` |
-| 2 | State Management | MEDIUM | `state-` |
-| 3 | Implementation Patterns | MEDIUM | `patterns-` |
-| 4 | React 19 APIs | MEDIUM | `react19-` |
-
-## Quick Reference
-
-### 1. Component Architecture (HIGH)
-
-- `architecture-avoid-boolean-props` - Don't add boolean props to customize
- behavior; use composition
-- `architecture-compound-components` - Structure complex components with shared
- context
-
-### 2. State Management (MEDIUM)
-
-- `state-decouple-implementation` - Provider is the only place that knows how
- state is managed
-- `state-context-interface` - Define generic interface with state, actions, meta
- for dependency injection
-- `state-lift-state` - Move state into provider components for sibling access
-
-### 3. Implementation Patterns (MEDIUM)
-
-- `patterns-explicit-variants` - Create explicit variant components instead of
- boolean modes
-- `patterns-children-over-render-props` - Use children for composition instead
- of renderX props
-
-### 4. React 19 APIs (MEDIUM)
-
-> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.
-
-- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `useContext()`
-
-## How to Use
-
-Read individual rule files for detailed explanations and code examples:
-
-```
-rules/architecture-avoid-boolean-props.md
-rules/state-context-interface.md
-```
-
-Each rule file contains:
-
-- Brief explanation of why it matters
-- Incorrect code example with explanation
-- Correct code example with explanation
-- Additional context and references
-
-## Full Compiled Document
-
-For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/.agents/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md b/.agents/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md
deleted file mode 100644
index ccee19ce4..000000000
--- a/.agents/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: Avoid Boolean Prop Proliferation
-impact: CRITICAL
-impactDescription: prevents unmaintainable component variants
-tags: composition, props, architecture
----
-
-## Avoid Boolean Prop Proliferation
-
-Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
-component behavior. Each boolean doubles possible states and creates
-unmaintainable conditional logic. Use composition instead.
-
-**Incorrect (boolean props create exponential complexity):**
-
-```tsx
-function Composer({
- onSubmit,
- isThread,
- channelId,
- isDMThread,
- dmId,
- isEditing,
- isForwarding,
-}: Props) {
- return (
- <form>
- <Header />
- <Input />
- {isDMThread ? (
- <AlsoSendToDMField id={dmId} />
- ) : isThread ? (
- <AlsoSendToChannelField id={channelId} />
- ) : null}
- {isEditing ? (
- <EditActions />
- ) : isForwarding ? (
- <ForwardActions />
- ) : (
- <DefaultActions />
- )}
- <Footer onSubmit={onSubmit} />
- </form>
- )
-}
-```
-
-**Correct (composition eliminates conditionals):**
-
-```tsx
-// Channel composer
-function ChannelComposer() {
- return (
- <Composer.Frame>
- <Composer.Header />
- <Composer.Input />
- <Composer.Footer>
- <Composer.Attachments />
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
- )
-}
-
-// Thread composer - adds "also send to channel" field
-function ThreadComposer({ channelId }: { channelId: string }) {
- return (
- <Composer.Frame>
- <Composer.Header />
- <Composer.Input />
- <AlsoSendToChannelField id={channelId} />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
- )
-}
-
-// Edit composer - different footer actions
-function EditComposer() {
- return (
- <Composer.Frame>
- <Composer.Input />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.CancelEdit />
- <Composer.SaveEdit />
- </Composer.Footer>
- </Composer.Frame>
- )
-}
-```
-
-Each variant is explicit about what it renders. We can share internals without
-sharing a single monolithic parent.
diff --git a/.agents/skills/vercel-composition-patterns/rules/architecture-compound-components.md b/.agents/skills/vercel-composition-patterns/rules/architecture-compound-components.md
deleted file mode 100644
index e5e3043cb..000000000
--- a/.agents/skills/vercel-composition-patterns/rules/architecture-compound-components.md
+++ /dev/null
@@ -1,112 +0,0 @@
----
-title: Use Compound Components
-impact: HIGH
-impactDescription: enables flexible composition without prop drilling
-tags: composition, compound-components, architecture
----
-
-## Use Compound Components
-
-Structure complex components as compound components with a shared context. Each
-subcomponent accesses shared state via context, not props. Consumers compose the
-pieces they need.
-
-**Incorrect (monolithic component with render props):**
-
-```tsx
-function Composer({
- renderHeader,
- renderFooter,
- renderActions,
- showAttachments,
- showFormatting,
- showEmojis,
-}: Props) {
- return (
- <form>
- {renderHeader?.()}
- <Input />
- {showAttachments && <Attachments />}
- {renderFooter ? (
- renderFooter()
- ) : (
- <Footer>
- {showFormatting && <Formatting />}
- {showEmojis && <Emojis />}
- {renderActions?.()}
- </Footer>
- )}
- </form>
- )
-}
-```
-
-**Correct (compound components with shared context):**
-
-```tsx
-const ComposerContext = createContext<ComposerContextValue | null>(null)
-
-function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
- return (
- <ComposerContext value={{ state, actions, meta }}>
- {children}
- </ComposerContext>
- )
-}
-
-function ComposerFrame({ children }: { children: React.ReactNode }) {
- return <form>{children}</form>
-}
-
-function ComposerInput() {
- const {
- state,
- actions: { update },
- meta: { inputRef },
- } = use(ComposerContext)
- return (
- <TextInput
- ref={inputRef}
- value={state.input}
- onChangeText={(text) => update((s) => ({ ...s, input: text }))}
- />
- )
-}
-
-function ComposerSubmit() {
- const {
- actions: { submit },
- } = use(ComposerContext)
- return <Button onPress={submit}>Send</Button>
-}
-
-// Export as compound component
-const Composer = {
- Provider: ComposerProvider,
- Frame: ComposerFrame,
- Input: ComposerInput,
- Submit: ComposerSubmit,
- Header: ComposerHeader,
- Footer: ComposerFooter,
- Attachments: ComposerAttachments,
- Formatting: ComposerFormatting,
- Emojis: ComposerEmojis,
-}
-```
-
-**Usage:**
-
-```tsx
-<Composer.Provider state={state} actions={actions} meta={meta}>
- <Composer.Frame>
- <Composer.Header />
- <Composer.Input />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
-</Composer.Provider>
-```
-
-Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
diff --git a/.agents/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md b/.agents/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md
deleted file mode 100644
index d4345ee30..000000000
--- a/.agents/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md
+++ /dev/null
@@ -1,87 +0,0 @@
----
-title: Prefer Composing Children Over Render Props
-impact: MEDIUM
-impactDescription: cleaner composition, better readability
-tags: composition, children, render-props
----
-
-## Prefer Children Over Render Props
-
-Use `children` for composition instead of `renderX` props. Children are more
-readable, compose naturally, and don't require understanding callback
-signatures.
-
-**Incorrect (render props):**
-
-```tsx
-function Composer({
- renderHeader,
- renderFooter,
- renderActions,
-}: {
- renderHeader?: () => React.ReactNode
- renderFooter?: () => React.ReactNode
- renderActions?: () => React.ReactNode
-}) {
- return (
- <form>
- {renderHeader?.()}
- <Input />
- {renderFooter ? renderFooter() : <DefaultFooter />}
- {renderActions?.()}
- </form>
- )
-}
-
-// Usage is awkward and inflexible
-return (
- <Composer
- renderHeader={() => <CustomHeader />}
- renderFooter={() => (
- <>
- <Formatting />
- <Emojis />
- </>
- )}
- renderActions={() => <SubmitButton />}
- />
-)
-```
-
-**Correct (compound components with children):**
-
-```tsx
-function ComposerFrame({ children }: { children: React.ReactNode }) {
- return <form>{children}</form>
-}
-
-function ComposerFooter({ children }: { children: React.ReactNode }) {
- return <footer className='flex'>{children}</footer>
-}
-
-// Usage is flexible
-return (
- <Composer.Frame>
- <CustomHeader />
- <Composer.Input />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <SubmitButton />
- </Composer.Footer>
- </Composer.Frame>
-)
-```
-
-**When render props are appropriate:**
-
-```tsx
-// Render props work well when you need to pass data back
-<List
- data={items}
- renderItem={({ item, index }) => <Item item={item} index={index} />}
-/>
-```
-
-Use render props when the parent needs to provide data or state to the child.
-Use children when composing static structure.
diff --git a/.agents/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md b/.agents/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md
deleted file mode 100644
index 56e32e8be..000000000
--- a/.agents/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: Create Explicit Component Variants
-impact: MEDIUM
-impactDescription: self-documenting code, no hidden conditionals
-tags: composition, variants, architecture
----
-
-## Create Explicit Component Variants
-
-Instead of one component with many boolean props, create explicit variant
-components. Each variant composes the pieces it needs. The code documents
-itself.
-
-**Incorrect (one component, many modes):**
-
-```tsx
-// What does this component actually render?
-<Composer
- isThread
- isEditing={false}
- channelId='abc'
- showAttachments
- showFormatting={false}
-/>
-```
-
-**Correct (explicit variants):**
-
-```tsx
-// Immediately clear what this renders
-<ThreadComposer channelId="abc" />
-
-// Or
-<EditMessageComposer messageId="xyz" />
-
-// Or
-<ForwardMessageComposer messageId="123" />
-```
-
-Each implementation is unique, explicit and self-contained. Yet they can each
-use shared parts.
-
-**Implementation:**
-
-```tsx
-function ThreadComposer({ channelId }: { channelId: string }) {
- return (
- <ThreadProvider channelId={channelId}>
- <Composer.Frame>
- <Composer.Input />
- <AlsoSendToChannelField channelId={channelId} />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
- </ThreadProvider>
- )
-}
-
-function EditMessageComposer({ messageId }: { messageId: string }) {
- return (
- <EditMessageProvider messageId={messageId}>
- <Composer.Frame>
- <Composer.Input />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.CancelEdit />
- <Composer.SaveEdit />
- </Composer.Footer>
- </Composer.Frame>
- </EditMessageProvider>
- )
-}
-
-function ForwardMessageComposer({ messageId }: { messageId: string }) {
- return (
- <ForwardMessageProvider messageId={messageId}>
- <Composer.Frame>
- <Composer.Input placeholder="Add a message, if you'd like." />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- <Composer.Mentions />
- </Composer.Footer>
- </Composer.Frame>
- </ForwardMessageProvider>
- )
-}
-```
-
-Each variant is explicit about:
-
-- What provider/state it uses
-- What UI elements it includes
-- What actions are available
-
-No boolean prop combinations to reason about. No impossible states.
diff --git a/.agents/skills/vercel-composition-patterns/rules/react19-no-forwardref.md b/.agents/skills/vercel-composition-patterns/rules/react19-no-forwardref.md
deleted file mode 100644
index e0d8f8a76..000000000
--- a/.agents/skills/vercel-composition-patterns/rules/react19-no-forwardref.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-title: React 19 API Changes
-impact: MEDIUM
-impactDescription: cleaner component definitions and context usage
-tags: react19, refs, context, hooks
----
-
-## React 19 API Changes
-
-> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
-
-In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
-
-**Incorrect (forwardRef in React 19):**
-
-```tsx
-const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
- return <TextInput ref={ref} {...props} />
-})
-```
-
-**Correct (ref as a regular prop):**
-
-```tsx
-function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
- return <TextInput ref={ref} {...props} />
-}
-```
-
-**Incorrect (useContext in React 19):**
-
-```tsx
-const value = useContext(MyContext)
-```
-
-**Correct (use instead of useContext):**
-
-```tsx
-const value = use(MyContext)
-```
-
-`use()` can also be called conditionally, unlike `useContext()`.
diff --git a/.agents/skills/vercel-composition-patterns/rules/state-context-interface.md b/.agents/skills/vercel-composition-patterns/rules/state-context-interface.md
deleted file mode 100644
index d961bede0..000000000
--- a/.agents/skills/vercel-composition-patterns/rules/state-context-interface.md
+++ /dev/null
@@ -1,191 +0,0 @@
----
-title: Define Generic Context Interfaces for Dependency Injection
-impact: HIGH
-impactDescription: enables dependency-injectable state across use-cases
-tags: composition, context, state, typescript, dependency-injection
----
-
-## Define Generic Context Interfaces for Dependency Injection
-
-Define a **generic interface** for your component context with three parts:
-`state`, `actions`, and `meta`. This interface is a contract that any provider
-can implement—enabling the same UI components to work with completely different
-state implementations.
-
-**Core principle:** Lift state, compose internals, make state
-dependency-injectable.
-
-**Incorrect (UI coupled to specific state implementation):**
-
-```tsx
-function ComposerInput() {
- // Tightly coupled to a specific hook
- const { input, setInput } = useChannelComposerState()
- return <TextInput value={input} onChangeText={setInput} />
-}
-```
-
-**Correct (generic interface enables dependency injection):**
-
-```tsx
-// Define a GENERIC interface that any provider can implement
-interface ComposerState {
- input: string
- attachments: Attachment[]
- isSubmitting: boolean
-}
-
-interface ComposerActions {
- update: (updater: (state: ComposerState) => ComposerState) => void
- submit: () => void
-}
-
-interface ComposerMeta {
- inputRef: React.RefObject<TextInput>
-}
-
-interface ComposerContextValue {
- state: ComposerState
- actions: ComposerActions
- meta: ComposerMeta
-}
-
-const ComposerContext = createContext<ComposerContextValue | null>(null)
-```
-
-**UI components consume the interface, not the implementation:**
-
-```tsx
-function ComposerInput() {
- const {
- state,
- actions: { update },
- meta,
- } = use(ComposerContext)
-
- // This component works with ANY provider that implements the interface
- return (
- <TextInput
- ref={meta.inputRef}
- value={state.input}
- onChangeText={(text) => update((s) => ({ ...s, input: text }))}
- />
- )
-}
-```
-
-**Different providers implement the same interface:**
-
-```tsx
-// Provider A: Local state for ephemeral forms
-function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
- const [state, setState] = useState(initialState)
- const inputRef = useRef(null)
- const submit = useForwardMessage()
-
- return (
- <ComposerContext
- value={{
- state,
- actions: { update: setState, submit },
- meta: { inputRef },
- }}
- >
- {children}
- </ComposerContext>
- )
-}
-
-// Provider B: Global synced state for channels
-function ChannelProvider({ channelId, children }: Props) {
- const { state, update, submit } = useGlobalChannel(channelId)
- const inputRef = useRef(null)
-
- return (
- <ComposerContext
- value={{
- state,
- actions: { update, submit },
- meta: { inputRef },
- }}
- >
- {children}
- </ComposerContext>
- )
-}
-```
-
-**The same composed UI works with both:**
-
-```tsx
-// Works with ForwardMessageProvider (local state)
-<ForwardMessageProvider>
- <Composer.Frame>
- <Composer.Input />
- <Composer.Submit />
- </Composer.Frame>
-</ForwardMessageProvider>
-
-// Works with ChannelProvider (global synced state)
-<ChannelProvider channelId="abc">
- <Composer.Frame>
- <Composer.Input />
- <Composer.Submit />
- </Composer.Frame>
-</ChannelProvider>
-```
-
-**Custom UI outside the component can access state and actions:**
-
-The provider boundary is what matters—not the visual nesting. Components that
-need shared state don't have to be inside the `Composer.Frame`. They just need
-to be within the provider.
-
-```tsx
-function ForwardMessageDialog() {
- return (
- <ForwardMessageProvider>
- <Dialog>
- {/* The composer UI */}
- <Composer.Frame>
- <Composer.Input placeholder="Add a message, if you'd like." />
- <Composer.Footer>
- <Composer.Formatting />
- <Composer.Emojis />
- </Composer.Footer>
- </Composer.Frame>
-
- {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
- <MessagePreview />
-
- {/* Actions at the bottom of the dialog */}
- <DialogActions>
- <CancelButton />
- <ForwardButton />
- </DialogActions>
- </Dialog>
- </ForwardMessageProvider>
- )
-}
-
-// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
-function ForwardButton() {
- const {
- actions: { submit },
- } = use(ComposerContext)
- return <Button onPress={submit}>Forward</Button>
-}
-
-// This preview lives OUTSIDE Composer.Frame but can read composer's state!
-function MessagePreview() {
- const { state } = use(ComposerContext)
- return <Preview message={state.input} attachments={state.attachments} />
-}
-```
-
-The `ForwardButton` and `MessagePreview` are not visually inside the composer
-box, but they can still access its state and actions. This is the power of
-lifting state into providers.
-
-The UI is reusable bits you compose together. The state is dependency-injected
-by the provider. Swap the provider, keep the UI.
diff --git a/.agents/skills/vercel-composition-patterns/rules/state-decouple-implementation.md b/.agents/skills/vercel-composition-patterns/rules/state-decouple-implementation.md
deleted file mode 100644
index 71a5afaa7..000000000
--- a/.agents/skills/vercel-composition-patterns/rules/state-decouple-implementation.md
+++ /dev/null
@@ -1,113 +0,0 @@
----
-title: Decouple State Management from UI
-impact: MEDIUM
-impactDescription: enables swapping state implementations without changing UI
-tags: composition, state, architecture
----
-
-## Decouple State Management from UI
-
-The provider component should be the only place that knows how state is managed.
-UI components consume the context interface—they don't know if state comes from
-useState, Zustand, or a server sync.
-
-**Incorrect (UI coupled to state implementation):**
-
-```tsx
-function ChannelComposer({ channelId }: { channelId: string }) {
- // UI component knows about global state implementation
- const state = useGlobalChannelState(channelId)
- const { submit, updateInput } = useChannelSync(channelId)
-
- return (
- <Composer.Frame>
- <Composer.Input
- value={state.input}
- onChange={(text) => sync.updateInput(text)}
- />
- <Composer.Submit onPress={() => sync.submit()} />
- </Composer.Frame>
- )
-}
-```
-
-**Correct (state management isolated in provider):**
-
-```tsx
-// Provider handles all state management details
-function ChannelProvider({
- channelId,
- children,
-}: {
- channelId: string
- children: React.ReactNode
-}) {
- const { state, update, submit } = useGlobalChannel(channelId)
- const inputRef = useRef(null)
-
- return (
- <Composer.Provider
- state={state}
- actions={{ update, submit }}
- meta={{ inputRef }}
- >
- {children}
- </Composer.Provider>
- )
-}
-
-// UI component only knows about the context interface
-function ChannelComposer() {
- return (
- <Composer.Frame>
- <Composer.Header />
- <Composer.Input />
- <Composer.Footer>
- <Composer.Submit />
- </Composer.Footer>
- </Composer.Frame>
- )
-}
-
-// Usage
-function Channel({ channelId }: { channelId: string }) {
- return (
- <ChannelProvider channelId={channelId}>
- <ChannelComposer />
- </ChannelProvider>
- )
-}
-```
-
-**Different providers, same UI:**
-
-```tsx
-// Local state for ephemeral forms
-function ForwardMessageProvider({ children }) {
- const [state, setState] = useState(initialState)
- const forwardMessage = useForwardMessage()
-
- return (
- <Composer.Provider
- state={state}
- actions={{ update: setState, submit: forwardMessage }}
- >
- {children}
- </Composer.Provider>
- )
-}
-
-// Global synced state for channels
-function ChannelProvider({ channelId, children }) {
- const { state, update, submit } = useGlobalChannel(channelId)
-
- return (
- <Composer.Provider state={state} actions={{ update, submit }}>
- {children}
- </Composer.Provider>
- )
-}
-```
-
-The same `Composer.Input` component works with both providers because it only
-depends on the context interface, not the implementation.
diff --git a/.agents/skills/vercel-composition-patterns/rules/state-lift-state.md b/.agents/skills/vercel-composition-patterns/rules/state-lift-state.md
deleted file mode 100644
index d7fe27b54..000000000
--- a/.agents/skills/vercel-composition-patterns/rules/state-lift-state.md
+++ /dev/null
@@ -1,125 +0,0 @@
----
-title: Lift State into Provider Components
-impact: HIGH
-impactDescription: enables state sharing outside component boundaries
-tags: composition, state, context, providers
----
-
-## Lift State into Provider Components
-
-Move state management into dedicated provider components. This allows sibling
-components outside the main UI to access and modify state without prop drilling
-or awkward refs.
-
-**Incorrect (state trapped inside component):**
-
-```tsx
-function ForwardMessageComposer() {
- const [state, setState] = useState(initialState)
- const forwardMessage = useForwardMessage()
-
- return (
- <Composer.Frame>
- <Composer.Input />
- <Composer.Footer />
- </Composer.Frame>
- )
-}
-
-// Problem: How does this button access composer state?
-function ForwardMessageDialog() {
- return (
- <Dialog>
- <ForwardMessageComposer />
- <MessagePreview /> {/* Needs composer state */}
- <DialogActions>
- <CancelButton />
- <ForwardButton /> {/* Needs to call submit */}
- </DialogActions>
- </Dialog>
- )
-}
-```
-
-**Incorrect (useEffect to sync state up):**
-
-```tsx
-function ForwardMessageDialog() {
- const [input, setInput] = useState('')
- return (
- <Dialog>
- <ForwardMessageComposer onInputChange={setInput} />
- <MessagePreview input={input} />
- </Dialog>
- )
-}
-
-function ForwardMessageComposer({ onInputChange }) {
- const [state, setState] = useState(initialState)
- useEffect(() => {
- onInputChange(state.input) // Sync on every change 😬
- }, [state.input])
-}
-```
-
-**Incorrect (reading state from ref on submit):**
-
-```tsx
-function ForwardMessageDialog() {
- const stateRef = useRef(null)
- return (
- <Dialog>
- <ForwardMessageComposer stateRef={stateRef} />
- <ForwardButton onPress={() => submit(stateRef.current)} />
- </Dialog>
- )
-}
-```
-
-**Correct (state lifted to provider):**
-
-```tsx
-function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
- const [state, setState] = useState(initialState)
- const forwardMessage = useForwardMessage()
- const inputRef = useRef(null)
-
- return (
- <Composer.Provider
- state={state}
- actions={{ update: setState, submit: forwardMessage }}
- meta={{ inputRef }}
- >
- {children}
- </Composer.Provider>
- )
-}
-
-function ForwardMessageDialog() {
- return (
- <ForwardMessageProvider>
- <Dialog>
- <ForwardMessageComposer />
- <MessagePreview /> {/* Custom components can access state and actions */}
- <DialogActions>
- <CancelButton />
- <ForwardButton /> {/* Custom components can access state and actions */}
- </DialogActions>
- </Dialog>
- </ForwardMessageProvider>
- )
-}
-
-function ForwardButton() {
- const { actions } = use(Composer.Context)
- return <Button onPress={actions.submit}>Forward</Button>
-}
-```
-
-The ForwardButton lives outside the Composer.Frame but still has access to the
-submit action because it's within the provider. Even though it's a one-off
-component, it can still access the composer's state and actions from outside the
-UI itself.
-
-**Key insight:** Components that need shared state don't have to be visually
-nested inside each other—they just need to be within the same provider.
diff --git a/.agents/skills/vercel-react-best-practices/AGENTS.md b/.agents/skills/vercel-react-best-practices/AGENTS.md
deleted file mode 100644
index db951abe7..000000000
--- a/.agents/skills/vercel-react-best-practices/AGENTS.md
+++ /dev/null
@@ -1,2934 +0,0 @@
-# React Best Practices
-
-**Version 1.0.0**
-Vercel Engineering
-January 2026
-
-> **Note:**
-> This document is mainly for agents and LLMs to follow when maintaining,
-> generating, or refactoring React and Next.js codebases. Humans
-> may also find it useful, but guidance here is optimized for automation
-> and consistency by AI-assisted workflows.
-
----
-
-## Abstract
-
-Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
-
----
-
-## Table of Contents
-
-1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
- - 1.1 [Defer Await Until Needed](#11-defer-await-until-needed)
- - 1.2 [Dependency-Based Parallelization](#12-dependency-based-parallelization)
- - 1.3 [Prevent Waterfall Chains in API Routes](#13-prevent-waterfall-chains-in-api-routes)
- - 1.4 [Promise.all() for Independent Operations](#14-promiseall-for-independent-operations)
- - 1.5 [Strategic Suspense Boundaries](#15-strategic-suspense-boundaries)
-2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
- - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)
- - 2.2 [Conditional Module Loading](#22-conditional-module-loading)
- - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
- - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
- - 2.5 [Preload Based on User Intent](#25-preload-based-on-user-intent)
-3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
- - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
- - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
- - 3.3 [Cross-Request LRU Caching](#33-cross-request-lru-caching)
- - 3.4 [Minimize Serialization at RSC Boundaries](#34-minimize-serialization-at-rsc-boundaries)
- - 3.5 [Parallel Data Fetching with Component Composition](#35-parallel-data-fetching-with-component-composition)
- - 3.6 [Per-Request Deduplication with React.cache()](#36-per-request-deduplication-with-reactcache)
- - 3.7 [Use after() for Non-Blocking Operations](#37-use-after-for-non-blocking-operations)
-4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
- - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)
- - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)
- - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)
- - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)
-5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
- - 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering)
- - 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point)
- - 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)
- - 5.4 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#54-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)
- - 5.5 [Extract to Memoized Components](#55-extract-to-memoized-components)
- - 5.6 [Narrow Effect Dependencies](#56-narrow-effect-dependencies)
- - 5.7 [Put Interaction Logic in Event Handlers](#57-put-interaction-logic-in-event-handlers)
- - 5.8 [Subscribe to Derived State](#58-subscribe-to-derived-state)
- - 5.9 [Use Functional setState Updates](#59-use-functional-setstate-updates)
- - 5.10 [Use Lazy State Initialization](#510-use-lazy-state-initialization)
- - 5.11 [Use Transitions for Non-Urgent Updates](#511-use-transitions-for-non-urgent-updates)
- - 5.12 [Use useRef for Transient Values](#512-use-useref-for-transient-values)
-6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
- - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)
- - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)
- - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)
- - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)
- - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)
- - 6.6 [Suppress Expected Hydration Mismatches](#66-suppress-expected-hydration-mismatches)
- - 6.7 [Use Activity Component for Show/Hide](#67-use-activity-component-for-showhide)
- - 6.8 [Use Explicit Conditional Rendering](#68-use-explicit-conditional-rendering)
- - 6.9 [Use useTransition Over Manual Loading States](#69-use-usetransition-over-manual-loading-states)
-7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
- - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)
- - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)
- - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)
- - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)
- - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)
- - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)
- - 7.7 [Early Length Check for Array Comparisons](#77-early-length-check-for-array-comparisons)
- - 7.8 [Early Return from Functions](#78-early-return-from-functions)
- - 7.9 [Hoist RegExp Creation](#79-hoist-regexp-creation)
- - 7.10 [Use Loop for Min/Max Instead of Sort](#710-use-loop-for-minmax-instead-of-sort)
- - 7.11 [Use Set/Map for O(1) Lookups](#711-use-setmap-for-o1-lookups)
- - 7.12 [Use toSorted() Instead of sort() for Immutability](#712-use-tosorted-instead-of-sort-for-immutability)
-8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
- - 8.1 [Initialize App Once, Not Per Mount](#81-initialize-app-once-not-per-mount)
- - 8.2 [Store Event Handlers in Refs](#82-store-event-handlers-in-refs)
- - 8.3 [useEffectEvent for Stable Callback Refs](#83-useeffectevent-for-stable-callback-refs)
-
----
-
-## 1. Eliminating Waterfalls
-
-**Impact: CRITICAL**
-
-Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
-
-### 1.1 Defer Await Until Needed
-
-**Impact: HIGH (avoids blocking unused code paths)**
-
-Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
-
-**Incorrect: blocks both branches**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
- const userData = await fetchUserData(userId)
-
- if (skipProcessing) {
- // Returns immediately but still waited for userData
- return { skipped: true }
- }
-
- // Only this branch uses userData
- return processUserData(userData)
-}
-```
-
-**Correct: only blocks when needed**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
- if (skipProcessing) {
- // Returns immediately without waiting
- return { skipped: true }
- }
-
- // Fetch only when needed
- const userData = await fetchUserData(userId)
- return processUserData(userData)
-}
-```
-
-**Another example: early return optimization**
-
-```typescript
-// Incorrect: always fetches permissions
-async function updateResource(resourceId: string, userId: string) {
- const permissions = await fetchPermissions(userId)
- const resource = await getResource(resourceId)
-
- if (!resource) {
- return { error: 'Not found' }
- }
-
- if (!permissions.canEdit) {
- return { error: 'Forbidden' }
- }
-
- return await updateResourceData(resource, permissions)
-}
-
-// Correct: fetches only when needed
-async function updateResource(resourceId: string, userId: string) {
- const resource = await getResource(resourceId)
-
- if (!resource) {
- return { error: 'Not found' }
- }
-
- const permissions = await fetchPermissions(userId)
-
- if (!permissions.canEdit) {
- return { error: 'Forbidden' }
- }
-
- return await updateResourceData(resource, permissions)
-}
-```
-
-This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
-
-### 1.2 Dependency-Based Parallelization
-
-**Impact: CRITICAL (2-10× improvement)**
-
-For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
-
-**Incorrect: profile waits for config unnecessarily**
-
-```typescript
-const [user, config] = await Promise.all([
- fetchUser(),
- fetchConfig()
-])
-const profile = await fetchProfile(user.id)
-```
-
-**Correct: config and profile run in parallel**
-
-```typescript
-import { all } from 'better-all'
-
-const { user, config, profile } = await all({
- async user() { return fetchUser() },
- async config() { return fetchConfig() },
- async profile() {
- return fetchProfile((await this.$.user).id)
- }
-})
-```
-
-**Alternative without extra dependencies:**
-
-```typescript
-const userPromise = fetchUser()
-const profilePromise = userPromise.then(user => fetchProfile(user.id))
-
-const [user, config, profile] = await Promise.all([
- userPromise,
- fetchConfig(),
- profilePromise
-])
-```
-
-We can also create all the promises first, and do `Promise.all()` at the end.
-
-Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
-
-### 1.3 Prevent Waterfall Chains in API Routes
-
-**Impact: CRITICAL (2-10× improvement)**
-
-In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
-
-**Incorrect: config waits for auth, data waits for both**
-
-```typescript
-export async function GET(request: Request) {
- const session = await auth()
- const config = await fetchConfig()
- const data = await fetchData(session.user.id)
- return Response.json({ data, config })
-}
-```
-
-**Correct: auth and config start immediately**
-
-```typescript
-export async function GET(request: Request) {
- const sessionPromise = auth()
- const configPromise = fetchConfig()
- const session = await sessionPromise
- const [config, data] = await Promise.all([
- configPromise,
- fetchData(session.user.id)
- ])
- return Response.json({ data, config })
-}
-```
-
-For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
-
-### 1.4 Promise.all() for Independent Operations
-
-**Impact: CRITICAL (2-10× improvement)**
-
-When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
-
-**Incorrect: sequential execution, 3 round trips**
-
-```typescript
-const user = await fetchUser()
-const posts = await fetchPosts()
-const comments = await fetchComments()
-```
-
-**Correct: parallel execution, 1 round trip**
-
-```typescript
-const [user, posts, comments] = await Promise.all([
- fetchUser(),
- fetchPosts(),
- fetchComments()
-])
-```
-
-### 1.5 Strategic Suspense Boundaries
-
-**Impact: HIGH (faster initial paint)**
-
-Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
-
-**Incorrect: wrapper blocked by data fetching**
-
-```tsx
-async function Page() {
- const data = await fetchData() // Blocks entire page
-
- return (
- <div>
- <div>Sidebar</div>
- <div>Header</div>
- <div>
- <DataDisplay data={data} />
- </div>
- <div>Footer</div>
- </div>
- )
-}
-```
-
-The entire layout waits for data even though only the middle section needs it.
-
-**Correct: wrapper shows immediately, data streams in**
-
-```tsx
-function Page() {
- return (
- <div>
- <div>Sidebar</div>
- <div>Header</div>
- <div>
- <Suspense fallback={<Skeleton />}>
- <DataDisplay />
- </Suspense>
- </div>
- <div>Footer</div>
- </div>
- )
-}
-
-async function DataDisplay() {
- const data = await fetchData() // Only blocks this component
- return <div>{data.content}</div>
-}
-```
-
-Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
-
-**Alternative: share promise across components**
-
-```tsx
-function Page() {
- // Start fetch immediately, but don't await
- const dataPromise = fetchData()
-
- return (
- <div>
- <div>Sidebar</div>
- <div>Header</div>
- <Suspense fallback={<Skeleton />}>
- <DataDisplay dataPromise={dataPromise} />
- <DataSummary dataPromise={dataPromise} />
- </Suspense>
- <div>Footer</div>
- </div>
- )
-}
-
-function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
- const data = use(dataPromise) // Unwraps the promise
- return <div>{data.content}</div>
-}
-
-function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
- const data = use(dataPromise) // Reuses the same promise
- return <div>{data.summary}</div>
-}
-```
-
-Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
-
-**When NOT to use this pattern:**
-
-- Critical data needed for layout decisions (affects positioning)
-
-- SEO-critical content above the fold
-
-- Small, fast queries where suspense overhead isn't worth it
-
-- When you want to avoid layout shift (loading → content jump)
-
-**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
-
----
-
-## 2. Bundle Size Optimization
-
-**Impact: CRITICAL**
-
-Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
-
-### 2.1 Avoid Barrel File Imports
-
-**Impact: CRITICAL (200-800ms import cost, slow builds)**
-
-Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
-
-Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
-
-**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
-
-**Incorrect: imports entire library**
-
-```tsx
-import { Check, X, Menu } from 'lucide-react'
-// Loads 1,583 modules, takes ~2.8s extra in dev
-// Runtime cost: 200-800ms on every cold start
-
-import { Button, TextField } from '@mui/material'
-// Loads 2,225 modules, takes ~4.2s extra in dev
-```
-
-**Correct: imports only what you need**
-
-```tsx
-import Check from 'lucide-react/dist/esm/icons/check'
-import X from 'lucide-react/dist/esm/icons/x'
-import Menu from 'lucide-react/dist/esm/icons/menu'
-// Loads only 3 modules (~2KB vs ~1MB)
-
-import Button from '@mui/material/Button'
-import TextField from '@mui/material/TextField'
-// Loads only what you use
-```
-
-**Alternative: Next.js 13.5+**
-
-```js
-// next.config.js - use optimizePackageImports
-module.exports = {
- experimental: {
- optimizePackageImports: ['lucide-react', '@mui/material']
- }
-}
-
-// Then you can keep the ergonomic barrel imports:
-import { Check, X, Menu } from 'lucide-react'
-// Automatically transformed to direct imports at build time
-```
-
-Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
-
-Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
-
-Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
-
-### 2.2 Conditional Module Loading
-
-**Impact: HIGH (loads large data only when needed)**
-
-Load large data or modules only when a feature is activated.
-
-**Example: lazy-load animation frames**
-
-```tsx
-function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
- const [frames, setFrames] = useState<Frame[] | null>(null)
-
- useEffect(() => {
- if (enabled && !frames && typeof window !== 'undefined') {
- import('./animation-frames.js')
- .then(mod => setFrames(mod.frames))
- .catch(() => setEnabled(false))
- }
- }, [enabled, frames, setEnabled])
-
- if (!frames) return <Skeleton />
- return <Canvas frames={frames} />
-}
-```
-
-The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
-
-### 2.3 Defer Non-Critical Third-Party Libraries
-
-**Impact: MEDIUM (loads after hydration)**
-
-Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
-
-**Incorrect: blocks initial bundle**
-
-```tsx
-import { Analytics } from '@vercel/analytics/react'
-
-export default function RootLayout({ children }) {
- return (
- <html>
- <body>
- {children}
- <Analytics />
- </body>
- </html>
- )
-}
-```
-
-**Correct: loads after hydration**
-
-```tsx
-import dynamic from 'next/dynamic'
-
-const Analytics = dynamic(
- () => import('@vercel/analytics/react').then(m => m.Analytics),
- { ssr: false }
-)
-
-export default function RootLayout({ children }) {
- return (
- <html>
- <body>
- {children}
- <Analytics />
- </body>
- </html>
- )
-}
-```
-
-### 2.4 Dynamic Imports for Heavy Components
-
-**Impact: CRITICAL (directly affects TTI and LCP)**
-
-Use `next/dynamic` to lazy-load large components not needed on initial render.
-
-**Incorrect: Monaco bundles with main chunk ~300KB**
-
-```tsx
-import { MonacoEditor } from './monaco-editor'
-
-function CodePanel({ code }: { code: string }) {
- return <MonacoEditor value={code} />
-}
-```
-
-**Correct: Monaco loads on demand**
-
-```tsx
-import dynamic from 'next/dynamic'
-
-const MonacoEditor = dynamic(
- () => import('./monaco-editor').then(m => m.MonacoEditor),
- { ssr: false }
-)
-
-function CodePanel({ code }: { code: string }) {
- return <MonacoEditor value={code} />
-}
-```
-
-### 2.5 Preload Based on User Intent
-
-**Impact: MEDIUM (reduces perceived latency)**
-
-Preload heavy bundles before they're needed to reduce perceived latency.
-
-**Example: preload on hover/focus**
-
-```tsx
-function EditorButton({ onClick }: { onClick: () => void }) {
- const preload = () => {
- if (typeof window !== 'undefined') {
- void import('./monaco-editor')
- }
- }
-
- return (
- <button
- onMouseEnter={preload}
- onFocus={preload}
- onClick={onClick}
- >
- Open Editor
- </button>
- )
-}
-```
-
-**Example: preload when feature flag is enabled**
-
-```tsx
-function FlagsProvider({ children, flags }: Props) {
- useEffect(() => {
- if (flags.editorEnabled && typeof window !== 'undefined') {
- void import('./monaco-editor').then(mod => mod.init())
- }
- }, [flags.editorEnabled])
-
- return <FlagsContext.Provider value={flags}>
- {children}
- </FlagsContext.Provider>
-}
-```
-
-The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
-
----
-
-## 3. Server-Side Performance
-
-**Impact: HIGH**
-
-Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
-
-### 3.1 Authenticate Server Actions Like API Routes
-
-**Impact: CRITICAL (prevents unauthorized access to server mutations)**
-
-Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
-
-Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
-
-**Incorrect: no authentication check**
-
-```typescript
-'use server'
-
-export async function deleteUser(userId: string) {
- // Anyone can call this! No auth check
- await db.user.delete({ where: { id: userId } })
- return { success: true }
-}
-```
-
-**Correct: authentication inside the action**
-
-```typescript
-'use server'
-
-import { verifySession } from '@/lib/auth'
-import { unauthorized } from '@/lib/errors'
-
-export async function deleteUser(userId: string) {
- // Always check auth inside the action
- const session = await verifySession()
-
- if (!session) {
- throw unauthorized('Must be logged in')
- }
-
- // Check authorization too
- if (session.user.role !== 'admin' && session.user.id !== userId) {
- throw unauthorized('Cannot delete other users')
- }
-
- await db.user.delete({ where: { id: userId } })
- return { success: true }
-}
-```
-
-**With input validation:**
-
-```typescript
-'use server'
-
-import { verifySession } from '@/lib/auth'
-import { z } from 'zod'
-
-const updateProfileSchema = z.object({
- userId: z.string().uuid(),
- name: z.string().min(1).max(100),
- email: z.string().email()
-})
-
-export async function updateProfile(data: unknown) {
- // Validate input first
- const validated = updateProfileSchema.parse(data)
-
- // Then authenticate
- const session = await verifySession()
- if (!session) {
- throw new Error('Unauthorized')
- }
-
- // Then authorize
- if (session.user.id !== validated.userId) {
- throw new Error('Can only update own profile')
- }
-
- // Finally perform the mutation
- await db.user.update({
- where: { id: validated.userId },
- data: {
- name: validated.name,
- email: validated.email
- }
- })
-
- return { success: true }
-}
-```
-
-Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
-
-### 3.2 Avoid Duplicate Serialization in RSC Props
-
-**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
-
-RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
-
-**Incorrect: duplicates array**
-
-```tsx
-// RSC: sends 6 strings (2 arrays × 3 items)
-<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
-```
-
-**Correct: sends 3 strings**
-
-```tsx
-// RSC: send once
-<ClientList usernames={usernames} />
-
-// Client: transform there
-'use client'
-const sorted = useMemo(() => [...usernames].sort(), [usernames])
-```
-
-**Nested deduplication behavior:**
-
-```tsx
-// string[] - duplicates everything
-usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
-
-// object[] - duplicates array structure only
-users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
-```
-
-Deduplication works recursively. Impact varies by data type:
-
-- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
-
-- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
-
-**Operations breaking deduplication: create new references**
-
-- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
-
-- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
-
-**More examples:**
-
-```tsx
-// ❌ Bad
-<C users={users} active={users.filter(u => u.active)} />
-<C product={product} productName={product.name} />
-
-// ✅ Good
-<C users={users} />
-<C product={product} />
-// Do filtering/destructuring in client
-```
-
-**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
-
-### 3.3 Cross-Request LRU Caching
-
-**Impact: HIGH (caches across requests)**
-
-`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
-
-**Implementation:**
-
-```typescript
-import { LRUCache } from 'lru-cache'
-
-const cache = new LRUCache<string, any>({
- max: 1000,
- ttl: 5 * 60 * 1000 // 5 minutes
-})
-
-export async function getUser(id: string) {
- const cached = cache.get(id)
- if (cached) return cached
-
- const user = await db.user.findUnique({ where: { id } })
- cache.set(id, user)
- return user
-}
-
-// Request 1: DB query, result cached
-// Request 2: cache hit, no DB query
-```
-
-Use when sequential user actions hit multiple endpoints needing the same data within seconds.
-
-**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
-
-**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
-
-Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
-
-### 3.4 Minimize Serialization at RSC Boundaries
-
-**Impact: HIGH (reduces data transfer size)**
-
-The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
-
-**Incorrect: serializes all 50 fields**
-
-```tsx
-async function Page() {
- const user = await fetchUser() // 50 fields
- return <Profile user={user} />
-}
-
-'use client'
-function Profile({ user }: { user: User }) {
- return <div>{user.name}</div> // uses 1 field
-}
-```
-
-**Correct: serializes only 1 field**
-
-```tsx
-async function Page() {
- const user = await fetchUser()
- return <Profile name={user.name} />
-}
-
-'use client'
-function Profile({ name }: { name: string }) {
- return <div>{name}</div>
-}
-```
-
-### 3.5 Parallel Data Fetching with Component Composition
-
-**Impact: CRITICAL (eliminates server-side waterfalls)**
-
-React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
-
-**Incorrect: Sidebar waits for Page's fetch to complete**
-
-```tsx
-export default async function Page() {
- const header = await fetchHeader()
- return (
- <div>
- <div>{header}</div>
- <Sidebar />
- </div>
- )
-}
-
-async function Sidebar() {
- const items = await fetchSidebarItems()
- return <nav>{items.map(renderItem)}</nav>
-}
-```
-
-**Correct: both fetch simultaneously**
-
-```tsx
-async function Header() {
- const data = await fetchHeader()
- return <div>{data}</div>
-}
-
-async function Sidebar() {
- const items = await fetchSidebarItems()
- return <nav>{items.map(renderItem)}</nav>
-}
-
-export default function Page() {
- return (
- <div>
- <Header />
- <Sidebar />
- </div>
- )
-}
-```
-
-**Alternative with children prop:**
-
-```tsx
-async function Header() {
- const data = await fetchHeader()
- return <div>{data}</div>
-}
-
-async function Sidebar() {
- const items = await fetchSidebarItems()
- return <nav>{items.map(renderItem)}</nav>
-}
-
-function Layout({ children }: { children: ReactNode }) {
- return (
- <div>
- <Header />
- {children}
- </div>
- )
-}
-
-export default function Page() {
- return (
- <Layout>
- <Sidebar />
- </Layout>
- )
-}
-```
-
-### 3.6 Per-Request Deduplication with React.cache()
-
-**Impact: MEDIUM (deduplicates within request)**
-
-Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
-
-**Usage:**
-
-```typescript
-import { cache } from 'react'
-
-export const getCurrentUser = cache(async () => {
- const session = await auth()
- if (!session?.user?.id) return null
- return await db.user.findUnique({
- where: { id: session.user.id }
- })
-})
-```
-
-Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
-
-**Avoid inline objects as arguments:**
-
-`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
-
-**Incorrect: always cache miss**
-
-```typescript
-const getUser = cache(async (params: { uid: number }) => {
- return await db.user.findUnique({ where: { id: params.uid } })
-})
-
-// Each call creates new object, never hits cache
-getUser({ uid: 1 })
-getUser({ uid: 1 }) // Cache miss, runs query again
-```
-
-**Correct: cache hit**
-
-```typescript
-const params = { uid: 1 }
-getUser(params) // Query runs
-getUser(params) // Cache hit (same reference)
-```
-
-If you must pass objects, pass the same reference:
-
-**Next.js-Specific Note:**
-
-In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
-
-- Database queries (Prisma, Drizzle, etc.)
-
-- Heavy computations
-
-- Authentication checks
-
-- File system operations
-
-- Any non-fetch async work
-
-Use `React.cache()` to deduplicate these operations across your component tree.
-
-Reference: [https://react.dev/reference/react/cache](https://react.dev/reference/react/cache)
-
-### 3.7 Use after() for Non-Blocking Operations
-
-**Impact: MEDIUM (faster response times)**
-
-Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
-
-**Incorrect: blocks response**
-
-```tsx
-import { logUserAction } from '@/app/utils'
-
-export async function POST(request: Request) {
- // Perform mutation
- await updateDatabase(request)
-
- // Logging blocks the response
- const userAgent = request.headers.get('user-agent') || 'unknown'
- await logUserAction({ userAgent })
-
- return new Response(JSON.stringify({ status: 'success' }), {
- status: 200,
- headers: { 'Content-Type': 'application/json' }
- })
-}
-```
-
-**Correct: non-blocking**
-
-```tsx
-import { after } from 'next/server'
-import { headers, cookies } from 'next/headers'
-import { logUserAction } from '@/app/utils'
-
-export async function POST(request: Request) {
- // Perform mutation
- await updateDatabase(request)
-
- // Log after response is sent
- after(async () => {
- const userAgent = (await headers()).get('user-agent') || 'unknown'
- const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
-
- logUserAction({ sessionCookie, userAgent })
- })
-
- return new Response(JSON.stringify({ status: 'success' }), {
- status: 200,
- headers: { 'Content-Type': 'application/json' }
- })
-}
-```
-
-The response is sent immediately while logging happens in the background.
-
-**Common use cases:**
-
-- Analytics tracking
-
-- Audit logging
-
-- Sending notifications
-
-- Cache invalidation
-
-- Cleanup tasks
-
-**Important notes:**
-
-- `after()` runs even if the response fails or redirects
-
-- Works in Server Actions, Route Handlers, and Server Components
-
-Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
-
----
-
-## 4. Client-Side Data Fetching
-
-**Impact: MEDIUM-HIGH**
-
-Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
-
-### 4.1 Deduplicate Global Event Listeners
-
-**Impact: LOW (single listener for N components)**
-
-Use `useSWRSubscription()` to share global event listeners across component instances.
-
-**Incorrect: N instances = N listeners**
-
-```tsx
-function useKeyboardShortcut(key: string, callback: () => void) {
- useEffect(() => {
- const handler = (e: KeyboardEvent) => {
- if (e.metaKey && e.key === key) {
- callback()
- }
- }
- window.addEventListener('keydown', handler)
- return () => window.removeEventListener('keydown', handler)
- }, [key, callback])
-}
-```
-
-When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
-
-**Correct: N instances = 1 listener**
-
-```tsx
-import useSWRSubscription from 'swr/subscription'
-
-// Module-level Map to track callbacks per key
-const keyCallbacks = new Map<string, Set<() => void>>()
-
-function useKeyboardShortcut(key: string, callback: () => void) {
- // Register this callback in the Map
- useEffect(() => {
- if (!keyCallbacks.has(key)) {
- keyCallbacks.set(key, new Set())
- }
- keyCallbacks.get(key)!.add(callback)
-
- return () => {
- const set = keyCallbacks.get(key)
- if (set) {
- set.delete(callback)
- if (set.size === 0) {
- keyCallbacks.delete(key)
- }
- }
- }
- }, [key, callback])
-
- useSWRSubscription('global-keydown', () => {
- const handler = (e: KeyboardEvent) => {
- if (e.metaKey && keyCallbacks.has(e.key)) {
- keyCallbacks.get(e.key)!.forEach(cb => cb())
- }
- }
- window.addEventListener('keydown', handler)
- return () => window.removeEventListener('keydown', handler)
- })
-}
-
-function Profile() {
- // Multiple shortcuts will share the same listener
- useKeyboardShortcut('p', () => { /* ... */ })
- useKeyboardShortcut('k', () => { /* ... */ })
- // ...
-}
-```
-
-### 4.2 Use Passive Event Listeners for Scrolling Performance
-
-**Impact: MEDIUM (eliminates scroll delay caused by event listeners)**
-
-Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
-
-**Incorrect:**
-
-```typescript
-useEffect(() => {
- const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
- const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
-
- document.addEventListener('touchstart', handleTouch)
- document.addEventListener('wheel', handleWheel)
-
- return () => {
- document.removeEventListener('touchstart', handleTouch)
- document.removeEventListener('wheel', handleWheel)
- }
-}, [])
-```
-
-**Correct:**
-
-```typescript
-useEffect(() => {
- const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
- const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
-
- document.addEventListener('touchstart', handleTouch, { passive: true })
- document.addEventListener('wheel', handleWheel, { passive: true })
-
- return () => {
- document.removeEventListener('touchstart', handleTouch)
- document.removeEventListener('wheel', handleWheel)
- }
-}, [])
-```
-
-**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
-
-**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
-
-### 4.3 Use SWR for Automatic Deduplication
-
-**Impact: MEDIUM-HIGH (automatic deduplication)**
-
-SWR enables request deduplication, caching, and revalidation across component instances.
-
-**Incorrect: no deduplication, each instance fetches**
-
-```tsx
-function UserList() {
- const [users, setUsers] = useState([])
- useEffect(() => {
- fetch('/api/users')
- .then(r => r.json())
- .then(setUsers)
- }, [])
-}
-```
-
-**Correct: multiple instances share one request**
-
-```tsx
-import useSWR from 'swr'
-
-function UserList() {
- const { data: users } = useSWR('/api/users', fetcher)
-}
-```
-
-**For immutable data:**
-
-```tsx
-import { useImmutableSWR } from '@/lib/swr'
-
-function StaticContent() {
- const { data } = useImmutableSWR('/api/config', fetcher)
-}
-```
-
-**For mutations:**
-
-```tsx
-import { useSWRMutation } from 'swr/mutation'
-
-function UpdateButton() {
- const { trigger } = useSWRMutation('/api/user', updateUser)
- return <button onClick={() => trigger()}>Update</button>
-}
-```
-
-Reference: [https://swr.vercel.app](https://swr.vercel.app)
-
-### 4.4 Version and Minimize localStorage Data
-
-**Impact: MEDIUM (prevents schema conflicts, reduces storage size)**
-
-Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
-
-**Incorrect:**
-
-```typescript
-// No version, stores everything, no error handling
-localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
-const data = localStorage.getItem('userConfig')
-```
-
-**Correct:**
-
-```typescript
-const VERSION = 'v2'
-
-function saveConfig(config: { theme: string; language: string }) {
- try {
- localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
- } catch {
- // Throws in incognito/private browsing, quota exceeded, or disabled
- }
-}
-
-function loadConfig() {
- try {
- const data = localStorage.getItem(`userConfig:${VERSION}`)
- return data ? JSON.parse(data) : null
- } catch {
- return null
- }
-}
-
-// Migration from v1 to v2
-function migrate() {
- try {
- const v1 = localStorage.getItem('userConfig:v1')
- if (v1) {
- const old = JSON.parse(v1)
- saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
- localStorage.removeItem('userConfig:v1')
- }
- } catch {}
-}
-```
-
-**Store minimal fields from server responses:**
-
-```typescript
-// User object has 20+ fields, only store what UI needs
-function cachePrefs(user: FullUser) {
- try {
- localStorage.setItem('prefs:v1', JSON.stringify({
- theme: user.preferences.theme,
- notifications: user.preferences.notifications
- }))
- } catch {}
-}
-```
-
-**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
-
-**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
-
----
-
-## 5. Re-render Optimization
-
-**Impact: MEDIUM**
-
-Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
-
-### 5.1 Calculate Derived State During Rendering
-
-**Impact: MEDIUM (avoids redundant renders and state drift)**
-
-If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
-
-**Incorrect: redundant state and effect**
-
-```tsx
-function Form() {
- const [firstName, setFirstName] = useState('First')
- const [lastName, setLastName] = useState('Last')
- const [fullName, setFullName] = useState('')
-
- useEffect(() => {
- setFullName(firstName + ' ' + lastName)
- }, [firstName, lastName])
-
- return <p>{fullName}</p>
-}
-```
-
-**Correct: derive during render**
-
-```tsx
-function Form() {
- const [firstName, setFirstName] = useState('First')
- const [lastName, setLastName] = useState('Last')
- const fullName = firstName + ' ' + lastName
-
- return <p>{fullName}</p>
-}
-```
-
-Reference: [https://react.dev/learn/you-might-not-need-an-effect](https://react.dev/learn/you-might-not-need-an-effect)
-
-### 5.2 Defer State Reads to Usage Point
-
-**Impact: MEDIUM (avoids unnecessary subscriptions)**
-
-Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
-
-**Incorrect: subscribes to all searchParams changes**
-
-```tsx
-function ShareButton({ chatId }: { chatId: string }) {
- const searchParams = useSearchParams()
-
- const handleShare = () => {
- const ref = searchParams.get('ref')
- shareChat(chatId, { ref })
- }
-
- return <button onClick={handleShare}>Share</button>
-}
-```
-
-**Correct: reads on demand, no subscription**
-
-```tsx
-function ShareButton({ chatId }: { chatId: string }) {
- const handleShare = () => {
- const params = new URLSearchParams(window.location.search)
- const ref = params.get('ref')
- shareChat(chatId, { ref })
- }
-
- return <button onClick={handleShare}>Share</button>
-}
-```
-
-### 5.3 Do not wrap a simple expression with a primitive result type in useMemo
-
-**Impact: LOW-MEDIUM (wasted computation on every render)**
-
-When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
-
-Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
-
-**Incorrect:**
-
-```tsx
-function Header({ user, notifications }: Props) {
- const isLoading = useMemo(() => {
- return user.isLoading || notifications.isLoading
- }, [user.isLoading, notifications.isLoading])
-
- if (isLoading) return <Skeleton />
- // return some markup
-}
-```
-
-**Correct:**
-
-```tsx
-function Header({ user, notifications }: Props) {
- const isLoading = user.isLoading || notifications.isLoading
-
- if (isLoading) return <Skeleton />
- // return some markup
-}
-```
-
-### 5.4 Extract Default Non-primitive Parameter Value from Memoized Component to Constant
-
-**Impact: MEDIUM (restores memoization by using a constant for default value)**
-
-When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
-
-To address this issue, extract the default value into a constant.
-
-**Incorrect: `onClick` has different values on every rerender**
-
-```tsx
-const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
- // ...
-})
-
-// Used without optional onClick
-<UserAvatar />
-```
-
-**Correct: stable default value**
-
-```tsx
-const NOOP = () => {};
-
-const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
- // ...
-})
-
-// Used without optional onClick
-<UserAvatar />
-```
-
-### 5.5 Extract to Memoized Components
-
-**Impact: MEDIUM (enables early returns)**
-
-Extract expensive work into memoized components to enable early returns before computation.
-
-**Incorrect: computes avatar even when loading**
-
-```tsx
-function Profile({ user, loading }: Props) {
- const avatar = useMemo(() => {
- const id = computeAvatarId(user)
- return <Avatar id={id} />
- }, [user])
-
- if (loading) return <Skeleton />
- return <div>{avatar}</div>
-}
-```
-
-**Correct: skips computation when loading**
-
-```tsx
-const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
- const id = useMemo(() => computeAvatarId(user), [user])
- return <Avatar id={id} />
-})
-
-function Profile({ user, loading }: Props) {
- if (loading) return <Skeleton />
- return (
- <div>
- <UserAvatar user={user} />
- </div>
- )
-}
-```
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
-
-### 5.6 Narrow Effect Dependencies
-
-**Impact: LOW (minimizes effect re-runs)**
-
-Specify primitive dependencies instead of objects to minimize effect re-runs.
-
-**Incorrect: re-runs on any user field change**
-
-```tsx
-useEffect(() => {
- console.log(user.id)
-}, [user])
-```
-
-**Correct: re-runs only when id changes**
-
-```tsx
-useEffect(() => {
- console.log(user.id)
-}, [user.id])
-```
-
-**For derived state, compute outside effect:**
-
-```tsx
-// Incorrect: runs on width=767, 766, 765...
-useEffect(() => {
- if (width < 768) {
- enableMobileMode()
- }
-}, [width])
-
-// Correct: runs only on boolean transition
-const isMobile = width < 768
-useEffect(() => {
- if (isMobile) {
- enableMobileMode()
- }
-}, [isMobile])
-```
-
-### 5.7 Put Interaction Logic in Event Handlers
-
-**Impact: MEDIUM (avoids effect re-runs and duplicate side effects)**
-
-If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
-
-**Incorrect: event modeled as state + effect**
-
-```tsx
-function Form() {
- const [submitted, setSubmitted] = useState(false)
- const theme = useContext(ThemeContext)
-
- useEffect(() => {
- if (submitted) {
- post('/api/register')
- showToast('Registered', theme)
- }
- }, [submitted, theme])
-
- return <button onClick={() => setSubmitted(true)}>Submit</button>
-}
-```
-
-**Correct: do it in the handler**
-
-```tsx
-function Form() {
- const theme = useContext(ThemeContext)
-
- function handleSubmit() {
- post('/api/register')
- showToast('Registered', theme)
- }
-
- return <button onClick={handleSubmit}>Submit</button>
-}
-```
-
-Reference: [https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
-
-### 5.8 Subscribe to Derived State
-
-**Impact: MEDIUM (reduces re-render frequency)**
-
-Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
-
-**Incorrect: re-renders on every pixel change**
-
-```tsx
-function Sidebar() {
- const width = useWindowWidth() // updates continuously
- const isMobile = width < 768
- return <nav className={isMobile ? 'mobile' : 'desktop'} />
-}
-```
-
-**Correct: re-renders only when boolean changes**
-
-```tsx
-function Sidebar() {
- const isMobile = useMediaQuery('(max-width: 767px)')
- return <nav className={isMobile ? 'mobile' : 'desktop'} />
-}
-```
-
-### 5.9 Use Functional setState Updates
-
-**Impact: MEDIUM (prevents stale closures and unnecessary callback recreations)**
-
-When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
-
-**Incorrect: requires state as dependency**
-
-```tsx
-function TodoList() {
- const [items, setItems] = useState(initialItems)
-
- // Callback must depend on items, recreated on every items change
- const addItems = useCallback((newItems: Item[]) => {
- setItems([...items, ...newItems])
- }, [items]) // ❌ items dependency causes recreations
-
- // Risk of stale closure if dependency is forgotten
- const removeItem = useCallback((id: string) => {
- setItems(items.filter(item => item.id !== id))
- }, []) // ❌ Missing items dependency - will use stale items!
-
- return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
-}
-```
-
-The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
-
-**Correct: stable callbacks, no stale closures**
-
-```tsx
-function TodoList() {
- const [items, setItems] = useState(initialItems)
-
- // Stable callback, never recreated
- const addItems = useCallback((newItems: Item[]) => {
- setItems(curr => [...curr, ...newItems])
- }, []) // ✅ No dependencies needed
-
- // Always uses latest state, no stale closure risk
- const removeItem = useCallback((id: string) => {
- setItems(curr => curr.filter(item => item.id !== id))
- }, []) // ✅ Safe and stable
-
- return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
-}
-```
-
-**Benefits:**
-
-1. **Stable callback references** - Callbacks don't need to be recreated when state changes
-
-2. **No stale closures** - Always operates on the latest state value
-
-3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
-
-4. **Prevents bugs** - Eliminates the most common source of React closure bugs
-
-**When to use functional updates:**
-
-- Any setState that depends on the current state value
-
-- Inside useCallback/useMemo when state is needed
-
-- Event handlers that reference state
-
-- Async operations that update state
-
-**When direct updates are fine:**
-
-- Setting state to a static value: `setCount(0)`
-
-- Setting state from props/arguments only: `setName(newName)`
-
-- State doesn't depend on previous value
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
-
-### 5.10 Use Lazy State Initialization
-
-**Impact: MEDIUM (wasted computation on every render)**
-
-Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
-
-**Incorrect: runs on every render**
-
-```tsx
-function FilteredList({ items }: { items: Item[] }) {
- // buildSearchIndex() runs on EVERY render, even after initialization
- const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
- const [query, setQuery] = useState('')
-
- // When query changes, buildSearchIndex runs again unnecessarily
- return <SearchResults index={searchIndex} query={query} />
-}
-
-function UserProfile() {
- // JSON.parse runs on every render
- const [settings, setSettings] = useState(
- JSON.parse(localStorage.getItem('settings') || '{}')
- )
-
- return <SettingsForm settings={settings} onChange={setSettings} />
-}
-```
-
-**Correct: runs only once**
-
-```tsx
-function FilteredList({ items }: { items: Item[] }) {
- // buildSearchIndex() runs ONLY on initial render
- const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
- const [query, setQuery] = useState('')
-
- return <SearchResults index={searchIndex} query={query} />
-}
-
-function UserProfile() {
- // JSON.parse runs only on initial render
- const [settings, setSettings] = useState(() => {
- const stored = localStorage.getItem('settings')
- return stored ? JSON.parse(stored) : {}
- })
-
- return <SettingsForm settings={settings} onChange={setSettings} />
-}
-```
-
-Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
-
-For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
-
-### 5.11 Use Transitions for Non-Urgent Updates
-
-**Impact: MEDIUM (maintains UI responsiveness)**
-
-Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
-
-**Incorrect: blocks UI on every scroll**
-
-```tsx
-function ScrollTracker() {
- const [scrollY, setScrollY] = useState(0)
- useEffect(() => {
- const handler = () => setScrollY(window.scrollY)
- window.addEventListener('scroll', handler, { passive: true })
- return () => window.removeEventListener('scroll', handler)
- }, [])
-}
-```
-
-**Correct: non-blocking updates**
-
-```tsx
-import { startTransition } from 'react'
-
-function ScrollTracker() {
- const [scrollY, setScrollY] = useState(0)
- useEffect(() => {
- const handler = () => {
- startTransition(() => setScrollY(window.scrollY))
- }
- window.addEventListener('scroll', handler, { passive: true })
- return () => window.removeEventListener('scroll', handler)
- }, [])
-}
-```
-
-### 5.12 Use useRef for Transient Values
-
-**Impact: MEDIUM (avoids unnecessary re-renders on frequent updates)**
-
-When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
-
-**Incorrect: renders every update**
-
-```tsx
-function Tracker() {
- const [lastX, setLastX] = useState(0)
-
- useEffect(() => {
- const onMove = (e: MouseEvent) => setLastX(e.clientX)
- window.addEventListener('mousemove', onMove)
- return () => window.removeEventListener('mousemove', onMove)
- }, [])
-
- return (
- <div
- style={{
- position: 'fixed',
- top: 0,
- left: lastX,
- width: 8,
- height: 8,
- background: 'black',
- }}
- />
- )
-}
-```
-
-**Correct: no re-render for tracking**
-
-```tsx
-function Tracker() {
- const lastXRef = useRef(0)
- const dotRef = useRef<HTMLDivElement>(null)
-
- useEffect(() => {
- const onMove = (e: MouseEvent) => {
- lastXRef.current = e.clientX
- const node = dotRef.current
- if (node) {
- node.style.transform = `translateX(${e.clientX}px)`
- }
- }
- window.addEventListener('mousemove', onMove)
- return () => window.removeEventListener('mousemove', onMove)
- }, [])
-
- return (
- <div
- ref={dotRef}
- style={{
- position: 'fixed',
- top: 0,
- left: 0,
- width: 8,
- height: 8,
- background: 'black',
- transform: 'translateX(0px)',
- }}
- />
- )
-}
-```
-
----
-
-## 6. Rendering Performance
-
-**Impact: MEDIUM**
-
-Optimizing the rendering process reduces the work the browser needs to do.
-
-### 6.1 Animate SVG Wrapper Instead of SVG Element
-
-**Impact: LOW (enables hardware acceleration)**
-
-Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
-
-**Incorrect: animating SVG directly - no hardware acceleration**
-
-```tsx
-function LoadingSpinner() {
- return (
- <svg
- className="animate-spin"
- width="24"
- height="24"
- viewBox="0 0 24 24"
- >
- <circle cx="12" cy="12" r="10" stroke="currentColor" />
- </svg>
- )
-}
-```
-
-**Correct: animating wrapper div - hardware accelerated**
-
-```tsx
-function LoadingSpinner() {
- return (
- <div className="animate-spin">
- <svg
- width="24"
- height="24"
- viewBox="0 0 24 24"
- >
- <circle cx="12" cy="12" r="10" stroke="currentColor" />
- </svg>
- </div>
- )
-}
-```
-
-This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
-
-### 6.2 CSS content-visibility for Long Lists
-
-**Impact: HIGH (faster initial render)**
-
-Apply `content-visibility: auto` to defer off-screen rendering.
-
-**CSS:**
-
-```css
-.message-item {
- content-visibility: auto;
- contain-intrinsic-size: 0 80px;
-}
-```
-
-**Example:**
-
-```tsx
-function MessageList({ messages }: { messages: Message[] }) {
- return (
- <div className="overflow-y-auto h-screen">
- {messages.map(msg => (
- <div key={msg.id} className="message-item">
- <Avatar user={msg.author} />
- <div>{msg.content}</div>
- </div>
- ))}
- </div>
- )
-}
-```
-
-For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
-
-### 6.3 Hoist Static JSX Elements
-
-**Impact: LOW (avoids re-creation)**
-
-Extract static JSX outside components to avoid re-creation.
-
-**Incorrect: recreates element every render**
-
-```tsx
-function LoadingSkeleton() {
- return <div className="animate-pulse h-20 bg-gray-200" />
-}
-
-function Container() {
- return (
- <div>
- {loading && <LoadingSkeleton />}
- </div>
- )
-}
-```
-
-**Correct: reuses same element**
-
-```tsx
-const loadingSkeleton = (
- <div className="animate-pulse h-20 bg-gray-200" />
-)
-
-function Container() {
- return (
- <div>
- {loading && loadingSkeleton}
- </div>
- )
-}
-```
-
-This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
-
-### 6.4 Optimize SVG Precision
-
-**Impact: LOW (reduces file size)**
-
-Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
-
-**Incorrect: excessive precision**
-
-```svg
-<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
-```
-
-**Correct: 1 decimal place**
-
-```svg
-<path d="M 10.3 20.8 L 30.9 40.2" />
-```
-
-**Automate with SVGO:**
-
-```bash
-npx svgo --precision=1 --multipass icon.svg
-```
-
-### 6.5 Prevent Hydration Mismatch Without Flickering
-
-**Impact: MEDIUM (avoids visual flicker and hydration errors)**
-
-When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
-
-**Incorrect: breaks SSR**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
- // localStorage is not available on server - throws error
- const theme = localStorage.getItem('theme') || 'light'
-
- return (
- <div className={theme}>
- {children}
- </div>
- )
-}
-```
-
-Server-side rendering will fail because `localStorage` is undefined.
-
-**Incorrect: visual flickering**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
- const [theme, setTheme] = useState('light')
-
- useEffect(() => {
- // Runs after hydration - causes visible flash
- const stored = localStorage.getItem('theme')
- if (stored) {
- setTheme(stored)
- }
- }, [])
-
- return (
- <div className={theme}>
- {children}
- </div>
- )
-}
-```
-
-Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
-
-**Correct: no flicker, no hydration mismatch**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
- return (
- <>
- <div id="theme-wrapper">
- {children}
- </div>
- <script
- dangerouslySetInnerHTML={{
- __html: `
- (function() {
- try {
- var theme = localStorage.getItem('theme') || 'light';
- var el = document.getElementById('theme-wrapper');
- if (el) el.className = theme;
- } catch (e) {}
- })();
- `,
- }}
- />
- </>
- )
-}
-```
-
-The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
-
-This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
-
-### 6.6 Suppress Expected Hydration Mismatches
-
-**Impact: LOW-MEDIUM (avoids noisy hydration warnings for known differences)**
-
-In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
-
-**Incorrect: known mismatch warnings**
-
-```tsx
-function Timestamp() {
- return <span>{new Date().toLocaleString()}</span>
-}
-```
-
-**Correct: suppress expected mismatch only**
-
-```tsx
-function Timestamp() {
- return (
- <span suppressHydrationWarning>
- {new Date().toLocaleString()}
- </span>
- )
-}
-```
-
-### 6.7 Use Activity Component for Show/Hide
-
-**Impact: MEDIUM (preserves state/DOM)**
-
-Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
-
-**Usage:**
-
-```tsx
-import { Activity } from 'react'
-
-function Dropdown({ isOpen }: Props) {
- return (
- <Activity mode={isOpen ? 'visible' : 'hidden'}>
- <ExpensiveMenu />
- </Activity>
- )
-}
-```
-
-Avoids expensive re-renders and state loss.
-
-### 6.8 Use Explicit Conditional Rendering
-
-**Impact: LOW (prevents rendering 0 or NaN)**
-
-Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
-
-**Incorrect: renders "0" when count is 0**
-
-```tsx
-function Badge({ count }: { count: number }) {
- return (
- <div>
- {count && <span className="badge">{count}</span>}
- </div>
- )
-}
-
-// When count = 0, renders: <div>0</div>
-// When count = 5, renders: <div><span class="badge">5</span></div>
-```
-
-**Correct: renders nothing when count is 0**
-
-```tsx
-function Badge({ count }: { count: number }) {
- return (
- <div>
- {count > 0 ? <span className="badge">{count}</span> : null}
- </div>
- )
-}
-
-// When count = 0, renders: <div></div>
-// When count = 5, renders: <div><span class="badge">5</span></div>
-```
-
-### 6.9 Use useTransition Over Manual Loading States
-
-**Impact: LOW (reduces re-renders and improves code clarity)**
-
-Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
-
-**Incorrect: manual loading state**
-
-```tsx
-function SearchResults() {
- const [query, setQuery] = useState('')
- const [results, setResults] = useState([])
- const [isLoading, setIsLoading] = useState(false)
-
- const handleSearch = async (value: string) => {
- setIsLoading(true)
- setQuery(value)
- const data = await fetchResults(value)
- setResults(data)
- setIsLoading(false)
- }
-
- return (
- <>
- <input onChange={(e) => handleSearch(e.target.value)} />
- {isLoading && <Spinner />}
- <ResultsList results={results} />
- </>
- )
-}
-```
-
-**Correct: useTransition with built-in pending state**
-
-```tsx
-import { useTransition, useState } from 'react'
-
-function SearchResults() {
- const [query, setQuery] = useState('')
- const [results, setResults] = useState([])
- const [isPending, startTransition] = useTransition()
-
- const handleSearch = (value: string) => {
- setQuery(value) // Update input immediately
-
- startTransition(async () => {
- // Fetch and update results
- const data = await fetchResults(value)
- setResults(data)
- })
- }
-
- return (
- <>
- <input onChange={(e) => handleSearch(e.target.value)} />
- {isPending && <Spinner />}
- <ResultsList results={results} />
- </>
- )
-}
-```
-
-**Benefits:**
-
-- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
-
-- **Error resilience**: Pending state correctly resets even if the transition throws
-
-- **Better responsiveness**: Keeps the UI responsive during updates
-
-- **Interrupt handling**: New transitions automatically cancel pending ones
-
-Reference: [https://react.dev/reference/react/useTransition](https://react.dev/reference/react/useTransition)
-
----
-
-## 7. JavaScript Performance
-
-**Impact: LOW-MEDIUM**
-
-Micro-optimizations for hot paths can add up to meaningful improvements.
-
-### 7.1 Avoid Layout Thrashing
-
-**Impact: MEDIUM (prevents forced synchronous layouts and reduces performance bottlenecks)**
-
-Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
-
-**This is OK: browser batches style changes**
-
-```typescript
-function updateElementStyles(element: HTMLElement) {
- // Each line invalidates style, but browser batches the recalculation
- element.style.width = '100px'
- element.style.height = '200px'
- element.style.backgroundColor = 'blue'
- element.style.border = '1px solid black'
-}
-```
-
-**Incorrect: interleaved reads and writes force reflows**
-
-```typescript
-function layoutThrashing(element: HTMLElement) {
- element.style.width = '100px'
- const width = element.offsetWidth // Forces reflow
- element.style.height = '200px'
- const height = element.offsetHeight // Forces another reflow
-}
-```
-
-**Correct: batch writes, then read once**
-
-```typescript
-function updateElementStyles(element: HTMLElement) {
- // Batch all writes together
- element.style.width = '100px'
- element.style.height = '200px'
- element.style.backgroundColor = 'blue'
- element.style.border = '1px solid black'
-
- // Read after all writes are done (single reflow)
- const { width, height } = element.getBoundingClientRect()
-}
-```
-
-**Correct: batch reads, then writes**
-
-```typescript
-function updateElementStyles(element: HTMLElement) {
- element.classList.add('highlighted-box')
-
- const { width, height } = element.getBoundingClientRect()
-}
-```
-
-**Better: use CSS classes**
-
-**React example:**
-
-```tsx
-// Incorrect: interleaving style changes with layout queries
-function Box({ isHighlighted }: { isHighlighted: boolean }) {
- const ref = useRef<HTMLDivElement>(null)
-
- useEffect(() => {
- if (ref.current && isHighlighted) {
- ref.current.style.width = '100px'
- const width = ref.current.offsetWidth // Forces layout
- ref.current.style.height = '200px'
- }
- }, [isHighlighted])
-
- return <div ref={ref}>Content</div>
-}
-
-// Correct: toggle class
-function Box({ isHighlighted }: { isHighlighted: boolean }) {
- return (
- <div className={isHighlighted ? 'highlighted-box' : ''}>
- Content
- </div>
- )
-}
-```
-
-Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
-
-See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
-
-### 7.2 Build Index Maps for Repeated Lookups
-
-**Impact: LOW-MEDIUM (1M ops to 2K ops)**
-
-Multiple `.find()` calls by the same key should use a Map.
-
-**Incorrect (O(n) per lookup):**
-
-```typescript
-function processOrders(orders: Order[], users: User[]) {
- return orders.map(order => ({
- ...order,
- user: users.find(u => u.id === order.userId)
- }))
-}
-```
-
-**Correct (O(1) per lookup):**
-
-```typescript
-function processOrders(orders: Order[], users: User[]) {
- const userById = new Map(users.map(u => [u.id, u]))
-
- return orders.map(order => ({
- ...order,
- user: userById.get(order.userId)
- }))
-}
-```
-
-Build map once (O(n)), then all lookups are O(1).
-
-For 1000 orders × 1000 users: 1M ops → 2K ops.
-
-### 7.3 Cache Property Access in Loops
-
-**Impact: LOW-MEDIUM (reduces lookups)**
-
-Cache object property lookups in hot paths.
-
-**Incorrect: 3 lookups × N iterations**
-
-```typescript
-for (let i = 0; i < arr.length; i++) {
- process(obj.config.settings.value)
-}
-```
-
-**Correct: 1 lookup total**
-
-```typescript
-const value = obj.config.settings.value
-const len = arr.length
-for (let i = 0; i < len; i++) {
- process(value)
-}
-```
-
-### 7.4 Cache Repeated Function Calls
-
-**Impact: MEDIUM (avoid redundant computation)**
-
-Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
-
-**Incorrect: redundant computation**
-
-```typescript
-function ProjectList({ projects }: { projects: Project[] }) {
- return (
- <div>
- {projects.map(project => {
- // slugify() called 100+ times for same project names
- const slug = slugify(project.name)
-
- return <ProjectCard key={project.id} slug={slug} />
- })}
- </div>
- )
-}
-```
-
-**Correct: cached results**
-
-```typescript
-// Module-level cache
-const slugifyCache = new Map<string, string>()
-
-function cachedSlugify(text: string): string {
- if (slugifyCache.has(text)) {
- return slugifyCache.get(text)!
- }
- const result = slugify(text)
- slugifyCache.set(text, result)
- return result
-}
-
-function ProjectList({ projects }: { projects: Project[] }) {
- return (
- <div>
- {projects.map(project => {
- // Computed only once per unique project name
- const slug = cachedSlugify(project.name)
-
- return <ProjectCard key={project.id} slug={slug} />
- })}
- </div>
- )
-}
-```
-
-**Simpler pattern for single-value functions:**
-
-```typescript
-let isLoggedInCache: boolean | null = null
-
-function isLoggedIn(): boolean {
- if (isLoggedInCache !== null) {
- return isLoggedInCache
- }
-
- isLoggedInCache = document.cookie.includes('auth=')
- return isLoggedInCache
-}
-
-// Clear cache when auth changes
-function onAuthChange() {
- isLoggedInCache = null
-}
-```
-
-Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
-
-Reference: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
-
-### 7.5 Cache Storage API Calls
-
-**Impact: LOW-MEDIUM (reduces expensive I/O)**
-
-`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
-
-**Incorrect: reads storage on every call**
-
-```typescript
-function getTheme() {
- return localStorage.getItem('theme') ?? 'light'
-}
-// Called 10 times = 10 storage reads
-```
-
-**Correct: Map cache**
-
-```typescript
-const storageCache = new Map<string, string | null>()
-
-function getLocalStorage(key: string) {
- if (!storageCache.has(key)) {
- storageCache.set(key, localStorage.getItem(key))
- }
- return storageCache.get(key)
-}
-
-function setLocalStorage(key: string, value: string) {
- localStorage.setItem(key, value)
- storageCache.set(key, value) // keep cache in sync
-}
-```
-
-Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
-
-**Cookie caching:**
-
-```typescript
-let cookieCache: Record<string, string> | null = null
-
-function getCookie(name: string) {
- if (!cookieCache) {
- cookieCache = Object.fromEntries(
- document.cookie.split('; ').map(c => c.split('='))
- )
- }
- return cookieCache[name]
-}
-```
-
-**Important: invalidate on external changes**
-
-```typescript
-window.addEventListener('storage', (e) => {
- if (e.key) storageCache.delete(e.key)
-})
-
-document.addEventListener('visibilitychange', () => {
- if (document.visibilityState === 'visible') {
- storageCache.clear()
- }
-})
-```
-
-If storage can change externally (another tab, server-set cookies), invalidate cache:
-
-### 7.6 Combine Multiple Array Iterations
-
-**Impact: LOW-MEDIUM (reduces iterations)**
-
-Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
-
-**Incorrect: 3 iterations**
-
-```typescript
-const admins = users.filter(u => u.isAdmin)
-const testers = users.filter(u => u.isTester)
-const inactive = users.filter(u => !u.isActive)
-```
-
-**Correct: 1 iteration**
-
-```typescript
-const admins: User[] = []
-const testers: User[] = []
-const inactive: User[] = []
-
-for (const user of users) {
- if (user.isAdmin) admins.push(user)
- if (user.isTester) testers.push(user)
- if (!user.isActive) inactive.push(user)
-}
-```
-
-### 7.7 Early Length Check for Array Comparisons
-
-**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
-
-When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
-
-In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
-
-**Incorrect: always runs expensive comparison**
-
-```typescript
-function hasChanges(current: string[], original: string[]) {
- // Always sorts and joins, even when lengths differ
- return current.sort().join() !== original.sort().join()
-}
-```
-
-Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
-
-**Correct (O(1) length check first):**
-
-```typescript
-function hasChanges(current: string[], original: string[]) {
- // Early return if lengths differ
- if (current.length !== original.length) {
- return true
- }
- // Only sort when lengths match
- const currentSorted = current.toSorted()
- const originalSorted = original.toSorted()
- for (let i = 0; i < currentSorted.length; i++) {
- if (currentSorted[i] !== originalSorted[i]) {
- return true
- }
- }
- return false
-}
-```
-
-This new approach is more efficient because:
-
-- It avoids the overhead of sorting and joining the arrays when lengths differ
-
-- It avoids consuming memory for the joined strings (especially important for large arrays)
-
-- It avoids mutating the original arrays
-
-- It returns early when a difference is found
-
-### 7.8 Early Return from Functions
-
-**Impact: LOW-MEDIUM (avoids unnecessary computation)**
-
-Return early when result is determined to skip unnecessary processing.
-
-**Incorrect: processes all items even after finding answer**
-
-```typescript
-function validateUsers(users: User[]) {
- let hasError = false
- let errorMessage = ''
-
- for (const user of users) {
- if (!user.email) {
- hasError = true
- errorMessage = 'Email required'
- }
- if (!user.name) {
- hasError = true
- errorMessage = 'Name required'
- }
- // Continues checking all users even after error found
- }
-
- return hasError ? { valid: false, error: errorMessage } : { valid: true }
-}
-```
-
-**Correct: returns immediately on first error**
-
-```typescript
-function validateUsers(users: User[]) {
- for (const user of users) {
- if (!user.email) {
- return { valid: false, error: 'Email required' }
- }
- if (!user.name) {
- return { valid: false, error: 'Name required' }
- }
- }
-
- return { valid: true }
-}
-```
-
-### 7.9 Hoist RegExp Creation
-
-**Impact: LOW-MEDIUM (avoids recreation)**
-
-Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
-
-**Incorrect: new RegExp every render**
-
-```tsx
-function Highlighter({ text, query }: Props) {
- const regex = new RegExp(`(${query})`, 'gi')
- const parts = text.split(regex)
- return <>{parts.map((part, i) => ...)}</>
-}
-```
-
-**Correct: memoize or hoist**
-
-```tsx
-const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
-
-function Highlighter({ text, query }: Props) {
- const regex = useMemo(
- () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
- [query]
- )
- const parts = text.split(regex)
- return <>{parts.map((part, i) => ...)}</>
-}
-```
-
-**Warning: global regex has mutable state**
-
-```typescript
-const regex = /foo/g
-regex.test('foo') // true, lastIndex = 3
-regex.test('foo') // false, lastIndex = 0
-```
-
-Global regex (`/g`) has mutable `lastIndex` state:
-
-### 7.10 Use Loop for Min/Max Instead of Sort
-
-**Impact: LOW (O(n) instead of O(n log n))**
-
-Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
-
-**Incorrect (O(n log n) - sort to find latest):**
-
-```typescript
-interface Project {
- id: string
- name: string
- updatedAt: number
-}
-
-function getLatestProject(projects: Project[]) {
- const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
- return sorted[0]
-}
-```
-
-Sorts the entire array just to find the maximum value.
-
-**Incorrect (O(n log n) - sort for oldest and newest):**
-
-```typescript
-function getOldestAndNewest(projects: Project[]) {
- const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
- return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
-}
-```
-
-Still sorts unnecessarily when only min/max are needed.
-
-**Correct (O(n) - single loop):**
-
-```typescript
-function getLatestProject(projects: Project[]) {
- if (projects.length === 0) return null
-
- let latest = projects[0]
-
- for (let i = 1; i < projects.length; i++) {
- if (projects[i].updatedAt > latest.updatedAt) {
- latest = projects[i]
- }
- }
-
- return latest
-}
-
-function getOldestAndNewest(projects: Project[]) {
- if (projects.length === 0) return { oldest: null, newest: null }
-
- let oldest = projects[0]
- let newest = projects[0]
-
- for (let i = 1; i < projects.length; i++) {
- if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
- if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
- }
-
- return { oldest, newest }
-}
-```
-
-Single pass through the array, no copying, no sorting.
-
-**Alternative: Math.min/Math.max for small arrays**
-
-```typescript
-const numbers = [5, 2, 8, 1, 9]
-const min = Math.min(...numbers)
-const max = Math.max(...numbers)
-```
-
-This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
-
-### 7.11 Use Set/Map for O(1) Lookups
-
-**Impact: LOW-MEDIUM (O(n) to O(1))**
-
-Convert arrays to Set/Map for repeated membership checks.
-
-**Incorrect (O(n) per check):**
-
-```typescript
-const allowedIds = ['a', 'b', 'c', ...]
-items.filter(item => allowedIds.includes(item.id))
-```
-
-**Correct (O(1) per check):**
-
-```typescript
-const allowedIds = new Set(['a', 'b', 'c', ...])
-items.filter(item => allowedIds.has(item.id))
-```
-
-### 7.12 Use toSorted() Instead of sort() for Immutability
-
-**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
-
-`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
-
-**Incorrect: mutates original array**
-
-```typescript
-function UserList({ users }: { users: User[] }) {
- // Mutates the users prop array!
- const sorted = useMemo(
- () => users.sort((a, b) => a.name.localeCompare(b.name)),
- [users]
- )
- return <div>{sorted.map(renderUser)}</div>
-}
-```
-
-**Correct: creates new array**
-
-```typescript
-function UserList({ users }: { users: User[] }) {
- // Creates new sorted array, original unchanged
- const sorted = useMemo(
- () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
- [users]
- )
- return <div>{sorted.map(renderUser)}</div>
-}
-```
-
-**Why this matters in React:**
-
-1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
-
-2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
-
-**Browser support: fallback for older browsers**
-
-```typescript
-// Fallback for older browsers
-const sorted = [...items].sort((a, b) => a.value - b.value)
-```
-
-`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
-
-**Other immutable array methods:**
-
-- `.toSorted()` - immutable sort
-
-- `.toReversed()` - immutable reverse
-
-- `.toSpliced()` - immutable splice
-
-- `.with()` - immutable element replacement
-
----
-
-## 8. Advanced Patterns
-
-**Impact: LOW**
-
-Advanced patterns for specific cases that require careful implementation.
-
-### 8.1 Initialize App Once, Not Per Mount
-
-**Impact: LOW-MEDIUM (avoids duplicate init in development)**
-
-Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
-
-**Incorrect: runs twice in dev, re-runs on remount**
-
-```tsx
-function Comp() {
- useEffect(() => {
- loadFromStorage()
- checkAuthToken()
- }, [])
-
- // ...
-}
-```
-
-**Correct: once per app load**
-
-```tsx
-let didInit = false
-
-function Comp() {
- useEffect(() => {
- if (didInit) return
- didInit = true
- loadFromStorage()
- checkAuthToken()
- }, [])
-
- // ...
-}
-```
-
-Reference: [https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
-
-### 8.2 Store Event Handlers in Refs
-
-**Impact: LOW (stable subscriptions)**
-
-Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
-
-**Incorrect: re-subscribes on every render**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
- useEffect(() => {
- window.addEventListener(event, handler)
- return () => window.removeEventListener(event, handler)
- }, [event, handler])
-}
-```
-
-**Correct: stable subscription**
-
-```tsx
-import { useEffectEvent } from 'react'
-
-function useWindowEvent(event: string, handler: (e) => void) {
- const onEvent = useEffectEvent(handler)
-
- useEffect(() => {
- window.addEventListener(event, onEvent)
- return () => window.removeEventListener(event, onEvent)
- }, [event])
-}
-```
-
-**Alternative: use `useEffectEvent` if you're on latest React:**
-
-`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
-
-### 8.3 useEffectEvent for Stable Callback Refs
-
-**Impact: LOW (prevents effect re-runs)**
-
-Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
-
-**Incorrect: effect re-runs on every callback change**
-
-```tsx
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
- const [query, setQuery] = useState('')
-
- useEffect(() => {
- const timeout = setTimeout(() => onSearch(query), 300)
- return () => clearTimeout(timeout)
- }, [query, onSearch])
-}
-```
-
-**Correct: using React's useEffectEvent**
-
-```tsx
-import { useEffectEvent } from 'react';
-
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
- const [query, setQuery] = useState('')
- const onSearchEvent = useEffectEvent(onSearch)
-
- useEffect(() => {
- const timeout = setTimeout(() => onSearchEvent(query), 300)
- return () => clearTimeout(timeout)
- }, [query])
-}
-```
-
----
-
-## References
-
-1. [https://react.dev](https://react.dev)
-2. [https://nextjs.org](https://nextjs.org)
-3. [https://swr.vercel.app](https://swr.vercel.app)
-4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
-5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
-6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
-7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.agents/skills/vercel-react-best-practices/SKILL.md b/.agents/skills/vercel-react-best-practices/SKILL.md
deleted file mode 100644
index 1ad7750e5..000000000
--- a/.agents/skills/vercel-react-best-practices/SKILL.md
+++ /dev/null
@@ -1,136 +0,0 @@
----
-name: vercel-react-best-practices
-description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
-license: MIT
-metadata:
- author: vercel
- version: "1.0.0"
----
-
-# Vercel React Best Practices
-
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
-
-## When to Apply
-
-Reference these guidelines when:
-- Writing new React components or Next.js pages
-- Implementing data fetching (client or server-side)
-- Reviewing code for performance issues
-- Refactoring existing React/Next.js code
-- Optimizing bundle size or load times
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
-| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
-| 3 | Server-Side Performance | HIGH | `server-` |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
-| 5 | Re-render Optimization | MEDIUM | `rerender-` |
-| 6 | Rendering Performance | MEDIUM | `rendering-` |
-| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
-| 8 | Advanced Patterns | LOW | `advanced-` |
-
-## Quick Reference
-
-### 1. Eliminating Waterfalls (CRITICAL)
-
-- `async-defer-await` - Move await into branches where actually used
-- `async-parallel` - Use Promise.all() for independent operations
-- `async-dependencies` - Use better-all for partial dependencies
-- `async-api-routes` - Start promises early, await late in API routes
-- `async-suspense-boundaries` - Use Suspense to stream content
-
-### 2. Bundle Size Optimization (CRITICAL)
-
-- `bundle-barrel-imports` - Import directly, avoid barrel files
-- `bundle-dynamic-imports` - Use next/dynamic for heavy components
-- `bundle-defer-third-party` - Load analytics/logging after hydration
-- `bundle-conditional` - Load modules only when feature is activated
-- `bundle-preload` - Preload on hover/focus for perceived speed
-
-### 3. Server-Side Performance (HIGH)
-
-- `server-auth-actions` - Authenticate server actions like API routes
-- `server-cache-react` - Use React.cache() for per-request deduplication
-- `server-cache-lru` - Use LRU cache for cross-request caching
-- `server-dedup-props` - Avoid duplicate serialization in RSC props
-- `server-serialization` - Minimize data passed to client components
-- `server-parallel-fetching` - Restructure components to parallelize fetches
-- `server-after-nonblocking` - Use after() for non-blocking operations
-
-### 4. Client-Side Data Fetching (MEDIUM-HIGH)
-
-- `client-swr-dedup` - Use SWR for automatic request deduplication
-- `client-event-listeners` - Deduplicate global event listeners
-- `client-passive-event-listeners` - Use passive listeners for scroll
-- `client-localstorage-schema` - Version and minimize localStorage data
-
-### 5. Re-render Optimization (MEDIUM)
-
-- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
-- `rerender-memo` - Extract expensive work into memoized components
-- `rerender-memo-with-default-value` - Hoist default non-primitive props
-- `rerender-dependencies` - Use primitive dependencies in effects
-- `rerender-derived-state` - Subscribe to derived booleans, not raw values
-- `rerender-derived-state-no-effect` - Derive state during render, not effects
-- `rerender-functional-setstate` - Use functional setState for stable callbacks
-- `rerender-lazy-state-init` - Pass function to useState for expensive values
-- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
-- `rerender-move-effect-to-event` - Put interaction logic in event handlers
-- `rerender-transitions` - Use startTransition for non-urgent updates
-- `rerender-use-ref-transient-values` - Use refs for transient frequent values
-
-### 6. Rendering Performance (MEDIUM)
-
-- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
-- `rendering-content-visibility` - Use content-visibility for long lists
-- `rendering-hoist-jsx` - Extract static JSX outside components
-- `rendering-svg-precision` - Reduce SVG coordinate precision
-- `rendering-hydration-no-flicker` - Use inline script for client-only data
-- `rendering-hydration-suppress-warning` - Suppress expected mismatches
-- `rendering-activity` - Use Activity component for show/hide
-- `rendering-conditional-render` - Use ternary, not && for conditionals
-- `rendering-usetransition-loading` - Prefer useTransition for loading state
-
-### 7. JavaScript Performance (LOW-MEDIUM)
-
-- `js-batch-dom-css` - Group CSS changes via classes or cssText
-- `js-index-maps` - Build Map for repeated lookups
-- `js-cache-property-access` - Cache object properties in loops
-- `js-cache-function-results` - Cache function results in module-level Map
-- `js-cache-storage` - Cache localStorage/sessionStorage reads
-- `js-combine-iterations` - Combine multiple filter/map into one loop
-- `js-length-check-first` - Check array length before expensive comparison
-- `js-early-exit` - Return early from functions
-- `js-hoist-regexp` - Hoist RegExp creation outside loops
-- `js-min-max-loop` - Use loop for min/max instead of sort
-- `js-set-map-lookups` - Use Set/Map for O(1) lookups
-- `js-tosorted-immutable` - Use toSorted() for immutability
-
-### 8. Advanced Patterns (LOW)
-
-- `advanced-event-handler-refs` - Store event handlers in refs
-- `advanced-init-once` - Initialize app once per app load
-- `advanced-use-latest` - useLatest for stable callback refs
-
-## How to Use
-
-Read individual rule files for detailed explanations and code examples:
-
-```
-rules/async-parallel.md
-rules/bundle-barrel-imports.md
-```
-
-Each rule file contains:
-- Brief explanation of why it matters
-- Incorrect code example with explanation
-- Correct code example with explanation
-- Additional context and references
-
-## Full Compiled Document
-
-For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/.agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md b/.agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
deleted file mode 100644
index 97e7ade24..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Store Event Handlers in Refs
-impact: LOW
-impactDescription: stable subscriptions
-tags: advanced, hooks, refs, event-handlers, optimization
----
-
-## Store Event Handlers in Refs
-
-Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
-
-**Incorrect (re-subscribes on every render):**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
- useEffect(() => {
- window.addEventListener(event, handler)
- return () => window.removeEventListener(event, handler)
- }, [event, handler])
-}
-```
-
-**Correct (stable subscription):**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
- const handlerRef = useRef(handler)
- useEffect(() => {
- handlerRef.current = handler
- }, [handler])
-
- useEffect(() => {
- const listener = (e) => handlerRef.current(e)
- window.addEventListener(event, listener)
- return () => window.removeEventListener(event, listener)
- }, [event])
-}
-```
-
-**Alternative: use `useEffectEvent` if you're on latest React:**
-
-```tsx
-import { useEffectEvent } from 'react'
-
-function useWindowEvent(event: string, handler: (e) => void) {
- const onEvent = useEffectEvent(handler)
-
- useEffect(() => {
- window.addEventListener(event, onEvent)
- return () => window.removeEventListener(event, onEvent)
- }, [event])
-}
-```
-
-`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
diff --git a/.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md b/.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md
deleted file mode 100644
index 73ee38e5e..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-title: Initialize App Once, Not Per Mount
-impact: LOW-MEDIUM
-impactDescription: avoids duplicate init in development
-tags: initialization, useEffect, app-startup, side-effects
----
-
-## Initialize App Once, Not Per Mount
-
-Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
-
-**Incorrect (runs twice in dev, re-runs on remount):**
-
-```tsx
-function Comp() {
- useEffect(() => {
- loadFromStorage()
- checkAuthToken()
- }, [])
-
- // ...
-}
-```
-
-**Correct (once per app load):**
-
-```tsx
-let didInit = false
-
-function Comp() {
- useEffect(() => {
- if (didInit) return
- didInit = true
- loadFromStorage()
- checkAuthToken()
- }, [])
-
- // ...
-}
-```
-
-Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
diff --git a/.agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md b/.agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md
deleted file mode 100644
index 9c7cb5016..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: useEffectEvent for Stable Callback Refs
-impact: LOW
-impactDescription: prevents effect re-runs
-tags: advanced, hooks, useEffectEvent, refs, optimization
----
-
-## useEffectEvent for Stable Callback Refs
-
-Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
-
-**Incorrect (effect re-runs on every callback change):**
-
-```tsx
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
- const [query, setQuery] = useState('')
-
- useEffect(() => {
- const timeout = setTimeout(() => onSearch(query), 300)
- return () => clearTimeout(timeout)
- }, [query, onSearch])
-}
-```
-
-**Correct (using React's useEffectEvent):**
-
-```tsx
-import { useEffectEvent } from 'react';
-
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
- const [query, setQuery] = useState('')
- const onSearchEvent = useEffectEvent(onSearch)
-
- useEffect(() => {
- const timeout = setTimeout(() => onSearchEvent(query), 300)
- return () => clearTimeout(timeout)
- }, [query])
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-api-routes.md b/.agents/skills/vercel-react-best-practices/rules/async-api-routes.md
deleted file mode 100644
index 6feda1ef0..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/async-api-routes.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: Prevent Waterfall Chains in API Routes
-impact: CRITICAL
-impactDescription: 2-10× improvement
-tags: api-routes, server-actions, waterfalls, parallelization
----
-
-## Prevent Waterfall Chains in API Routes
-
-In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
-
-**Incorrect (config waits for auth, data waits for both):**
-
-```typescript
-export async function GET(request: Request) {
- const session = await auth()
- const config = await fetchConfig()
- const data = await fetchData(session.user.id)
- return Response.json({ data, config })
-}
-```
-
-**Correct (auth and config start immediately):**
-
-```typescript
-export async function GET(request: Request) {
- const sessionPromise = auth()
- const configPromise = fetchConfig()
- const session = await sessionPromise
- const [config, data] = await Promise.all([
- configPromise,
- fetchData(session.user.id)
- ])
- return Response.json({ data, config })
-}
-```
-
-For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-defer-await.md b/.agents/skills/vercel-react-best-practices/rules/async-defer-await.md
deleted file mode 100644
index ea7082a36..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/async-defer-await.md
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: Defer Await Until Needed
-impact: HIGH
-impactDescription: avoids blocking unused code paths
-tags: async, await, conditional, optimization
----
-
-## Defer Await Until Needed
-
-Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
-
-**Incorrect (blocks both branches):**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
- const userData = await fetchUserData(userId)
-
- if (skipProcessing) {
- // Returns immediately but still waited for userData
- return { skipped: true }
- }
-
- // Only this branch uses userData
- return processUserData(userData)
-}
-```
-
-**Correct (only blocks when needed):**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
- if (skipProcessing) {
- // Returns immediately without waiting
- return { skipped: true }
- }
-
- // Fetch only when needed
- const userData = await fetchUserData(userId)
- return processUserData(userData)
-}
-```
-
-**Another example (early return optimization):**
-
-```typescript
-// Incorrect: always fetches permissions
-async function updateResource(resourceId: string, userId: string) {
- const permissions = await fetchPermissions(userId)
- const resource = await getResource(resourceId)
-
- if (!resource) {
- return { error: 'Not found' }
- }
-
- if (!permissions.canEdit) {
- return { error: 'Forbidden' }
- }
-
- return await updateResourceData(resource, permissions)
-}
-
-// Correct: fetches only when needed
-async function updateResource(resourceId: string, userId: string) {
- const resource = await getResource(resourceId)
-
- if (!resource) {
- return { error: 'Not found' }
- }
-
- const permissions = await fetchPermissions(userId)
-
- if (!permissions.canEdit) {
- return { error: 'Forbidden' }
- }
-
- return await updateResourceData(resource, permissions)
-}
-```
-
-This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-dependencies.md b/.agents/skills/vercel-react-best-practices/rules/async-dependencies.md
deleted file mode 100644
index 0484ebab9..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/async-dependencies.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-title: Dependency-Based Parallelization
-impact: CRITICAL
-impactDescription: 2-10× improvement
-tags: async, parallelization, dependencies, better-all
----
-
-## Dependency-Based Parallelization
-
-For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
-
-**Incorrect (profile waits for config unnecessarily):**
-
-```typescript
-const [user, config] = await Promise.all([
- fetchUser(),
- fetchConfig()
-])
-const profile = await fetchProfile(user.id)
-```
-
-**Correct (config and profile run in parallel):**
-
-```typescript
-import { all } from 'better-all'
-
-const { user, config, profile } = await all({
- async user() { return fetchUser() },
- async config() { return fetchConfig() },
- async profile() {
- return fetchProfile((await this.$.user).id)
- }
-})
-```
-
-**Alternative without extra dependencies:**
-
-We can also create all the promises first, and do `Promise.all()` at the end.
-
-```typescript
-const userPromise = fetchUser()
-const profilePromise = userPromise.then(user => fetchProfile(user.id))
-
-const [user, config, profile] = await Promise.all([
- userPromise,
- fetchConfig(),
- profilePromise
-])
-```
-
-Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-parallel.md b/.agents/skills/vercel-react-best-practices/rules/async-parallel.md
deleted file mode 100644
index 64133f6c3..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/async-parallel.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-title: Promise.all() for Independent Operations
-impact: CRITICAL
-impactDescription: 2-10× improvement
-tags: async, parallelization, promises, waterfalls
----
-
-## Promise.all() for Independent Operations
-
-When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
-
-**Incorrect (sequential execution, 3 round trips):**
-
-```typescript
-const user = await fetchUser()
-const posts = await fetchPosts()
-const comments = await fetchComments()
-```
-
-**Correct (parallel execution, 1 round trip):**
-
-```typescript
-const [user, posts, comments] = await Promise.all([
- fetchUser(),
- fetchPosts(),
- fetchComments()
-])
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md b/.agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
deleted file mode 100644
index 1fbc05b04..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
+++ /dev/null
@@ -1,99 +0,0 @@
----
-title: Strategic Suspense Boundaries
-impact: HIGH
-impactDescription: faster initial paint
-tags: async, suspense, streaming, layout-shift
----
-
-## Strategic Suspense Boundaries
-
-Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
-
-**Incorrect (wrapper blocked by data fetching):**
-
-```tsx
-async function Page() {
- const data = await fetchData() // Blocks entire page
-
- return (
- <div>
- <div>Sidebar</div>
- <div>Header</div>
- <div>
- <DataDisplay data={data} />
- </div>
- <div>Footer</div>
- </div>
- )
-}
-```
-
-The entire layout waits for data even though only the middle section needs it.
-
-**Correct (wrapper shows immediately, data streams in):**
-
-```tsx
-function Page() {
- return (
- <div>
- <div>Sidebar</div>
- <div>Header</div>
- <div>
- <Suspense fallback={<Skeleton />}>
- <DataDisplay />
- </Suspense>
- </div>
- <div>Footer</div>
- </div>
- )
-}
-
-async function DataDisplay() {
- const data = await fetchData() // Only blocks this component
- return <div>{data.content}</div>
-}
-```
-
-Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
-
-**Alternative (share promise across components):**
-
-```tsx
-function Page() {
- // Start fetch immediately, but don't await
- const dataPromise = fetchData()
-
- return (
- <div>
- <div>Sidebar</div>
- <div>Header</div>
- <Suspense fallback={<Skeleton />}>
- <DataDisplay dataPromise={dataPromise} />
- <DataSummary dataPromise={dataPromise} />
- </Suspense>
- <div>Footer</div>
- </div>
- )
-}
-
-function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
- const data = use(dataPromise) // Unwraps the promise
- return <div>{data.content}</div>
-}
-
-function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
- const data = use(dataPromise) // Reuses the same promise
- return <div>{data.summary}</div>
-}
-```
-
-Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
-
-**When NOT to use this pattern:**
-
-- Critical data needed for layout decisions (affects positioning)
-- SEO-critical content above the fold
-- Small, fast queries where suspense overhead isn't worth it
-- When you want to avoid layout shift (loading → content jump)
-
-**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md b/.agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
deleted file mode 100644
index ee48f3273..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: Avoid Barrel File Imports
-impact: CRITICAL
-impactDescription: 200-800ms import cost, slow builds
-tags: bundle, imports, tree-shaking, barrel-files, performance
----
-
-## Avoid Barrel File Imports
-
-Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
-
-Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
-
-**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
-
-**Incorrect (imports entire library):**
-
-```tsx
-import { Check, X, Menu } from 'lucide-react'
-// Loads 1,583 modules, takes ~2.8s extra in dev
-// Runtime cost: 200-800ms on every cold start
-
-import { Button, TextField } from '@mui/material'
-// Loads 2,225 modules, takes ~4.2s extra in dev
-```
-
-**Correct (imports only what you need):**
-
-```tsx
-import Check from 'lucide-react/dist/esm/icons/check'
-import X from 'lucide-react/dist/esm/icons/x'
-import Menu from 'lucide-react/dist/esm/icons/menu'
-// Loads only 3 modules (~2KB vs ~1MB)
-
-import Button from '@mui/material/Button'
-import TextField from '@mui/material/TextField'
-// Loads only what you use
-```
-
-**Alternative (Next.js 13.5+):**
-
-```js
-// next.config.js - use optimizePackageImports
-module.exports = {
- experimental: {
- optimizePackageImports: ['lucide-react', '@mui/material']
- }
-}
-
-// Then you can keep the ergonomic barrel imports:
-import { Check, X, Menu } from 'lucide-react'
-// Automatically transformed to direct imports at build time
-```
-
-Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
-
-Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
-
-Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md b/.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md
deleted file mode 100644
index 99d6fc90e..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-title: Conditional Module Loading
-impact: HIGH
-impactDescription: loads large data only when needed
-tags: bundle, conditional-loading, lazy-loading
----
-
-## Conditional Module Loading
-
-Load large data or modules only when a feature is activated.
-
-**Example (lazy-load animation frames):**
-
-```tsx
-function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
- const [frames, setFrames] = useState<Frame[] | null>(null)
-
- useEffect(() => {
- if (enabled && !frames && typeof window !== 'undefined') {
- import('./animation-frames.js')
- .then(mod => setFrames(mod.frames))
- .catch(() => setEnabled(false))
- }
- }, [enabled, frames, setEnabled])
-
- if (!frames) return <Skeleton />
- return <Canvas frames={frames} />
-}
-```
-
-The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md b/.agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
deleted file mode 100644
index db041d151..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
+++ /dev/null
@@ -1,49 +0,0 @@
----
-title: Defer Non-Critical Third-Party Libraries
-impact: MEDIUM
-impactDescription: loads after hydration
-tags: bundle, third-party, analytics, defer
----
-
-## Defer Non-Critical Third-Party Libraries
-
-Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
-
-**Incorrect (blocks initial bundle):**
-
-```tsx
-import { Analytics } from '@vercel/analytics/react'
-
-export default function RootLayout({ children }) {
- return (
- <html>
- <body>
- {children}
- <Analytics />
- </body>
- </html>
- )
-}
-```
-
-**Correct (loads after hydration):**
-
-```tsx
-import dynamic from 'next/dynamic'
-
-const Analytics = dynamic(
- () => import('@vercel/analytics/react').then(m => m.Analytics),
- { ssr: false }
-)
-
-export default function RootLayout({ children }) {
- return (
- <html>
- <body>
- {children}
- <Analytics />
- </body>
- </html>
- )
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md b/.agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
deleted file mode 100644
index 60b62695e..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: Dynamic Imports for Heavy Components
-impact: CRITICAL
-impactDescription: directly affects TTI and LCP
-tags: bundle, dynamic-import, code-splitting, next-dynamic
----
-
-## Dynamic Imports for Heavy Components
-
-Use `next/dynamic` to lazy-load large components not needed on initial render.
-
-**Incorrect (Monaco bundles with main chunk ~300KB):**
-
-```tsx
-import { MonacoEditor } from './monaco-editor'
-
-function CodePanel({ code }: { code: string }) {
- return <MonacoEditor value={code} />
-}
-```
-
-**Correct (Monaco loads on demand):**
-
-```tsx
-import dynamic from 'next/dynamic'
-
-const MonacoEditor = dynamic(
- () => import('./monaco-editor').then(m => m.MonacoEditor),
- { ssr: false }
-)
-
-function CodePanel({ code }: { code: string }) {
- return <MonacoEditor value={code} />
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/bundle-preload.md b/.agents/skills/vercel-react-best-practices/rules/bundle-preload.md
deleted file mode 100644
index 700050406..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/bundle-preload.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-title: Preload Based on User Intent
-impact: MEDIUM
-impactDescription: reduces perceived latency
-tags: bundle, preload, user-intent, hover
----
-
-## Preload Based on User Intent
-
-Preload heavy bundles before they're needed to reduce perceived latency.
-
-**Example (preload on hover/focus):**
-
-```tsx
-function EditorButton({ onClick }: { onClick: () => void }) {
- const preload = () => {
- if (typeof window !== 'undefined') {
- void import('./monaco-editor')
- }
- }
-
- return (
- <button
- onMouseEnter={preload}
- onFocus={preload}
- onClick={onClick}
- >
- Open Editor
- </button>
- )
-}
-```
-
-**Example (preload when feature flag is enabled):**
-
-```tsx
-function FlagsProvider({ children, flags }: Props) {
- useEffect(() => {
- if (flags.editorEnabled && typeof window !== 'undefined') {
- void import('./monaco-editor').then(mod => mod.init())
- }
- }, [flags.editorEnabled])
-
- return <FlagsContext.Provider value={flags}>
- {children}
- </FlagsContext.Provider>
-}
-```
-
-The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
diff --git a/.agents/skills/vercel-react-best-practices/rules/client-event-listeners.md b/.agents/skills/vercel-react-best-practices/rules/client-event-listeners.md
deleted file mode 100644
index aad4ae916..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/client-event-listeners.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: Deduplicate Global Event Listeners
-impact: LOW
-impactDescription: single listener for N components
-tags: client, swr, event-listeners, subscription
----
-
-## Deduplicate Global Event Listeners
-
-Use `useSWRSubscription()` to share global event listeners across component instances.
-
-**Incorrect (N instances = N listeners):**
-
-```tsx
-function useKeyboardShortcut(key: string, callback: () => void) {
- useEffect(() => {
- const handler = (e: KeyboardEvent) => {
- if (e.metaKey && e.key === key) {
- callback()
- }
- }
- window.addEventListener('keydown', handler)
- return () => window.removeEventListener('keydown', handler)
- }, [key, callback])
-}
-```
-
-When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
-
-**Correct (N instances = 1 listener):**
-
-```tsx
-import useSWRSubscription from 'swr/subscription'
-
-// Module-level Map to track callbacks per key
-const keyCallbacks = new Map<string, Set<() => void>>()
-
-function useKeyboardShortcut(key: string, callback: () => void) {
- // Register this callback in the Map
- useEffect(() => {
- if (!keyCallbacks.has(key)) {
- keyCallbacks.set(key, new Set())
- }
- keyCallbacks.get(key)!.add(callback)
-
- return () => {
- const set = keyCallbacks.get(key)
- if (set) {
- set.delete(callback)
- if (set.size === 0) {
- keyCallbacks.delete(key)
- }
- }
- }
- }, [key, callback])
-
- useSWRSubscription('global-keydown', () => {
- const handler = (e: KeyboardEvent) => {
- if (e.metaKey && keyCallbacks.has(e.key)) {
- keyCallbacks.get(e.key)!.forEach(cb => cb())
- }
- }
- window.addEventListener('keydown', handler)
- return () => window.removeEventListener('keydown', handler)
- })
-}
-
-function Profile() {
- // Multiple shortcuts will share the same listener
- useKeyboardShortcut('p', () => { /* ... */ })
- useKeyboardShortcut('k', () => { /* ... */ })
- // ...
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md b/.agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
deleted file mode 100644
index d30a1a7d4..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: Version and Minimize localStorage Data
-impact: MEDIUM
-impactDescription: prevents schema conflicts, reduces storage size
-tags: client, localStorage, storage, versioning, data-minimization
----
-
-## Version and Minimize localStorage Data
-
-Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
-
-**Incorrect:**
-
-```typescript
-// No version, stores everything, no error handling
-localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
-const data = localStorage.getItem('userConfig')
-```
-
-**Correct:**
-
-```typescript
-const VERSION = 'v2'
-
-function saveConfig(config: { theme: string; language: string }) {
- try {
- localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
- } catch {
- // Throws in incognito/private browsing, quota exceeded, or disabled
- }
-}
-
-function loadConfig() {
- try {
- const data = localStorage.getItem(`userConfig:${VERSION}`)
- return data ? JSON.parse(data) : null
- } catch {
- return null
- }
-}
-
-// Migration from v1 to v2
-function migrate() {
- try {
- const v1 = localStorage.getItem('userConfig:v1')
- if (v1) {
- const old = JSON.parse(v1)
- saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
- localStorage.removeItem('userConfig:v1')
- }
- } catch {}
-}
-```
-
-**Store minimal fields from server responses:**
-
-```typescript
-// User object has 20+ fields, only store what UI needs
-function cachePrefs(user: FullUser) {
- try {
- localStorage.setItem('prefs:v1', JSON.stringify({
- theme: user.preferences.theme,
- notifications: user.preferences.notifications
- }))
- } catch {}
-}
-```
-
-**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
-
-**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
diff --git a/.agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md b/.agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
deleted file mode 100644
index ce39a889e..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
+++ /dev/null
@@ -1,48 +0,0 @@
----
-title: Use Passive Event Listeners for Scrolling Performance
-impact: MEDIUM
-impactDescription: eliminates scroll delay caused by event listeners
-tags: client, event-listeners, scrolling, performance, touch, wheel
----
-
-## Use Passive Event Listeners for Scrolling Performance
-
-Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
-
-**Incorrect:**
-
-```typescript
-useEffect(() => {
- const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
- const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
-
- document.addEventListener('touchstart', handleTouch)
- document.addEventListener('wheel', handleWheel)
-
- return () => {
- document.removeEventListener('touchstart', handleTouch)
- document.removeEventListener('wheel', handleWheel)
- }
-}, [])
-```
-
-**Correct:**
-
-```typescript
-useEffect(() => {
- const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
- const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
-
- document.addEventListener('touchstart', handleTouch, { passive: true })
- document.addEventListener('wheel', handleWheel, { passive: true })
-
- return () => {
- document.removeEventListener('touchstart', handleTouch)
- document.removeEventListener('wheel', handleWheel)
- }
-}, [])
-```
-
-**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
-
-**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
diff --git a/.agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md b/.agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md
deleted file mode 100644
index 2a430f27f..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Use SWR for Automatic Deduplication
-impact: MEDIUM-HIGH
-impactDescription: automatic deduplication
-tags: client, swr, deduplication, data-fetching
----
-
-## Use SWR for Automatic Deduplication
-
-SWR enables request deduplication, caching, and revalidation across component instances.
-
-**Incorrect (no deduplication, each instance fetches):**
-
-```tsx
-function UserList() {
- const [users, setUsers] = useState([])
- useEffect(() => {
- fetch('/api/users')
- .then(r => r.json())
- .then(setUsers)
- }, [])
-}
-```
-
-**Correct (multiple instances share one request):**
-
-```tsx
-import useSWR from 'swr'
-
-function UserList() {
- const { data: users } = useSWR('/api/users', fetcher)
-}
-```
-
-**For immutable data:**
-
-```tsx
-import { useImmutableSWR } from '@/lib/swr'
-
-function StaticContent() {
- const { data } = useImmutableSWR('/api/config', fetcher)
-}
-```
-
-**For mutations:**
-
-```tsx
-import { useSWRMutation } from 'swr/mutation'
-
-function UpdateButton() {
- const { trigger } = useSWRMutation('/api/user', updateUser)
- return <button onClick={() => trigger()}>Update</button>
-}
-```
-
-Reference: [https://swr.vercel.app](https://swr.vercel.app)
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md b/.agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
deleted file mode 100644
index a62d84ed8..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
+++ /dev/null
@@ -1,107 +0,0 @@
----
-title: Avoid Layout Thrashing
-impact: MEDIUM
-impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
-tags: javascript, dom, css, performance, reflow, layout-thrashing
----
-
-## Avoid Layout Thrashing
-
-Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
-
-**This is OK (browser batches style changes):**
-```typescript
-function updateElementStyles(element: HTMLElement) {
- // Each line invalidates style, but browser batches the recalculation
- element.style.width = '100px'
- element.style.height = '200px'
- element.style.backgroundColor = 'blue'
- element.style.border = '1px solid black'
-}
-```
-
-**Incorrect (interleaved reads and writes force reflows):**
-```typescript
-function layoutThrashing(element: HTMLElement) {
- element.style.width = '100px'
- const width = element.offsetWidth // Forces reflow
- element.style.height = '200px'
- const height = element.offsetHeight // Forces another reflow
-}
-```
-
-**Correct (batch writes, then read once):**
-```typescript
-function updateElementStyles(element: HTMLElement) {
- // Batch all writes together
- element.style.width = '100px'
- element.style.height = '200px'
- element.style.backgroundColor = 'blue'
- element.style.border = '1px solid black'
-
- // Read after all writes are done (single reflow)
- const { width, height } = element.getBoundingClientRect()
-}
-```
-
-**Correct (batch reads, then writes):**
-```typescript
-function avoidThrashing(element: HTMLElement) {
- // Read phase - all layout queries first
- const rect1 = element.getBoundingClientRect()
- const offsetWidth = element.offsetWidth
- const offsetHeight = element.offsetHeight
-
- // Write phase - all style changes after
- element.style.width = '100px'
- element.style.height = '200px'
-}
-```
-
-**Better: use CSS classes**
-```css
-.highlighted-box {
- width: 100px;
- height: 200px;
- background-color: blue;
- border: 1px solid black;
-}
-```
-```typescript
-function updateElementStyles(element: HTMLElement) {
- element.classList.add('highlighted-box')
-
- const { width, height } = element.getBoundingClientRect()
-}
-```
-
-**React example:**
-```tsx
-// Incorrect: interleaving style changes with layout queries
-function Box({ isHighlighted }: { isHighlighted: boolean }) {
- const ref = useRef<HTMLDivElement>(null)
-
- useEffect(() => {
- if (ref.current && isHighlighted) {
- ref.current.style.width = '100px'
- const width = ref.current.offsetWidth // Forces layout
- ref.current.style.height = '200px'
- }
- }, [isHighlighted])
-
- return <div ref={ref}>Content</div>
-}
-
-// Correct: toggle class
-function Box({ isHighlighted }: { isHighlighted: boolean }) {
- return (
- <div className={isHighlighted ? 'highlighted-box' : ''}>
- Content
- </div>
- )
-}
-```
-
-Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
-
-See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md b/.agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md
deleted file mode 100644
index 180f8ac8f..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: Cache Repeated Function Calls
-impact: MEDIUM
-impactDescription: avoid redundant computation
-tags: javascript, cache, memoization, performance
----
-
-## Cache Repeated Function Calls
-
-Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
-
-**Incorrect (redundant computation):**
-
-```typescript
-function ProjectList({ projects }: { projects: Project[] }) {
- return (
- <div>
- {projects.map(project => {
- // slugify() called 100+ times for same project names
- const slug = slugify(project.name)
-
- return <ProjectCard key={project.id} slug={slug} />
- })}
- </div>
- )
-}
-```
-
-**Correct (cached results):**
-
-```typescript
-// Module-level cache
-const slugifyCache = new Map<string, string>()
-
-function cachedSlugify(text: string): string {
- if (slugifyCache.has(text)) {
- return slugifyCache.get(text)!
- }
- const result = slugify(text)
- slugifyCache.set(text, result)
- return result
-}
-
-function ProjectList({ projects }: { projects: Project[] }) {
- return (
- <div>
- {projects.map(project => {
- // Computed only once per unique project name
- const slug = cachedSlugify(project.name)
-
- return <ProjectCard key={project.id} slug={slug} />
- })}
- </div>
- )
-}
-```
-
-**Simpler pattern for single-value functions:**
-
-```typescript
-let isLoggedInCache: boolean | null = null
-
-function isLoggedIn(): boolean {
- if (isLoggedInCache !== null) {
- return isLoggedInCache
- }
-
- isLoggedInCache = document.cookie.includes('auth=')
- return isLoggedInCache
-}
-
-// Clear cache when auth changes
-function onAuthChange() {
- isLoggedInCache = null
-}
-```
-
-Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
-
-Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md b/.agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md
deleted file mode 100644
index 39eec9061..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-title: Cache Property Access in Loops
-impact: LOW-MEDIUM
-impactDescription: reduces lookups
-tags: javascript, loops, optimization, caching
----
-
-## Cache Property Access in Loops
-
-Cache object property lookups in hot paths.
-
-**Incorrect (3 lookups × N iterations):**
-
-```typescript
-for (let i = 0; i < arr.length; i++) {
- process(obj.config.settings.value)
-}
-```
-
-**Correct (1 lookup total):**
-
-```typescript
-const value = obj.config.settings.value
-const len = arr.length
-for (let i = 0; i < len; i++) {
- process(value)
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-cache-storage.md b/.agents/skills/vercel-react-best-practices/rules/js-cache-storage.md
deleted file mode 100644
index aa4a30c08..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-cache-storage.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: Cache Storage API Calls
-impact: LOW-MEDIUM
-impactDescription: reduces expensive I/O
-tags: javascript, localStorage, storage, caching, performance
----
-
-## Cache Storage API Calls
-
-`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
-
-**Incorrect (reads storage on every call):**
-
-```typescript
-function getTheme() {
- return localStorage.getItem('theme') ?? 'light'
-}
-// Called 10 times = 10 storage reads
-```
-
-**Correct (Map cache):**
-
-```typescript
-const storageCache = new Map<string, string | null>()
-
-function getLocalStorage(key: string) {
- if (!storageCache.has(key)) {
- storageCache.set(key, localStorage.getItem(key))
- }
- return storageCache.get(key)
-}
-
-function setLocalStorage(key: string, value: string) {
- localStorage.setItem(key, value)
- storageCache.set(key, value) // keep cache in sync
-}
-```
-
-Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
-
-**Cookie caching:**
-
-```typescript
-let cookieCache: Record<string, string> | null = null
-
-function getCookie(name: string) {
- if (!cookieCache) {
- cookieCache = Object.fromEntries(
- document.cookie.split('; ').map(c => c.split('='))
- )
- }
- return cookieCache[name]
-}
-```
-
-**Important (invalidate on external changes):**
-
-If storage can change externally (another tab, server-set cookies), invalidate cache:
-
-```typescript
-window.addEventListener('storage', (e) => {
- if (e.key) storageCache.delete(e.key)
-})
-
-document.addEventListener('visibilitychange', () => {
- if (document.visibilityState === 'visible') {
- storageCache.clear()
- }
-})
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md b/.agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md
deleted file mode 100644
index 044d017ec..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-title: Combine Multiple Array Iterations
-impact: LOW-MEDIUM
-impactDescription: reduces iterations
-tags: javascript, arrays, loops, performance
----
-
-## Combine Multiple Array Iterations
-
-Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
-
-**Incorrect (3 iterations):**
-
-```typescript
-const admins = users.filter(u => u.isAdmin)
-const testers = users.filter(u => u.isTester)
-const inactive = users.filter(u => !u.isActive)
-```
-
-**Correct (1 iteration):**
-
-```typescript
-const admins: User[] = []
-const testers: User[] = []
-const inactive: User[] = []
-
-for (const user of users) {
- if (user.isAdmin) admins.push(user)
- if (user.isTester) testers.push(user)
- if (!user.isActive) inactive.push(user)
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-early-exit.md b/.agents/skills/vercel-react-best-practices/rules/js-early-exit.md
deleted file mode 100644
index f46cb89c6..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-early-exit.md
+++ /dev/null
@@ -1,50 +0,0 @@
----
-title: Early Return from Functions
-impact: LOW-MEDIUM
-impactDescription: avoids unnecessary computation
-tags: javascript, functions, optimization, early-return
----
-
-## Early Return from Functions
-
-Return early when result is determined to skip unnecessary processing.
-
-**Incorrect (processes all items even after finding answer):**
-
-```typescript
-function validateUsers(users: User[]) {
- let hasError = false
- let errorMessage = ''
-
- for (const user of users) {
- if (!user.email) {
- hasError = true
- errorMessage = 'Email required'
- }
- if (!user.name) {
- hasError = true
- errorMessage = 'Name required'
- }
- // Continues checking all users even after error found
- }
-
- return hasError ? { valid: false, error: errorMessage } : { valid: true }
-}
-```
-
-**Correct (returns immediately on first error):**
-
-```typescript
-function validateUsers(users: User[]) {
- for (const user of users) {
- if (!user.email) {
- return { valid: false, error: 'Email required' }
- }
- if (!user.name) {
- return { valid: false, error: 'Name required' }
- }
- }
-
- return { valid: true }
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md b/.agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
deleted file mode 100644
index dae3fefdc..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-title: Hoist RegExp Creation
-impact: LOW-MEDIUM
-impactDescription: avoids recreation
-tags: javascript, regexp, optimization, memoization
----
-
-## Hoist RegExp Creation
-
-Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
-
-**Incorrect (new RegExp every render):**
-
-```tsx
-function Highlighter({ text, query }: Props) {
- const regex = new RegExp(`(${query})`, 'gi')
- const parts = text.split(regex)
- return <>{parts.map((part, i) => ...)}</>
-}
-```
-
-**Correct (memoize or hoist):**
-
-```tsx
-const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
-
-function Highlighter({ text, query }: Props) {
- const regex = useMemo(
- () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
- [query]
- )
- const parts = text.split(regex)
- return <>{parts.map((part, i) => ...)}</>
-}
-```
-
-**Warning (global regex has mutable state):**
-
-Global regex (`/g`) has mutable `lastIndex` state:
-
-```typescript
-const regex = /foo/g
-regex.test('foo') // true, lastIndex = 3
-regex.test('foo') // false, lastIndex = 0
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-index-maps.md b/.agents/skills/vercel-react-best-practices/rules/js-index-maps.md
deleted file mode 100644
index 9d357a00b..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-index-maps.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-title: Build Index Maps for Repeated Lookups
-impact: LOW-MEDIUM
-impactDescription: 1M ops to 2K ops
-tags: javascript, map, indexing, optimization, performance
----
-
-## Build Index Maps for Repeated Lookups
-
-Multiple `.find()` calls by the same key should use a Map.
-
-**Incorrect (O(n) per lookup):**
-
-```typescript
-function processOrders(orders: Order[], users: User[]) {
- return orders.map(order => ({
- ...order,
- user: users.find(u => u.id === order.userId)
- }))
-}
-```
-
-**Correct (O(1) per lookup):**
-
-```typescript
-function processOrders(orders: Order[], users: User[]) {
- const userById = new Map(users.map(u => [u.id, u]))
-
- return orders.map(order => ({
- ...order,
- user: userById.get(order.userId)
- }))
-}
-```
-
-Build map once (O(n)), then all lookups are O(1).
-For 1000 orders × 1000 users: 1M ops → 2K ops.
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-length-check-first.md b/.agents/skills/vercel-react-best-practices/rules/js-length-check-first.md
deleted file mode 100644
index 8b8957363..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-length-check-first.md
+++ /dev/null
@@ -1,49 +0,0 @@
----
-title: Early Length Check for Array Comparisons
-impact: MEDIUM-HIGH
-impactDescription: avoids expensive operations when lengths differ
-tags: javascript, arrays, performance, optimization, comparison
----
-
-## Early Length Check for Array Comparisons
-
-When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
-
-In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
-
-**Incorrect (always runs expensive comparison):**
-
-```typescript
-function hasChanges(current: string[], original: string[]) {
- // Always sorts and joins, even when lengths differ
- return current.sort().join() !== original.sort().join()
-}
-```
-
-Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
-
-**Correct (O(1) length check first):**
-
-```typescript
-function hasChanges(current: string[], original: string[]) {
- // Early return if lengths differ
- if (current.length !== original.length) {
- return true
- }
- // Only sort when lengths match
- const currentSorted = current.toSorted()
- const originalSorted = original.toSorted()
- for (let i = 0; i < currentSorted.length; i++) {
- if (currentSorted[i] !== originalSorted[i]) {
- return true
- }
- }
- return false
-}
-```
-
-This new approach is more efficient because:
-- It avoids the overhead of sorting and joining the arrays when lengths differ
-- It avoids consuming memory for the joined strings (especially important for large arrays)
-- It avoids mutating the original arrays
-- It returns early when a difference is found
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md b/.agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md
deleted file mode 100644
index 4b6656e96..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md
+++ /dev/null
@@ -1,82 +0,0 @@
----
-title: Use Loop for Min/Max Instead of Sort
-impact: LOW
-impactDescription: O(n) instead of O(n log n)
-tags: javascript, arrays, performance, sorting, algorithms
----
-
-## Use Loop for Min/Max Instead of Sort
-
-Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
-
-**Incorrect (O(n log n) - sort to find latest):**
-
-```typescript
-interface Project {
- id: string
- name: string
- updatedAt: number
-}
-
-function getLatestProject(projects: Project[]) {
- const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
- return sorted[0]
-}
-```
-
-Sorts the entire array just to find the maximum value.
-
-**Incorrect (O(n log n) - sort for oldest and newest):**
-
-```typescript
-function getOldestAndNewest(projects: Project[]) {
- const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
- return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
-}
-```
-
-Still sorts unnecessarily when only min/max are needed.
-
-**Correct (O(n) - single loop):**
-
-```typescript
-function getLatestProject(projects: Project[]) {
- if (projects.length === 0) return null
-
- let latest = projects[0]
-
- for (let i = 1; i < projects.length; i++) {
- if (projects[i].updatedAt > latest.updatedAt) {
- latest = projects[i]
- }
- }
-
- return latest
-}
-
-function getOldestAndNewest(projects: Project[]) {
- if (projects.length === 0) return { oldest: null, newest: null }
-
- let oldest = projects[0]
- let newest = projects[0]
-
- for (let i = 1; i < projects.length; i++) {
- if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
- if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
- }
-
- return { oldest, newest }
-}
-```
-
-Single pass through the array, no copying, no sorting.
-
-**Alternative (Math.min/Math.max for small arrays):**
-
-```typescript
-const numbers = [5, 2, 8, 1, 9]
-const min = Math.min(...numbers)
-const max = Math.max(...numbers)
-```
-
-This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md b/.agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
deleted file mode 100644
index 680a4892e..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: Use Set/Map for O(1) Lookups
-impact: LOW-MEDIUM
-impactDescription: O(n) to O(1)
-tags: javascript, set, map, data-structures, performance
----
-
-## Use Set/Map for O(1) Lookups
-
-Convert arrays to Set/Map for repeated membership checks.
-
-**Incorrect (O(n) per check):**
-
-```typescript
-const allowedIds = ['a', 'b', 'c', ...]
-items.filter(item => allowedIds.includes(item.id))
-```
-
-**Correct (O(1) per check):**
-
-```typescript
-const allowedIds = new Set(['a', 'b', 'c', ...])
-items.filter(item => allowedIds.has(item.id))
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md b/.agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
deleted file mode 100644
index eae8b3f8a..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
+++ /dev/null
@@ -1,57 +0,0 @@
----
-title: Use toSorted() Instead of sort() for Immutability
-impact: MEDIUM-HIGH
-impactDescription: prevents mutation bugs in React state
-tags: javascript, arrays, immutability, react, state, mutation
----
-
-## Use toSorted() Instead of sort() for Immutability
-
-`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
-
-**Incorrect (mutates original array):**
-
-```typescript
-function UserList({ users }: { users: User[] }) {
- // Mutates the users prop array!
- const sorted = useMemo(
- () => users.sort((a, b) => a.name.localeCompare(b.name)),
- [users]
- )
- return <div>{sorted.map(renderUser)}</div>
-}
-```
-
-**Correct (creates new array):**
-
-```typescript
-function UserList({ users }: { users: User[] }) {
- // Creates new sorted array, original unchanged
- const sorted = useMemo(
- () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
- [users]
- )
- return <div>{sorted.map(renderUser)}</div>
-}
-```
-
-**Why this matters in React:**
-
-1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
-2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
-
-**Browser support (fallback for older browsers):**
-
-`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
-
-```typescript
-// Fallback for older browsers
-const sorted = [...items].sort((a, b) => a.value - b.value)
-```
-
-**Other immutable array methods:**
-
-- `.toSorted()` - immutable sort
-- `.toReversed()` - immutable reverse
-- `.toSpliced()` - immutable splice
-- `.with()` - immutable element replacement
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-activity.md b/.agents/skills/vercel-react-best-practices/rules/rendering-activity.md
deleted file mode 100644
index c957a490b..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-activity.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-title: Use Activity Component for Show/Hide
-impact: MEDIUM
-impactDescription: preserves state/DOM
-tags: rendering, activity, visibility, state-preservation
----
-
-## Use Activity Component for Show/Hide
-
-Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
-
-**Usage:**
-
-```tsx
-import { Activity } from 'react'
-
-function Dropdown({ isOpen }: Props) {
- return (
- <Activity mode={isOpen ? 'visible' : 'hidden'}>
- <ExpensiveMenu />
- </Activity>
- )
-}
-```
-
-Avoids expensive re-renders and state loss.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md b/.agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
deleted file mode 100644
index 646744cbe..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-title: Animate SVG Wrapper Instead of SVG Element
-impact: LOW
-impactDescription: enables hardware acceleration
-tags: rendering, svg, css, animation, performance
----
-
-## Animate SVG Wrapper Instead of SVG Element
-
-Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
-
-**Incorrect (animating SVG directly - no hardware acceleration):**
-
-```tsx
-function LoadingSpinner() {
- return (
- <svg
- className="animate-spin"
- width="24"
- height="24"
- viewBox="0 0 24 24"
- >
- <circle cx="12" cy="12" r="10" stroke="currentColor" />
- </svg>
- )
-}
-```
-
-**Correct (animating wrapper div - hardware accelerated):**
-
-```tsx
-function LoadingSpinner() {
- return (
- <div className="animate-spin">
- <svg
- width="24"
- height="24"
- viewBox="0 0 24 24"
- >
- <circle cx="12" cy="12" r="10" stroke="currentColor" />
- </svg>
- </div>
- )
-}
-```
-
-This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md b/.agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
deleted file mode 100644
index 7e866f585..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
+++ /dev/null
@@ -1,40 +0,0 @@
----
-title: Use Explicit Conditional Rendering
-impact: LOW
-impactDescription: prevents rendering 0 or NaN
-tags: rendering, conditional, jsx, falsy-values
----
-
-## Use Explicit Conditional Rendering
-
-Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
-
-**Incorrect (renders "0" when count is 0):**
-
-```tsx
-function Badge({ count }: { count: number }) {
- return (
- <div>
- {count && <span className="badge">{count}</span>}
- </div>
- )
-}
-
-// When count = 0, renders: <div>0</div>
-// When count = 5, renders: <div><span class="badge">5</span></div>
-```
-
-**Correct (renders nothing when count is 0):**
-
-```tsx
-function Badge({ count }: { count: number }) {
- return (
- <div>
- {count > 0 ? <span className="badge">{count}</span> : null}
- </div>
- )
-}
-
-// When count = 0, renders: <div></div>
-// When count = 5, renders: <div><span class="badge">5</span></div>
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md b/.agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
deleted file mode 100644
index aa6656362..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: CSS content-visibility for Long Lists
-impact: HIGH
-impactDescription: faster initial render
-tags: rendering, css, content-visibility, long-lists
----
-
-## CSS content-visibility for Long Lists
-
-Apply `content-visibility: auto` to defer off-screen rendering.
-
-**CSS:**
-
-```css
-.message-item {
- content-visibility: auto;
- contain-intrinsic-size: 0 80px;
-}
-```
-
-**Example:**
-
-```tsx
-function MessageList({ messages }: { messages: Message[] }) {
- return (
- <div className="overflow-y-auto h-screen">
- {messages.map(msg => (
- <div key={msg.id} className="message-item">
- <Avatar user={msg.author} />
- <div>{msg.content}</div>
- </div>
- ))}
- </div>
- )
-}
-```
-
-For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md b/.agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
deleted file mode 100644
index 32d2f3fce..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-title: Hoist Static JSX Elements
-impact: LOW
-impactDescription: avoids re-creation
-tags: rendering, jsx, static, optimization
----
-
-## Hoist Static JSX Elements
-
-Extract static JSX outside components to avoid re-creation.
-
-**Incorrect (recreates element every render):**
-
-```tsx
-function LoadingSkeleton() {
- return <div className="animate-pulse h-20 bg-gray-200" />
-}
-
-function Container() {
- return (
- <div>
- {loading && <LoadingSkeleton />}
- </div>
- )
-}
-```
-
-**Correct (reuses same element):**
-
-```tsx
-const loadingSkeleton = (
- <div className="animate-pulse h-20 bg-gray-200" />
-)
-
-function Container() {
- return (
- <div>
- {loading && loadingSkeleton}
- </div>
- )
-}
-```
-
-This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md b/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
deleted file mode 100644
index 5cf0e79b6..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
+++ /dev/null
@@ -1,82 +0,0 @@
----
-title: Prevent Hydration Mismatch Without Flickering
-impact: MEDIUM
-impactDescription: avoids visual flicker and hydration errors
-tags: rendering, ssr, hydration, localStorage, flicker
----
-
-## Prevent Hydration Mismatch Without Flickering
-
-When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
-
-**Incorrect (breaks SSR):**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
- // localStorage is not available on server - throws error
- const theme = localStorage.getItem('theme') || 'light'
-
- return (
- <div className={theme}>
- {children}
- </div>
- )
-}
-```
-
-Server-side rendering will fail because `localStorage` is undefined.
-
-**Incorrect (visual flickering):**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
- const [theme, setTheme] = useState('light')
-
- useEffect(() => {
- // Runs after hydration - causes visible flash
- const stored = localStorage.getItem('theme')
- if (stored) {
- setTheme(stored)
- }
- }, [])
-
- return (
- <div className={theme}>
- {children}
- </div>
- )
-}
-```
-
-Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
-
-**Correct (no flicker, no hydration mismatch):**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
- return (
- <>
- <div id="theme-wrapper">
- {children}
- </div>
- <script
- dangerouslySetInnerHTML={{
- __html: `
- (function() {
- try {
- var theme = localStorage.getItem('theme') || 'light';
- var el = document.getElementById('theme-wrapper');
- if (el) el.className = theme;
- } catch (e) {}
- })();
- `,
- }}
- />
- </>
- )
-}
-```
-
-The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
-
-This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md b/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
deleted file mode 100644
index 24ba2513a..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-title: Suppress Expected Hydration Mismatches
-impact: LOW-MEDIUM
-impactDescription: avoids noisy hydration warnings for known differences
-tags: rendering, hydration, ssr, nextjs
----
-
-## Suppress Expected Hydration Mismatches
-
-In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
-
-**Incorrect (known mismatch warnings):**
-
-```tsx
-function Timestamp() {
- return <span>{new Date().toLocaleString()}</span>
-}
-```
-
-**Correct (suppress expected mismatch only):**
-
-```tsx
-function Timestamp() {
- return (
- <span suppressHydrationWarning>
- {new Date().toLocaleString()}
- </span>
- )
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md b/.agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
deleted file mode 100644
index 6d7712860..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
+++ /dev/null
@@ -1,28 +0,0 @@
----
-title: Optimize SVG Precision
-impact: LOW
-impactDescription: reduces file size
-tags: rendering, svg, optimization, svgo
----
-
-## Optimize SVG Precision
-
-Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
-
-**Incorrect (excessive precision):**
-
-```svg
-<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
-```
-
-**Correct (1 decimal place):**
-
-```svg
-<path d="M 10.3 20.8 L 30.9 40.2" />
-```
-
-**Automate with SVGO:**
-
-```bash
-npx svgo --precision=1 --multipass icon.svg
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md b/.agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
deleted file mode 100644
index 0c1b0b98e..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
+++ /dev/null
@@ -1,75 +0,0 @@
----
-title: Use useTransition Over Manual Loading States
-impact: LOW
-impactDescription: reduces re-renders and improves code clarity
-tags: rendering, transitions, useTransition, loading, state
----
-
-## Use useTransition Over Manual Loading States
-
-Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
-
-**Incorrect (manual loading state):**
-
-```tsx
-function SearchResults() {
- const [query, setQuery] = useState('')
- const [results, setResults] = useState([])
- const [isLoading, setIsLoading] = useState(false)
-
- const handleSearch = async (value: string) => {
- setIsLoading(true)
- setQuery(value)
- const data = await fetchResults(value)
- setResults(data)
- setIsLoading(false)
- }
-
- return (
- <>
- <input onChange={(e) => handleSearch(e.target.value)} />
- {isLoading && <Spinner />}
- <ResultsList results={results} />
- </>
- )
-}
-```
-
-**Correct (useTransition with built-in pending state):**
-
-```tsx
-import { useTransition, useState } from 'react'
-
-function SearchResults() {
- const [query, setQuery] = useState('')
- const [results, setResults] = useState([])
- const [isPending, startTransition] = useTransition()
-
- const handleSearch = (value: string) => {
- setQuery(value) // Update input immediately
-
- startTransition(async () => {
- // Fetch and update results
- const data = await fetchResults(value)
- setResults(data)
- })
- }
-
- return (
- <>
- <input onChange={(e) => handleSearch(e.target.value)} />
- {isPending && <Spinner />}
- <ResultsList results={results} />
- </>
- )
-}
-```
-
-**Benefits:**
-
-- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
-- **Error resilience**: Pending state correctly resets even if the transition throws
-- **Better responsiveness**: Keeps the UI responsive during updates
-- **Interrupt handling**: New transitions automatically cancel pending ones
-
-Reference: [useTransition](https://react.dev/reference/react/useTransition)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md b/.agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
deleted file mode 100644
index e867c95f0..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: Defer State Reads to Usage Point
-impact: MEDIUM
-impactDescription: avoids unnecessary subscriptions
-tags: rerender, searchParams, localStorage, optimization
----
-
-## Defer State Reads to Usage Point
-
-Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
-
-**Incorrect (subscribes to all searchParams changes):**
-
-```tsx
-function ShareButton({ chatId }: { chatId: string }) {
- const searchParams = useSearchParams()
-
- const handleShare = () => {
- const ref = searchParams.get('ref')
- shareChat(chatId, { ref })
- }
-
- return <button onClick={handleShare}>Share</button>
-}
-```
-
-**Correct (reads on demand, no subscription):**
-
-```tsx
-function ShareButton({ chatId }: { chatId: string }) {
- const handleShare = () => {
- const params = new URLSearchParams(window.location.search)
- const ref = params.get('ref')
- shareChat(chatId, { ref })
- }
-
- return <button onClick={handleShare}>Share</button>
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md b/.agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md
deleted file mode 100644
index 47a4d9268..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-title: Narrow Effect Dependencies
-impact: LOW
-impactDescription: minimizes effect re-runs
-tags: rerender, useEffect, dependencies, optimization
----
-
-## Narrow Effect Dependencies
-
-Specify primitive dependencies instead of objects to minimize effect re-runs.
-
-**Incorrect (re-runs on any user field change):**
-
-```tsx
-useEffect(() => {
- console.log(user.id)
-}, [user])
-```
-
-**Correct (re-runs only when id changes):**
-
-```tsx
-useEffect(() => {
- console.log(user.id)
-}, [user.id])
-```
-
-**For derived state, compute outside effect:**
-
-```tsx
-// Incorrect: runs on width=767, 766, 765...
-useEffect(() => {
- if (width < 768) {
- enableMobileMode()
- }
-}, [width])
-
-// Correct: runs only on boolean transition
-const isMobile = width < 768
-useEffect(() => {
- if (isMobile) {
- enableMobileMode()
- }
-}, [isMobile])
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md b/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
deleted file mode 100644
index 3d9fe4050..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
+++ /dev/null
@@ -1,40 +0,0 @@
----
-title: Calculate Derived State During Rendering
-impact: MEDIUM
-impactDescription: avoids redundant renders and state drift
-tags: rerender, derived-state, useEffect, state
----
-
-## Calculate Derived State During Rendering
-
-If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
-
-**Incorrect (redundant state and effect):**
-
-```tsx
-function Form() {
- const [firstName, setFirstName] = useState('First')
- const [lastName, setLastName] = useState('Last')
- const [fullName, setFullName] = useState('')
-
- useEffect(() => {
- setFullName(firstName + ' ' + lastName)
- }, [firstName, lastName])
-
- return <p>{fullName}</p>
-}
-```
-
-**Correct (derive during render):**
-
-```tsx
-function Form() {
- const [firstName, setFirstName] = useState('First')
- const [lastName, setLastName] = useState('Last')
- const fullName = firstName + ' ' + lastName
-
- return <p>{fullName}</p>
-}
-```
-
-References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md b/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md
deleted file mode 100644
index e5c899f6c..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: Subscribe to Derived State
-impact: MEDIUM
-impactDescription: reduces re-render frequency
-tags: rerender, derived-state, media-query, optimization
----
-
-## Subscribe to Derived State
-
-Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
-
-**Incorrect (re-renders on every pixel change):**
-
-```tsx
-function Sidebar() {
- const width = useWindowWidth() // updates continuously
- const isMobile = width < 768
- return <nav className={isMobile ? 'mobile' : 'desktop'} />
-}
-```
-
-**Correct (re-renders only when boolean changes):**
-
-```tsx
-function Sidebar() {
- const isMobile = useMediaQuery('(max-width: 767px)')
- return <nav className={isMobile ? 'mobile' : 'desktop'} />
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md b/.agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
deleted file mode 100644
index b004ef45e..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: Use Functional setState Updates
-impact: MEDIUM
-impactDescription: prevents stale closures and unnecessary callback recreations
-tags: react, hooks, useState, useCallback, callbacks, closures
----
-
-## Use Functional setState Updates
-
-When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
-
-**Incorrect (requires state as dependency):**
-
-```tsx
-function TodoList() {
- const [items, setItems] = useState(initialItems)
-
- // Callback must depend on items, recreated on every items change
- const addItems = useCallback((newItems: Item[]) => {
- setItems([...items, ...newItems])
- }, [items]) // ❌ items dependency causes recreations
-
- // Risk of stale closure if dependency is forgotten
- const removeItem = useCallback((id: string) => {
- setItems(items.filter(item => item.id !== id))
- }, []) // ❌ Missing items dependency - will use stale items!
-
- return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
-}
-```
-
-The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
-
-**Correct (stable callbacks, no stale closures):**
-
-```tsx
-function TodoList() {
- const [items, setItems] = useState(initialItems)
-
- // Stable callback, never recreated
- const addItems = useCallback((newItems: Item[]) => {
- setItems(curr => [...curr, ...newItems])
- }, []) // ✅ No dependencies needed
-
- // Always uses latest state, no stale closure risk
- const removeItem = useCallback((id: string) => {
- setItems(curr => curr.filter(item => item.id !== id))
- }, []) // ✅ Safe and stable
-
- return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
-}
-```
-
-**Benefits:**
-
-1. **Stable callback references** - Callbacks don't need to be recreated when state changes
-2. **No stale closures** - Always operates on the latest state value
-3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
-4. **Prevents bugs** - Eliminates the most common source of React closure bugs
-
-**When to use functional updates:**
-
-- Any setState that depends on the current state value
-- Inside useCallback/useMemo when state is needed
-- Event handlers that reference state
-- Async operations that update state
-
-**When direct updates are fine:**
-
-- Setting state to a static value: `setCount(0)`
-- Setting state from props/arguments only: `setName(newName)`
-- State doesn't depend on previous value
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md b/.agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
deleted file mode 100644
index 4ecb350fb..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
+++ /dev/null
@@ -1,58 +0,0 @@
----
-title: Use Lazy State Initialization
-impact: MEDIUM
-impactDescription: wasted computation on every render
-tags: react, hooks, useState, performance, initialization
----
-
-## Use Lazy State Initialization
-
-Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
-
-**Incorrect (runs on every render):**
-
-```tsx
-function FilteredList({ items }: { items: Item[] }) {
- // buildSearchIndex() runs on EVERY render, even after initialization
- const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
- const [query, setQuery] = useState('')
-
- // When query changes, buildSearchIndex runs again unnecessarily
- return <SearchResults index={searchIndex} query={query} />
-}
-
-function UserProfile() {
- // JSON.parse runs on every render
- const [settings, setSettings] = useState(
- JSON.parse(localStorage.getItem('settings') || '{}')
- )
-
- return <SettingsForm settings={settings} onChange={setSettings} />
-}
-```
-
-**Correct (runs only once):**
-
-```tsx
-function FilteredList({ items }: { items: Item[] }) {
- // buildSearchIndex() runs ONLY on initial render
- const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
- const [query, setQuery] = useState('')
-
- return <SearchResults index={searchIndex} query={query} />
-}
-
-function UserProfile() {
- // JSON.parse runs only on initial render
- const [settings, setSettings] = useState(() => {
- const stored = localStorage.getItem('settings')
- return stored ? JSON.parse(stored) : {}
- })
-
- return <SettingsForm settings={settings} onChange={setSettings} />
-}
-```
-
-Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
-
-For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md b/.agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
deleted file mode 100644
index 635704918..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-
-title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
-impact: MEDIUM
-impactDescription: restores memoization by using a constant for default value
-tags: rerender, memo, optimization
-
----
-
-## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
-
-When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
-
-To address this issue, extract the default value into a constant.
-
-**Incorrect (`onClick` has different values on every rerender):**
-
-```tsx
-const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
- // ...
-})
-
-// Used without optional onClick
-<UserAvatar />
-```
-
-**Correct (stable default value):**
-
-```tsx
-const NOOP = () => {};
-
-const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
- // ...
-})
-
-// Used without optional onClick
-<UserAvatar />
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-memo.md b/.agents/skills/vercel-react-best-practices/rules/rerender-memo.md
deleted file mode 100644
index f8982ab61..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-memo.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-title: Extract to Memoized Components
-impact: MEDIUM
-impactDescription: enables early returns
-tags: rerender, memo, useMemo, optimization
----
-
-## Extract to Memoized Components
-
-Extract expensive work into memoized components to enable early returns before computation.
-
-**Incorrect (computes avatar even when loading):**
-
-```tsx
-function Profile({ user, loading }: Props) {
- const avatar = useMemo(() => {
- const id = computeAvatarId(user)
- return <Avatar id={id} />
- }, [user])
-
- if (loading) return <Skeleton />
- return <div>{avatar}</div>
-}
-```
-
-**Correct (skips computation when loading):**
-
-```tsx
-const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
- const id = useMemo(() => computeAvatarId(user), [user])
- return <Avatar id={id} />
-})
-
-function Profile({ user, loading }: Props) {
- if (loading) return <Skeleton />
- return (
- <div>
- <UserAvatar user={user} />
- </div>
- )
-}
-```
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md b/.agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
deleted file mode 100644
index dd58a1af0..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-title: Put Interaction Logic in Event Handlers
-impact: MEDIUM
-impactDescription: avoids effect re-runs and duplicate side effects
-tags: rerender, useEffect, events, side-effects, dependencies
----
-
-## Put Interaction Logic in Event Handlers
-
-If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
-
-**Incorrect (event modeled as state + effect):**
-
-```tsx
-function Form() {
- const [submitted, setSubmitted] = useState(false)
- const theme = useContext(ThemeContext)
-
- useEffect(() => {
- if (submitted) {
- post('/api/register')
- showToast('Registered', theme)
- }
- }, [submitted, theme])
-
- return <button onClick={() => setSubmitted(true)}>Submit</button>
-}
-```
-
-**Correct (do it in the handler):**
-
-```tsx
-function Form() {
- const theme = useContext(ThemeContext)
-
- function handleSubmit() {
- post('/api/register')
- showToast('Registered', theme)
- }
-
- return <button onClick={handleSubmit}>Submit</button>
-}
-```
-
-Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md b/.agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
deleted file mode 100644
index 59dfab0f3..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: Do not wrap a simple expression with a primitive result type in useMemo
-impact: LOW-MEDIUM
-impactDescription: wasted computation on every render
-tags: rerender, useMemo, optimization
----
-
-## Do not wrap a simple expression with a primitive result type in useMemo
-
-When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
-Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
-
-**Incorrect:**
-
-```tsx
-function Header({ user, notifications }: Props) {
- const isLoading = useMemo(() => {
- return user.isLoading || notifications.isLoading
- }, [user.isLoading, notifications.isLoading])
-
- if (isLoading) return <Skeleton />
- // return some markup
-}
-```
-
-**Correct:**
-
-```tsx
-function Header({ user, notifications }: Props) {
- const isLoading = user.isLoading || notifications.isLoading
-
- if (isLoading) return <Skeleton />
- // return some markup
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-transitions.md b/.agents/skills/vercel-react-best-practices/rules/rerender-transitions.md
deleted file mode 100644
index d99f43f76..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-transitions.md
+++ /dev/null
@@ -1,40 +0,0 @@
----
-title: Use Transitions for Non-Urgent Updates
-impact: MEDIUM
-impactDescription: maintains UI responsiveness
-tags: rerender, transitions, startTransition, performance
----
-
-## Use Transitions for Non-Urgent Updates
-
-Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
-
-**Incorrect (blocks UI on every scroll):**
-
-```tsx
-function ScrollTracker() {
- const [scrollY, setScrollY] = useState(0)
- useEffect(() => {
- const handler = () => setScrollY(window.scrollY)
- window.addEventListener('scroll', handler, { passive: true })
- return () => window.removeEventListener('scroll', handler)
- }, [])
-}
-```
-
-**Correct (non-blocking updates):**
-
-```tsx
-import { startTransition } from 'react'
-
-function ScrollTracker() {
- const [scrollY, setScrollY] = useState(0)
- useEffect(() => {
- const handler = () => {
- startTransition(() => setScrollY(window.scrollY))
- }
- window.addEventListener('scroll', handler, { passive: true })
- return () => window.removeEventListener('scroll', handler)
- }, [])
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md b/.agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
deleted file mode 100644
index cf04b81f8..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
+++ /dev/null
@@ -1,73 +0,0 @@
----
-title: Use useRef for Transient Values
-impact: MEDIUM
-impactDescription: avoids unnecessary re-renders on frequent updates
-tags: rerender, useref, state, performance
----
-
-## Use useRef for Transient Values
-
-When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
-
-**Incorrect (renders every update):**
-
-```tsx
-function Tracker() {
- const [lastX, setLastX] = useState(0)
-
- useEffect(() => {
- const onMove = (e: MouseEvent) => setLastX(e.clientX)
- window.addEventListener('mousemove', onMove)
- return () => window.removeEventListener('mousemove', onMove)
- }, [])
-
- return (
- <div
- style={{
- position: 'fixed',
- top: 0,
- left: lastX,
- width: 8,
- height: 8,
- background: 'black',
- }}
- />
- )
-}
-```
-
-**Correct (no re-render for tracking):**
-
-```tsx
-function Tracker() {
- const lastXRef = useRef(0)
- const dotRef = useRef<HTMLDivElement>(null)
-
- useEffect(() => {
- const onMove = (e: MouseEvent) => {
- lastXRef.current = e.clientX
- const node = dotRef.current
- if (node) {
- node.style.transform = `translateX(${e.clientX}px)`
- }
- }
- window.addEventListener('mousemove', onMove)
- return () => window.removeEventListener('mousemove', onMove)
- }, [])
-
- return (
- <div
- ref={dotRef}
- style={{
- position: 'fixed',
- top: 0,
- left: 0,
- width: 8,
- height: 8,
- background: 'black',
- transform: 'translateX(0px)',
- }}
- />
- )
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md b/.agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
deleted file mode 100644
index e8f5b260f..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
+++ /dev/null
@@ -1,73 +0,0 @@
----
-title: Use after() for Non-Blocking Operations
-impact: MEDIUM
-impactDescription: faster response times
-tags: server, async, logging, analytics, side-effects
----
-
-## Use after() for Non-Blocking Operations
-
-Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
-
-**Incorrect (blocks response):**
-
-```tsx
-import { logUserAction } from '@/app/utils'
-
-export async function POST(request: Request) {
- // Perform mutation
- await updateDatabase(request)
-
- // Logging blocks the response
- const userAgent = request.headers.get('user-agent') || 'unknown'
- await logUserAction({ userAgent })
-
- return new Response(JSON.stringify({ status: 'success' }), {
- status: 200,
- headers: { 'Content-Type': 'application/json' }
- })
-}
-```
-
-**Correct (non-blocking):**
-
-```tsx
-import { after } from 'next/server'
-import { headers, cookies } from 'next/headers'
-import { logUserAction } from '@/app/utils'
-
-export async function POST(request: Request) {
- // Perform mutation
- await updateDatabase(request)
-
- // Log after response is sent
- after(async () => {
- const userAgent = (await headers()).get('user-agent') || 'unknown'
- const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
-
- logUserAction({ sessionCookie, userAgent })
- })
-
- return new Response(JSON.stringify({ status: 'success' }), {
- status: 200,
- headers: { 'Content-Type': 'application/json' }
- })
-}
-```
-
-The response is sent immediately while logging happens in the background.
-
-**Common use cases:**
-
-- Analytics tracking
-- Audit logging
-- Sending notifications
-- Cache invalidation
-- Cleanup tasks
-
-**Important notes:**
-
-- `after()` runs even if the response fails or redirects
-- Works in Server Actions, Route Handlers, and Server Components
-
-Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-auth-actions.md b/.agents/skills/vercel-react-best-practices/rules/server-auth-actions.md
deleted file mode 100644
index ee82c0442..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/server-auth-actions.md
+++ /dev/null
@@ -1,96 +0,0 @@
----
-title: Authenticate Server Actions Like API Routes
-impact: CRITICAL
-impactDescription: prevents unauthorized access to server mutations
-tags: server, server-actions, authentication, security, authorization
----
-
-## Authenticate Server Actions Like API Routes
-
-**Impact: CRITICAL (prevents unauthorized access to server mutations)**
-
-Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
-
-Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
-
-**Incorrect (no authentication check):**
-
-```typescript
-'use server'
-
-export async function deleteUser(userId: string) {
- // Anyone can call this! No auth check
- await db.user.delete({ where: { id: userId } })
- return { success: true }
-}
-```
-
-**Correct (authentication inside the action):**
-
-```typescript
-'use server'
-
-import { verifySession } from '@/lib/auth'
-import { unauthorized } from '@/lib/errors'
-
-export async function deleteUser(userId: string) {
- // Always check auth inside the action
- const session = await verifySession()
-
- if (!session) {
- throw unauthorized('Must be logged in')
- }
-
- // Check authorization too
- if (session.user.role !== 'admin' && session.user.id !== userId) {
- throw unauthorized('Cannot delete other users')
- }
-
- await db.user.delete({ where: { id: userId } })
- return { success: true }
-}
-```
-
-**With input validation:**
-
-```typescript
-'use server'
-
-import { verifySession } from '@/lib/auth'
-import { z } from 'zod'
-
-const updateProfileSchema = z.object({
- userId: z.string().uuid(),
- name: z.string().min(1).max(100),
- email: z.string().email()
-})
-
-export async function updateProfile(data: unknown) {
- // Validate input first
- const validated = updateProfileSchema.parse(data)
-
- // Then authenticate
- const session = await verifySession()
- if (!session) {
- throw new Error('Unauthorized')
- }
-
- // Then authorize
- if (session.user.id !== validated.userId) {
- throw new Error('Can only update own profile')
- }
-
- // Finally perform the mutation
- await db.user.update({
- where: { id: validated.userId },
- data: {
- name: validated.name,
- email: validated.email
- }
- })
-
- return { success: true }
-}
-```
-
-Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-cache-lru.md b/.agents/skills/vercel-react-best-practices/rules/server-cache-lru.md
deleted file mode 100644
index ef6938aa5..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/server-cache-lru.md
+++ /dev/null
@@ -1,41 +0,0 @@
----
-title: Cross-Request LRU Caching
-impact: HIGH
-impactDescription: caches across requests
-tags: server, cache, lru, cross-request
----
-
-## Cross-Request LRU Caching
-
-`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
-
-**Implementation:**
-
-```typescript
-import { LRUCache } from 'lru-cache'
-
-const cache = new LRUCache<string, any>({
- max: 1000,
- ttl: 5 * 60 * 1000 // 5 minutes
-})
-
-export async function getUser(id: string) {
- const cached = cache.get(id)
- if (cached) return cached
-
- const user = await db.user.findUnique({ where: { id } })
- cache.set(id, user)
- return user
-}
-
-// Request 1: DB query, result cached
-// Request 2: cache hit, no DB query
-```
-
-Use when sequential user actions hit multiple endpoints needing the same data within seconds.
-
-**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
-
-**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
-
-Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-cache-react.md b/.agents/skills/vercel-react-best-practices/rules/server-cache-react.md
deleted file mode 100644
index 87c9ca331..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/server-cache-react.md
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: Per-Request Deduplication with React.cache()
-impact: MEDIUM
-impactDescription: deduplicates within request
-tags: server, cache, react-cache, deduplication
----
-
-## Per-Request Deduplication with React.cache()
-
-Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
-
-**Usage:**
-
-```typescript
-import { cache } from 'react'
-
-export const getCurrentUser = cache(async () => {
- const session = await auth()
- if (!session?.user?.id) return null
- return await db.user.findUnique({
- where: { id: session.user.id }
- })
-})
-```
-
-Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
-
-**Avoid inline objects as arguments:**
-
-`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
-
-**Incorrect (always cache miss):**
-
-```typescript
-const getUser = cache(async (params: { uid: number }) => {
- return await db.user.findUnique({ where: { id: params.uid } })
-})
-
-// Each call creates new object, never hits cache
-getUser({ uid: 1 })
-getUser({ uid: 1 }) // Cache miss, runs query again
-```
-
-**Correct (cache hit):**
-
-```typescript
-const getUser = cache(async (uid: number) => {
- return await db.user.findUnique({ where: { id: uid } })
-})
-
-// Primitive args use value equality
-getUser(1)
-getUser(1) // Cache hit, returns cached result
-```
-
-If you must pass objects, pass the same reference:
-
-```typescript
-const params = { uid: 1 }
-getUser(params) // Query runs
-getUser(params) // Cache hit (same reference)
-```
-
-**Next.js-Specific Note:**
-
-In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
-
-- Database queries (Prisma, Drizzle, etc.)
-- Heavy computations
-- Authentication checks
-- File system operations
-- Any non-fetch async work
-
-Use `React.cache()` to deduplicate these operations across your component tree.
-
-Reference: [React.cache documentation](https://react.dev/reference/react/cache)
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-dedup-props.md b/.agents/skills/vercel-react-best-practices/rules/server-dedup-props.md
deleted file mode 100644
index fb24a2562..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/server-dedup-props.md
+++ /dev/null
@@ -1,65 +0,0 @@
----
-title: Avoid Duplicate Serialization in RSC Props
-impact: LOW
-impactDescription: reduces network payload by avoiding duplicate serialization
-tags: server, rsc, serialization, props, client-components
----
-
-## Avoid Duplicate Serialization in RSC Props
-
-**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
-
-RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
-
-**Incorrect (duplicates array):**
-
-```tsx
-// RSC: sends 6 strings (2 arrays × 3 items)
-<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
-```
-
-**Correct (sends 3 strings):**
-
-```tsx
-// RSC: send once
-<ClientList usernames={usernames} />
-
-// Client: transform there
-'use client'
-const sorted = useMemo(() => [...usernames].sort(), [usernames])
-```
-
-**Nested deduplication behavior:**
-
-Deduplication works recursively. Impact varies by data type:
-
-- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
-- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
-
-```tsx
-// string[] - duplicates everything
-usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
-
-// object[] - duplicates array structure only
-users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
-```
-
-**Operations breaking deduplication (create new references):**
-
-- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
-- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
-
-**More examples:**
-
-```tsx
-// ❌ Bad
-<C users={users} active={users.filter(u => u.active)} />
-<C product={product} productName={product.name} />
-
-// ✅ Good
-<C users={users} />
-<C product={product} />
-// Do filtering/destructuring in client
-```
-
-**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md b/.agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
deleted file mode 100644
index 1affc835a..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
+++ /dev/null
@@ -1,83 +0,0 @@
----
-title: Parallel Data Fetching with Component Composition
-impact: CRITICAL
-impactDescription: eliminates server-side waterfalls
-tags: server, rsc, parallel-fetching, composition
----
-
-## Parallel Data Fetching with Component Composition
-
-React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
-
-**Incorrect (Sidebar waits for Page's fetch to complete):**
-
-```tsx
-export default async function Page() {
- const header = await fetchHeader()
- return (
- <div>
- <div>{header}</div>
- <Sidebar />
- </div>
- )
-}
-
-async function Sidebar() {
- const items = await fetchSidebarItems()
- return <nav>{items.map(renderItem)}</nav>
-}
-```
-
-**Correct (both fetch simultaneously):**
-
-```tsx
-async function Header() {
- const data = await fetchHeader()
- return <div>{data}</div>
-}
-
-async function Sidebar() {
- const items = await fetchSidebarItems()
- return <nav>{items.map(renderItem)}</nav>
-}
-
-export default function Page() {
- return (
- <div>
- <Header />
- <Sidebar />
- </div>
- )
-}
-```
-
-**Alternative with children prop:**
-
-```tsx
-async function Header() {
- const data = await fetchHeader()
- return <div>{data}</div>
-}
-
-async function Sidebar() {
- const items = await fetchSidebarItems()
- return <nav>{items.map(renderItem)}</nav>
-}
-
-function Layout({ children }: { children: ReactNode }) {
- return (
- <div>
- <Header />
- {children}
- </div>
- )
-}
-
-export default function Page() {
- return (
- <Layout>
- <Sidebar />
- </Layout>
- )
-}
-```
diff --git a/.agents/skills/vercel-react-best-practices/rules/server-serialization.md b/.agents/skills/vercel-react-best-practices/rules/server-serialization.md
deleted file mode 100644
index 39c5c4164..000000000
--- a/.agents/skills/vercel-react-best-practices/rules/server-serialization.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: Minimize Serialization at RSC Boundaries
-impact: HIGH
-impactDescription: reduces data transfer size
-tags: server, rsc, serialization, props
----
-
-## Minimize Serialization at RSC Boundaries
-
-The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
-
-**Incorrect (serializes all 50 fields):**
-
-```tsx
-async function Page() {
- const user = await fetchUser() // 50 fields
- return <Profile user={user} />
-}
-
-'use client'
-function Profile({ user }: { user: User }) {
- return <div>{user.name}</div> // uses 1 field
-}
-```
-
-**Correct (serializes only 1 field):**
-
-```tsx
-async function Page() {
- const user = await fetchUser()
- return <Profile name={user.name} />
-}
-
-'use client'
-function Profile({ name }: { name: string }) {
- return <div>{name}</div>
-}
-```
diff --git a/.agents/skills/web-design-guidelines/SKILL.md b/.agents/skills/web-design-guidelines/SKILL.md
deleted file mode 100644
index ceae92ab3..000000000
--- a/.agents/skills/web-design-guidelines/SKILL.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-name: web-design-guidelines
-description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
-metadata:
- author: vercel
- version: "1.0.0"
- argument-hint: <file-or-pattern>
----
-
-# Web Interface Guidelines
-
-Review files for compliance with Web Interface Guidelines.
-
-## How It Works
-
-1. Fetch the latest guidelines from the source URL below
-2. Read the specified files (or prompt user for files/pattern)
-3. Check against all rules in the fetched guidelines
-4. Output findings in the terse `file:line` format
-
-## Guidelines Source
-
-Fetch fresh guidelines before each review:
-
-```
-https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
-```
-
-Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
-
-## Usage
-
-When a user provides a file or pattern argument:
-1. Fetch guidelines from the source URL above
-2. Read the specified files
-3. Apply all rules from the fetched guidelines
-4. Output findings using the format specified in the guidelines
-
-If no files specified, ask the user which files to review.
diff --git a/.claude/skills/copywriting b/.claude/skills/copywriting
deleted file mode 120000
index 214f2185c..000000000
--- a/.claude/skills/copywriting
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/copywriting
\ No newline at end of file
diff --git a/.claude/skills/find-skills b/.claude/skills/find-skills
deleted file mode 120000
index 0b17e357d..000000000
--- a/.claude/skills/find-skills
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/find-skills
\ No newline at end of file
diff --git a/.claude/skills/hono b/.claude/skills/hono
deleted file mode 120000
index fa565217e..000000000
--- a/.claude/skills/hono
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/hono
\ No newline at end of file
diff --git a/.claude/skills/seo-audit b/.claude/skills/seo-audit
deleted file mode 120000
index e89ca8bcf..000000000
--- a/.claude/skills/seo-audit
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/seo-audit
\ No newline at end of file
diff --git a/.claude/skills/skill-creator b/.claude/skills/skill-creator
deleted file mode 120000
index b87455490..000000000
--- a/.claude/skills/skill-creator
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/skill-creator
\ No newline at end of file
diff --git a/.claude/skills/vercel-composition-patterns b/.claude/skills/vercel-composition-patterns
deleted file mode 120000
index 55a19e8f4..000000000
--- a/.claude/skills/vercel-composition-patterns
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/vercel-composition-patterns
\ No newline at end of file
diff --git a/.claude/skills/vercel-react-best-practices b/.claude/skills/vercel-react-best-practices
deleted file mode 120000
index e567923b3..000000000
--- a/.claude/skills/vercel-react-best-practices
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/vercel-react-best-practices
\ No newline at end of file
diff --git a/.claude/skills/web-design-guidelines b/.claude/skills/web-design-guidelines
deleted file mode 120000
index 886b26ded..000000000
--- a/.claude/skills/web-design-guidelines
+++ /dev/null
@@ -1 +0,0 @@
-../../.agents/skills/web-design-guidelines
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 4037c271c..a6b85b79c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -80,3 +80,7 @@ plan.md
.zed
*.tsbuildinfo
+
+.claude/skills/**
+.agents/skills/**
+skills-lock.json
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 6d28e0597..a3e4b023a 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -19,6 +19,7 @@
"@openpanel/astro": "1.0.1",
"@tailwindcss/vite": "4.1.8",
"astro": "5.16.6",
+ "shiki": "3.23.0",
"sharp": "0.33.5",
"starlight-image-zoom": "0.13.2",
"starlight-links-validator": "0.19.2",
diff --git a/apps/docs/src/content/docs/concept/getting-started.mdx b/apps/docs/src/content/docs/concept/getting-started.mdx
index 4d2191f82..a4f20bea2 100644
--- a/apps/docs/src/content/docs/concept/getting-started.mdx
+++ b/apps/docs/src/content/docs/concept/getting-started.mdx
@@ -1,8 +1,8 @@
---
title: Foundational Concepts
-description: Understand the core ideas, architecture, and design decisions that shape OpenStatus.
+description: "Understand uptime monitoring, latency vs response time, SLA calculations, and the design decisions behind OpenStatus."
sidebar:
- label: Getting Started
+ label: Concepts Overview
order: 1
---
diff --git a/apps/docs/src/content/docs/getting-started/introduction.mdx b/apps/docs/src/content/docs/getting-started/introduction.mdx
deleted file mode 100644
index 0c9d2eb15..000000000
--- a/apps/docs/src/content/docs/getting-started/introduction.mdx
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Getting Started with openstatus
-description: "How to get started with openstatus?"
-topic: docs
-next: 'Start Monitoring'
----
-
-import { Aside } from '@astrojs/starlight/components';
-
-
-You can use openstatus by either signing up for our **cloud version** or by **self-hosting** the application on your own infrastructure.
-
-
-## Cloud Version
-
-The easiest way to get started is with our cloud version. You can [sign up for a free account](https://www.openstatus.dev/app/login?ref=docs)
-and begin monitoring your services in seconds.
-
-
-## Self-Hosted Version
-
-For users who want to host openstatus on their own infrastructure, all our code is [open source](https://github.com/openstatushq/openstatus).
-
-We offer a few ways to get started with self-hosting:
-
-### With Docker (Recommended)
-
-The fastest way to get started for both development and self-hosting is with Docker.
-
-```sh
-# 1. Copy environment file
-cp .env.docker.example .env.docker
-
-# 2. Start all services
-docker compose up -d
-
-# 3. Access the application
-open http://localhost:3002 # Dashboard
-open http://localhost:3003 # Status Pages
-```
-
-For a complete guide on using Docker, including database setup and configuration, please see our [DOCKER.md](https://github.com/openstatushq/openstatus/blob/main/DOCKER.md) file.
-
-### With Devbox
-
-You can use [Devbox](https://www.jetify.com/devbox/) to easily manage your development environment.
-
-1. Install Devbox
- ```sh
- curl -fsSL https://get.jetify.com/devbox | bash
- ```
-2. Install project dependencies, build and start services
- ```sh
- devbox services up
- ```
-
diff --git a/apps/docs/src/content/docs/guides/getting-started.mdx b/apps/docs/src/content/docs/guides/getting-started.mdx
index 723a4a45f..65080bbdf 100644
--- a/apps/docs/src/content/docs/guides/getting-started.mdx
+++ b/apps/docs/src/content/docs/guides/getting-started.mdx
@@ -1,8 +1,8 @@
---
title: How-to Guides
-description: Problem-solving guides for specific tasks with openstatus
+description: "Practical guides for integrating OpenStatus with GitHub Actions, OTLP endpoints, Cloudflare, and more."
sidebar:
- label: Introduction
+ label: Guides Overview
order: 1
---
diff --git a/apps/docs/src/content/docs/reference/page-components.mdx b/apps/docs/src/content/docs/reference/page-components.mdx
index 2a9628292..d9c8be1c1 100644
--- a/apps/docs/src/content/docs/reference/page-components.mdx
+++ b/apps/docs/src/content/docs/reference/page-components.mdx
@@ -300,5 +300,5 @@ Newer API versions will primarily use the `pageComponents` structure. The legacy
- **[Status Page Reference](/reference/status-page)** - Complete status page configuration reference.
- **[Status Report Reference](/reference/status-report)** - Details on creating and managing status reports.
-- **[Create Status Page](/status-page/create-status-page)** - Step-by-step tutorial on creating a status page.
+- **[Create Status Page](/tutorial/how-to-create-status-page)** - Step-by-step tutorial on creating a status page.
- **[HTTP Monitor Reference](/reference/http-monitor)** - Technical specification for HTTP monitors that can be linked to components.
diff --git a/apps/docs/src/content/docs/reference/status-page.mdx b/apps/docs/src/content/docs/reference/status-page.mdx
index 9695f9081..5ba011ef5 100644
--- a/apps/docs/src/content/docs/reference/status-page.mdx
+++ b/apps/docs/src/content/docs/reference/status-page.mdx
@@ -92,6 +92,6 @@ Removes the "powered by openstatus.dev" footer from your status page, providing
## Related resources
-- **[Create Status Page](/status-page/create-status-page)** - Step-by-step tutorial on creating a status page.
+- **[Create Status Page](/tutorial/how-to-create-status-page)** - Step-by-step tutorial on creating a status page.
- **[How to Configure Status Page](/tutorial/how-to-configure-status-page)** - Guide on advanced status page configuration.
- **[Status Report Reference](/reference/status-report)** - Details on how incident statuses are managed and reported.
diff --git a/apps/docs/src/content/docs/sdk/nodejs/getting-started.mdx b/apps/docs/src/content/docs/sdk/nodejs/getting-started.mdx
index 597ecf8cb..908c6d2e0 100644
--- a/apps/docs/src/content/docs/sdk/nodejs/getting-started.mdx
+++ b/apps/docs/src/content/docs/sdk/nodejs/getting-started.mdx
@@ -3,6 +3,18 @@ title: Getting Started
description: "Install and start using the OpenStatus Node.js SDK"
---
+import { Aside } from '@astrojs/starlight/components';
+
+## Get Your API Key
+
+Before using the SDK, you need an API key:
+
+1. Log in to the [OpenStatus dashboard](https://www.openstatus.dev/app/login)
+2. Go to **Settings** > **API Keys**
+3. Click **Create API Key** and copy it
+
+<Aside type="tip">Store your API key as an environment variable (`OPENSTATUS_API_KEY`) — never commit it to source control.</Aside>
+
## Installation
### npm
diff --git a/apps/docs/src/content/docs/sdk/nodejs/index.mdx b/apps/docs/src/content/docs/sdk/nodejs/index.mdx
index 597ecf8cb..908c6d2e0 100644
--- a/apps/docs/src/content/docs/sdk/nodejs/index.mdx
+++ b/apps/docs/src/content/docs/sdk/nodejs/index.mdx
@@ -3,6 +3,18 @@ title: Getting Started
description: "Install and start using the OpenStatus Node.js SDK"
---
+import { Aside } from '@astrojs/starlight/components';
+
+## Get Your API Key
+
+Before using the SDK, you need an API key:
+
+1. Log in to the [OpenStatus dashboard](https://www.openstatus.dev/app/login)
+2. Go to **Settings** > **API Keys**
+3. Click **Create API Key** and copy it
+
+<Aside type="tip">Store your API key as an environment variable (`OPENSTATUS_API_KEY`) — never commit it to source control.</Aside>
+
## Installation
### npm
diff --git a/apps/docs/src/content/docs/status-page/advanced/custom-domain.mdx b/apps/docs/src/content/docs/status-page/advanced/custom-domain.mdx
deleted file mode 100644
index 129fac683..000000000
--- a/apps/docs/src/content/docs/status-page/advanced/custom-domain.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: Custom Domain
-description: "How to connect a custom domain to your status page in openstatus"
----
-
-import { Aside } from '@astrojs/starlight/components';
-
-<Aside>This is a paid feature only</Aside>
-
-To connect a custom domain to your status page: _Select a status page &rarr; Domain &rarr;_.
-
-You will be asked to enter your custom domain. And we will provide you with a DNS record to add to your domain provider.
diff --git a/apps/docs/src/content/docs/status-page/advanced/description.mdx b/apps/docs/src/content/docs/status-page/advanced/description.mdx
deleted file mode 100644
index 6d1762d45..000000000
--- a/apps/docs/src/content/docs/status-page/advanced/description.mdx
+++ /dev/null
@@ -1,21 +0,0 @@
----
-title: Description
-description: "How to set a custom description for your status page in openstatus"
----
-
-import { Image } from 'astro:assets';
-
-import StatusPage from '../../../../assets/status-page/description.png';
-
-
-You can set a custom description for your status page. The description will be displayed on the status page.
-
-To add a custom description for your status page: _Select a status page &rarr; Settings &rarr; Advanced_.
-
-
-
-
- <Image
- src={StatusPage}
- alt="openstatus status page"
- />
diff --git a/apps/docs/src/content/docs/status-page/advanced/icon.mdx b/apps/docs/src/content/docs/status-page/advanced/icon.mdx
deleted file mode 100644
index b04529523..000000000
--- a/apps/docs/src/content/docs/status-page/advanced/icon.mdx
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title: Icon
-description: "How to set a custom icon for your status page in openstatus"
----
-
-import { Image } from 'astro:assets';
-
-import StatusPage from '../../../../assets/status-page/favicon.png';
-
-
-
-You can set a custom icon for your status page. The icon will be displayed in the browser tab and on the status page.
-
-To add a custom favicon for your status page: _Select a status page &rarr; Settings &rarr; Advanced_.
-
-
- <Image
- src={StatusPage}
- alt="openstatus status page"
- />
diff --git a/apps/docs/src/content/docs/status-page/advanced/monitors.mdx b/apps/docs/src/content/docs/status-page/advanced/monitors.mdx
deleted file mode 100644
index 77302acdd..000000000
--- a/apps/docs/src/content/docs/status-page/advanced/monitors.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: Monitors
-description: "How to connect your monitors for your status page in openstatus"
----
-
-Connect your created monitors to your status page to display the current status of your services.
-
-To change monitors for a status page: _Select a status page &rarr; Settings &rarr; Monitors_.
-
-### Values visibility
-
-By default, we share the number of total requests and the number of failed request with the total uptime of the last 45 days. If you want to hide the values, you can do so by toggeling the setting.
-
-{/* TODO: update after OPE-427 */}
-To change the visibility of the values: _Select a status page &rarr; Settings &rarr; Advanced_.
-
-
-### Public monitors
-
-If you want to share all your monitor metrics with your users, you can make your monitor public. This will allow you to display the metrics on your status page.
-
-To make a monitor public: _Select a monitor &rarr; Settings &rarr; Danger &rarr; Toggle Public monitor.
-
-You can see an example of a public monitor at [https://status.openstatus.dev/monitors/1](https://status.openstatus.dev/monitors/1).
diff --git a/apps/docs/src/content/docs/status-page/advanced/password.mdx b/apps/docs/src/content/docs/status-page/advanced/password.mdx
deleted file mode 100644
index a15190a24..000000000
--- a/apps/docs/src/content/docs/status-page/advanced/password.mdx
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: Password protection
-description: "How to password protect your status page in openstatus"
----
-
-import { Aside } from '@astrojs/starlight/components';
-
-<Aside>This is a paid feature only</Aside>
-
-You can password protect your status page to restrict access to it.
-
-To change toggle the protection or change password of your status page: _Select a status page &rarr; Settings &rarr; Visibility_.
-
-The password is stored stored unencrypted in our database and can be shared via `password` search param in the URL, e.g. `https://statuspage.openstatus.dev?password=top-secret`. We recommend using a unique password for your status page.
diff --git a/apps/docs/src/content/docs/status-page/create-status-page.mdx b/apps/docs/src/content/docs/status-page/create-status-page.mdx
deleted file mode 100644
index f391f5758..000000000
--- a/apps/docs/src/content/docs/status-page/create-status-page.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: About this project
-description: Learn more about the project I’m working on.
----
diff --git a/apps/docs/src/content/docs/status-page/overview.mdx b/apps/docs/src/content/docs/status-page/overview.mdx
deleted file mode 100644
index d2334b399..000000000
--- a/apps/docs/src/content/docs/status-page/overview.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: Status page
-description: "Discover what is a status page in openstatus"
----
-import { Image } from 'astro:assets';
-
-import StatusPage from '../../../assets/status-page/status-page.png';
-
- <Image
- src={StatusPage}
- alt="openstatus status page"
- />
-
-
-
-## What is a status page 🧑‍🏫
-
-A status page is a public page that displays the status and performance of your
-services. It shows the current status of your services and the history of
-incidents.
-
-You can create a status page with openstatus and display the status of your synthetic checks.
-
-You can see our own status page at [https://status.openstatus.dev](https://status.openstatus.dev).
diff --git a/apps/docs/src/content/docs/status-page/work/color-status-bar.mdx b/apps/docs/src/content/docs/status-page/work/color-status-bar.mdx
deleted file mode 100644
index 83954f4b5..000000000
--- a/apps/docs/src/content/docs/status-page/work/color-status-bar.mdx
+++ /dev/null
@@ -1,11 +0,0 @@
----
-title: Understand the color of the status bar
----
-
-On your status page, each status bar can have a different color based on the status of the service.
-
-- **Green**: The service is up and running.
-- **Orange**: The service is slow or degraded.
-- **Red**: The service is down or unreachable.
-- **Gray**: The service is paused or disabled or there is no data.
-- **Blue**: The service is in maintenance or scheduled downtime.
\ No newline at end of file
diff --git a/apps/docs/src/content/docs/status-page/work/maintenances.mdx b/apps/docs/src/content/docs/status-page/work/maintenances.mdx
deleted file mode 100644
index 613a0bd50..000000000
--- a/apps/docs/src/content/docs/status-page/work/maintenances.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
----
-title: Maintenance
----
-
-You can predefine maintenance periods for your services and inform your users about upcoming and/or current maintenance.
-
-During the maintenance period, the status of your service will be set to `Maintenance`. We will not ping your selected monitors during this time.
-
-To set up maintenance periods for your services: _Select a status page &rarr; Maintenance_.
\ No newline at end of file
diff --git a/apps/docs/src/content/docs/status-page/work/reports.mdx b/apps/docs/src/content/docs/status-page/work/reports.mdx
deleted file mode 100644
index 7a9a136fe..000000000
--- a/apps/docs/src/content/docs/status-page/work/reports.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
----
-title: Status Page Report
-description: "What is a Status Page Report 🔥"
----
-## What is a Status Page Report?
-
-A status page report is a timeline of status updates that can be shared with your users. It is a great way to keep your users informed about the status of your application, website or service.
-
-Only the update that happened during the last 7 days will be displayed on the main page of your status page.
-Otherwise they will be displayed on your status page and under the **Event** tab.
-
-## How to create a Status Page Report?
-
-Go to your **status page** tab, select your status page click on the **Status report**.
-
-When creating a status report, you can map it to a **monitor** or not. This will allow you access the latest reports on your status
-page.
-
-If you don't select a monitor, this is useful if you want to inform your users about an incident, a maintenance of a third party provider.
-
-Update your report over time and keep your users informed. Add a new **status**,
-**date** and **message** to your report. They will be displayed on a timeline.
-
-
-### Status update
-
-The status update can be one of the following:
-
-- **Investigating**: You are investigating an issue
-- **Identified**: You have identified the issue
-- **Monitoring**: You are monitoring the issue
-- **Resolved**: The issue has been resolved
-
-
diff --git a/apps/docs/src/content/docs/status-page/work/subscribers.mdx b/apps/docs/src/content/docs/status-page/work/subscribers.mdx
deleted file mode 100644
index ae8646d01..000000000
--- a/apps/docs/src/content/docs/status-page/work/subscribers.mdx
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title: Status Page Subscribers
----
-
-import { Aside } from '@astrojs/starlight/components';
-
-
-<Aside>This is a paid feature only</Aside>
-
-## What does it mean to subscribe to a status page?
-
-Your subscribers will receive an email notification when you update your status page. Each time you create a new status report or update an existing one, your subscribers will receive an email.
-
-As a status page owner you will be able to see the list of subscribers.
-
-## How to subscribe to a status page?
-
-To subscribe to a status page, you need to click on the `Subscribe` button on the status page.
-
-You will be asked to enter your email address. You will receive a confirmation email to validate your subscription.
\ No newline at end of file
diff --git a/apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx b/apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx
index 929ee2373..802acf08d 100644
--- a/apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx
+++ b/apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx
@@ -4,10 +4,17 @@ description: "Step-by-step tutorial to install and use the openstatus CLI for mo
---
import { Image } from 'astro:assets';
+import { Aside } from '@astrojs/starlight/components';
import CLI from '../../../assets/tutorial/get-started-with-openstatus-cli/CLI.png';
## What you'll learn
+| | |
+|---|---|
+| **Time** | ~10 minutes |
+| **Level** | Intermediate |
+| **Prerequisites** | openstatus account, command line experience |
+
In this tutorial, you'll learn how to use the openstatus CLI to manage your monitors as code. This enables you to version control your monitoring configuration, automate deployments, and implement GitOps workflows.
### Prerequisites
@@ -53,19 +60,39 @@ curl -fsSL https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/in
### Windows
-```bash
+```powershell
iwr https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.ps1 | iex
```
+### Verify installation
+
+Run the following command to confirm the CLI is installed:
+
+```bash
+openstatus --version
+```
+
+You should see output like:
+
+```
+openstatus version x.x.x
+```
+
## Configure API authentication
Create an API key in your workspace settings (Settings → API), then set it as an environment variable:
```bash
+# macOS / Linux
export OPENSTATUS_API_TOKEN=<your-api-token>
```
-**Tip**: Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist across sessions.
+```powershell
+# Windows PowerShell
+$env:OPENSTATUS_API_TOKEN="<your-api-token>"
+```
+
+<Aside>Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist across sessions.</Aside>
## Import existing monitors
@@ -75,8 +102,16 @@ Start by importing your existing monitors from your workspace to a YAML file:
openstatus monitors import
```
+You should see output confirming the import:
+
+```
+Successfully imported X monitors to openstatus.yaml
+```
+
This creates an `openstatus.yaml` file containing all your current monitors. This file becomes your single source of truth for monitoring configuration.
+**Checkpoint:** Open the `openstatus.yaml` file and verify it contains your monitors. You should see entries with your monitor names and URLs.
+
## Manage monitors as code
Now you can add, remove, or update monitors in the YAML file and apply your changes:
@@ -95,6 +130,37 @@ Excellent work! You've successfully:
- ✅ Imported monitors to a YAML file
- ✅ Learned the monitoring as code workflow
+## Troubleshooting
+
+### "command not found: openstatus"
+
+**Cause:** The CLI binary is not in your PATH.
+
+**Fix (macOS/Homebrew):**
+```bash
+brew reinstall openstatusHQ/cli/openstatus --cask
+```
+
+**Fix (install script):** Ensure `~/.local/bin` is in your PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### "unauthorized" or "invalid token" error
+
+**Cause:** Your API token is missing or incorrect.
+
+**Fix:**
+1. Verify the token is set: `echo $OPENSTATUS_API_TOKEN`
+2. Regenerate the token in your workspace settings (Settings → API)
+3. Make sure there are no extra spaces or newlines in the token value
+
+### "no monitors found" on import
+
+**Cause:** Your workspace has no monitors, or the token belongs to a different workspace.
+
+**Fix:** Create at least one monitor in the dashboard first, then retry the import.
+
## What's next?
Now that you have the CLI set up, you can:
diff --git a/apps/docs/src/content/docs/tutorial/getting-started.mdx b/apps/docs/src/content/docs/tutorial/getting-started.mdx
index 7dc18aeb7..7e3e93c6f 100644
--- a/apps/docs/src/content/docs/tutorial/getting-started.mdx
+++ b/apps/docs/src/content/docs/tutorial/getting-started.mdx
@@ -1,12 +1,12 @@
---
-title: Getting Started with Tutorials
-description: Step-by-step lessons to learn openstatus from the ground up
+title: Tutorials Overview
+description: "Step-by-step tutorials to create monitors, status pages, and private locations with OpenStatus."
sidebar:
- label: Getting Started
+ label: Tutorials Overview
order: 1
---
-## 📚 Tutorials
+## Tutorials
### What you'll learn
@@ -20,20 +20,21 @@ Our tutorials are designed to help you:
Start your journey with openstatus:
-- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Learn the fundamentals by setting up uptime monitoring for your first endpoint
-- **[Create a Status Page](/tutorial/how-to-create-status-page)** - Build a public status page to communicate service health to your users
-- **[Configure Your Status Page](/tutorial/how-to-configure-status-page)** - Customize your status page with monitors, domains, and protection
+- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** (~5 min) - Learn the fundamentals by setting up uptime monitoring for your first endpoint
+- **[Create a Status Page](/tutorial/how-to-create-status-page)** (~5 min) - Build a public status page to communicate service health to your users
+- **[Configure Your Status Page](/tutorial/how-to-configure-status-page)** (~10 min) - Customize your status page with monitors, domains, and protection
+- **[Set Up the Slack Agent](/tutorial/how-to-setup-slack-agent)** (~5 min) - Manage incidents directly from Slack
### Advanced Tutorials
Once you're comfortable with the basics:
-- **[Create a Private Location (Beta)](/tutorial/how-to-create-private-location)** - Set up monitoring from your own infrastructure
-- **[Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)** - Automate monitor management with our command-line tool
+- **[Create a Private Location (Beta)](/tutorial/how-to-create-private-location)** (~15 min) - Set up monitoring from your own infrastructure
+- **[Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)** (~10 min) - Automate monitor management with our command-line tool
### What's next?
After completing these tutorials, you'll be ready to:
-- Explore [how-to guides](/guides/getting-started/) for specific tasks and advanced scenarios
-- Dive into [explanations](/concept/getting-started/) to understand the concepts behind the features
-- Reference our [technical documentation](/reference) for detailed specifications
+- Explore [how-to guides](/guides/getting-started) for specific tasks and advanced scenarios
+- Dive into [explanations](/concept/getting-started) to understand the concepts behind the features
+- Reference our [technical documentation](/reference/cli-reference) for detailed specifications
diff --git a/apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx b/apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx
index a33fea28d..ce6715774 100644
--- a/apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx
+++ b/apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx
@@ -32,19 +32,19 @@ By the end of this tutorial, you'll have:
- Links to important resources
- Preview and live configuration experience
-## Status Page Redesign (Beta)
+## Status Page Customization
-We are releasing a new version of our status pages with enhanced customization options.
+OpenStatus offers enhanced status page customization with multiple themes and display options.
Explore available themes: [https://themes.openstatus.dev](https://themes.openstatus.dev)
## Get started
-Go to the **Status Page Redesign (beta)** section in your status page settings. Toggle the `Enable New Version` to support it. Once enabled, you'll see two subsections:
+Go to the **Status Page Redesign** section in your status page settings and toggle `Enable New Version`. Once enabled, you'll see three subsections:
1. **Tracker Configuration**
2. **Theme Explorer**
-2. **Links**
+3. **Links**
<Image
src={ConfigureStatusPage1}
@@ -73,7 +73,7 @@ We have three new status tracker configurations to provide you with a maximum ch
**Card Type**: The card type is only configurable if the bar type is **absolute**. You'll then be able to choose between **duration**, which will show the duration of "success", "error", "degraded" or "maintenance" reports or **requests** where we will share the number of request status itself. If **manual** bar type is chosen, we will only show the most significant status of the day.
-**Show Uptime**: The uptime is calculated by ither the **duration** of the different reports _or_ the **request** values depending on what you've chosen for the **absolute** value (incl. incidents). If you've chosen **manual**, it only gets calculated by the duration of your status reports.
+**Show Uptime**: The uptime is calculated by either the **duration** of the different reports _or_ the **request** values depending on what you've chosen for the **absolute** value (incl. incidents). If you've chosen **manual**, it only gets calculated by the duration of your status reports.
A few examples to understand it:
@@ -110,7 +110,7 @@ Visit [themes.openstatus.dev](https://themes.openstatus.dev) to see the list of
### 3. Links
-Let's have a closer look to your status page header navigation:
+Let's have a closer look at your status page header navigation:
<Image
src={StatusPageBeta1}
@@ -123,12 +123,12 @@ Let's have a closer look to your status page header navigation:
---
-We are adding some additional features. Feel free to let us know what's missing!
+We are continuously adding new features. Feel free to let us know what's missing!
## What you've accomplished
Excellent work! You've successfully:
-- ✅ Enabled and configured the new status page design (beta)
+- ✅ Enabled and configured the new status page design
- ✅ Customized status tracker display options
- ✅ Explored and applied theme settings
- ✅ Added navigation links to your status page
diff --git a/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx b/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx
index a58166380..8bb1182ec 100644
--- a/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx
+++ b/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx
@@ -1,6 +1,6 @@
---
-title: Create Your First Monitor
-description: "A step-by-step tutorial to create your first monitor with openstatus"
+title: Create an Uptime Monitor in 5 Minutes
+description: "Set up your first uptime monitor with OpenStatus — track response time, status codes, and availability from 35+ global locations."
---
import { Image } from 'astro:assets';
@@ -36,7 +36,7 @@ Let's get your first uptime check up and running.
<Image
src={createMonitor}
- alt="Charts with status code and response time"
+ alt="Monitors page showing the Create Monitor button in the sidebar"
/>
Navigate to the **Monitors** page from the sidebar and click the **Create Monitor** button. This will open a new configuration screen.
@@ -46,7 +46,7 @@ Navigate to the **Monitors** page from the sidebar and click the **Create Monito
<Image
src={createMonitor2}
- alt="Charts with status code and response time"
+ alt="Monitor creation form with name and URL fields"
/>
To get your monitor started, you only need to provide two essential pieces of information:
@@ -62,9 +62,11 @@ As soon as you enter the URL, our monitoring tool will automatically begin track
<Image
src={monitorOverview}
- alt="Charts with status code and response time"
+ alt="Monitor overview dashboard showing response time and status code charts"
/>
+**Checkpoint:** After saving, you should see your monitor's overview page with response time and status code charts. If data appears within a few seconds, your monitor is running.
+
### 3. Customizing the HTTP Request
@@ -72,7 +74,7 @@ Your monitor doesn't just have to be a simple `GET` request. You can customize t
#### HTTP Method
-Choose the appropriate HTTP method for your check. While `GET` is the default and most common for simple health checks, you can also select `POST`, `HEAD`, `OPTIONS`, `PUT`, `PATCH`, `DELETE`, `TRACE`. `OPTIONS`
+Choose the appropriate HTTP method for your check. While `GET` is the default and most common for simple health checks, you can also select `POST`, `HEAD`, `OPTIONS`, `PUT`, `PATCH`, `DELETE`, or `TRACE`.
- `GET`: Retrieve data from an endpoint. The most common choice for health checks.
- `POST`: Send data to an endpoint, for example, to test a form submission or API creation endpoint.
@@ -91,15 +93,15 @@ If you select the `POST` method, you can add a Request Body to your monitor's co
You can add any number of custom HTTP headers to your request. This is particularly useful for:
-- **Authentication:**: Sending an Authorization token (e.g., a Bearer token) to test a protected endpoint.
-- **Content Type:**: Setting an `content-type` header to specify a content type (e.g., `application/json`).
+- **Authentication:** Sending an Authorization token (e.g., a Bearer token) to test a protected endpoint.
+- **Content Type:** Setting a `content-type` header to specify a content type (e.g., `application/json`).
- **Content Negotiation:** Setting an Accept header to request a specific content type from the server (e.g., `application/json`).
- **Simulating Clients:** Adding a User-Agent header to simulate traffic from a specific browser or device.
- Heads Up: We've got your User-Agent covered!
- openstatus automatically includes the `"User-Agent": "openstatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.
-
+<Aside title="We've got your User-Agent covered!">
+openstatus automatically includes the `"User-Agent": "openstatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.
+</Aside>
## Important Considerations
diff --git a/apps/docs/src/content/docs/tutorial/how-to-create-private-location.mdx b/apps/docs/src/content/docs/tutorial/how-to-create-private-location.mdx
index 769a355cc..3d7d425e9 100644
--- a/apps/docs/src/content/docs/tutorial/how-to-create-private-location.mdx
+++ b/apps/docs/src/content/docs/tutorial/how-to-create-private-location.mdx
@@ -1,26 +1,136 @@
---
-title: How to create a private location (beta)
+title: Create a Private Location
+description: "Set up monitoring from your own infrastructure using Docker-based private probes"
---
-### What are private locations?
+import { Aside } from '@astrojs/starlight/components';
-**Private locations** allow you to monitor internal applications and network resources from within your own infrastructure, rather than solely relying on public cloud-based servers.
+## What you'll learn
-By deploying our **monitoring probes** (as containers) on your own machines inside your firewall, you can run tests against private endpoints like internal APIs or servers and get detailed *timing phases and latency information* from your specific deployment location. This enables you to monitor not just *datacenter to datacenter* (when your web services are deployed on platforms like Cloudflare, AWS, or GCP), but also from **private locations** like on-prem servers or even Raspberry Pi devices.
+| | |
+|---|---|
+| **Time** | ~15 minutes |
+| **Level** | Advanced |
+| **Prerequisites** | OpenStatus account, Docker installed |
-Private locations are crucial for verifying *performance and availability* of internal systems, integrating with your development pipelines, and ensuring **security** without exposing sensitive services to the open internet.
+In this tutorial, you'll set up a **private location** — a monitoring probe running on your own infrastructure. This lets you monitor internal applications, private APIs, and network resources behind your firewall without exposing them to the public internet.
+### Prerequisites
-### How to use private locations?
+- An OpenStatus account ([openstatus.dev](https://www.openstatus.dev))
+- Docker installed on your server or local machine (`docker --version` to verify)
+- At least one monitor already created (see [Create Your First Monitor](/tutorial/how-to-create-monitor))
-1. create a private location and access a generated `token`
-2. install the docker image on your server
-3. in the private location settings, choose which monitors to track (or vice versa, configure it in your monitor settings)
-4. done (within a couple of minutes, we'll check the everything)
+### What you'll build
-We have published a blog post on how we [deployed the docker image on a Raspberry Pi (2016)](https://www.openstatus.dev/blog/deploy-private-locations-raspberry-pi).
+By the end of this tutorial, you'll have:
+- A private location configured in OpenStatus
+- A Docker container running the monitoring probe on your infrastructure
+- Monitors assigned to check from your private location
-### What is missing?
+<Aside type="caution">Private locations are currently in **beta**. Some features like incident creation and public status page support are not yet available for private locations.</Aside>
-- Incidents will not be created (yet) if you run your monitors via privat regions. That means you should still use the openstatus regions to get alerts if a monitor is down.
-- Public monitors on status pages do not support private regions (yet).
\ No newline at end of file
+## What are private locations?
+
+Private locations allow you to monitor internal applications from within your own infrastructure, rather than solely relying on our public cloud-based regions. By deploying monitoring probes as Docker containers on your own machines, you can:
+
+- Monitor internal APIs and services behind your firewall
+- Get detailed timing and latency data from your specific deployment location
+- Monitor from on-prem servers, Raspberry Pi devices, or any Docker-capable machine
+
+## Step 1: Create a private location
+
+1. Navigate to **Settings** > **Private Locations** in your OpenStatus dashboard
+2. Click **Create Private Location**
+3. Give your location a descriptive name (e.g., "Office Network", "AWS us-east-1 VPC")
+4. Save the configuration
+
+After creation, you'll receive a **token**. Copy this token — you'll need it in the next step.
+
+<Aside type="caution">Keep your token secure. It authenticates your probe with the OpenStatus platform.</Aside>
+
+## Step 2: Deploy the Docker probe
+
+Run the monitoring probe on your server using Docker:
+
+```bash
+docker run -d \
+ --name openstatus-probe \
+ --restart unless-stopped \
+ -e OPENSTATUS_TOKEN=<your-token> \
+ ghcr.io/openstatushq/probe:latest
+```
+
+Replace `<your-token>` with the token from Step 1.
+
+### Verify the container is running
+
+```bash
+docker ps --filter name=openstatus-probe
+```
+
+You should see the container listed with a status of `Up`:
+
+```
+CONTAINER ID IMAGE STATUS NAMES
+abc123 ghcr.io/openstatushq/probe:latest Up 2 minutes openstatus-probe
+```
+
+## Step 3: Assign monitors to your private location
+
+1. Go to **Settings** > **Private Locations** and select your location
+2. Choose which monitors should run from this private location
+3. Alternatively, edit an individual monitor and select your private location in its settings
+
+**Checkpoint:** Within a couple of minutes, you should see monitoring data appearing in your monitor's overview from your private location.
+
+## What you've accomplished
+
+You've successfully:
+- ✅ Created a private location in OpenStatus
+- ✅ Deployed a monitoring probe on your own infrastructure
+- ✅ Assigned monitors to check from your private location
+
+## Current limitations
+
+- Incidents are **not yet created** for monitors running via private locations. Continue using OpenStatus public regions if you need alerting.
+- Public monitors on status pages **do not yet support** private locations.
+
+## Troubleshooting
+
+### Container exits immediately
+
+Check the container logs for errors:
+
+```bash
+docker logs openstatus-probe
+```
+
+Common causes:
+- **Invalid token:** Double-check the token value — ensure no extra spaces or newlines
+- **Network issues:** Ensure the container can reach `api.openstatus.dev` on port 443
+
+### No data appearing in the dashboard
+
+1. Verify the container is running: `docker ps --filter name=openstatus-probe`
+2. Check that you've assigned at least one monitor to the private location
+3. Wait 2-3 minutes — there may be a short delay before the first check runs
+
+### Container can't reach internal services
+
+If the probe needs to reach services on your host machine, use Docker's host networking:
+
+```bash
+docker run -d \
+ --name openstatus-probe \
+ --restart unless-stopped \
+ --network host \
+ -e OPENSTATUS_TOKEN=<your-token> \
+ ghcr.io/openstatushq/probe:latest
+```
+
+## What's next?
+
+- **[Read our Raspberry Pi deployment guide](https://www.openstatus.dev/blog/deploy-private-locations-raspberry-pi)** — Deploy probes on low-cost hardware
+- **[Create a Monitor](/tutorial/how-to-create-monitor)** — Set up more monitors to run from your private location
+- **[Configure Notifications](/monitoring/customization/notification)** — Get alerted when services go down (via public regions)
diff --git a/apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx b/apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx
index 20a883228..fd3502747 100644
--- a/apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx
+++ b/apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx
@@ -4,6 +4,7 @@ description: "A step-by-step tutorial to create and publish your first status pa
---
import { Image } from 'astro:assets';
+import { Aside } from '@astrojs/starlight/components';
import CreateStatusPage1 from '../../../assets/tutorial/create-status-page/create-status-page-1.png';
@@ -11,6 +12,12 @@ import CreateStatusPage2 from '../../../assets/tutorial/create-status-page/creat
## What you'll learn
+| | |
+|---|---|
+| **Time** | ~5 minutes |
+| **Level** | Beginner |
+| **Prerequisites** | OpenStatus account, at least one monitor |
+
In this tutorial, you'll create a public status page to communicate your service's health to users. A status page is a transparent way to show real-time uptime information and keep your users informed during incidents.
### Prerequisites
@@ -25,8 +32,6 @@ By the end of this tutorial, you'll have:
- Monitors displayed on your status page
- Understanding of privacy and security options
-This tutorial will guide you through the process of creating a status page in openstatus. A status page is a web page that displays the status of your services, building trust with your users through transparency.
-
## Get started
### 1. Create the status page
@@ -35,33 +40,41 @@ Navigate to the **Status Pages** page from the sidebar and click the **Create St
<Image
src={CreateStatusPage1}
- alt="Create your status page"
+ alt="Status Pages sidebar with the Create Status Page button highlighted"
/>
### 2. Configure the status page
-After creating the status page, you can configure it
-
+Fill in the basic details for your status page:
+- **Title:** A name for your status page (e.g., "Acme Status" or "API Health")
+- **Slug:** The URL path for your status page (e.g., `acme` creates `acme.openstatus.dev`)
<Image
src={CreateStatusPage2}
- alt="Configure your status page"
+ alt="Status page configuration form showing title, slug, and monitor selection"
/>
-#### Monitors
+#### Add monitors
-You need to add monitors to your status page. Monitors are used to check the status of your services.
+Select the monitors you want to display on your status page. Each monitor will show as a separate service with its own uptime bar. You can add multiple monitors to give users a complete picture of your infrastructure health.
#### Custom domain
-You can add a Custom Domain to your status page. Custom domains allow you to use your own domain name instead of the default domain name provided by openstatus.
+You can use your own domain (e.g., `status.yourdomain.com`) instead of the default `*.openstatus.dev` subdomain. To set this up:
+
+1. Enter your custom domain in the **Custom Domain** field
+2. Add a CNAME record pointing to `status.openstatus.dev` in your DNS provider
+3. Wait for DNS propagation (usually a few minutes, up to 48 hours)
+
+See the [Status Page Reference](/reference/status-page) for detailed DNS configuration instructions.
+#### Password protection
-#### Password Protection
+Enable password protection to restrict access to your status page. This is useful for internal status pages that should only be visible to your team or specific customers. Enter a password, and visitors will be prompted to authenticate before viewing the page.
-You can add password protection to your status page. Password protection allows you to restrict access to your status page to only authorized users.
+**Checkpoint:** After saving, click the link to your status page (shown at the top of the settings). You should see your monitors listed with uptime bars.
## What you've accomplished
diff --git a/apps/docs/src/content/docs/tutorial/how-to-setup-slack-agent.mdx b/apps/docs/src/content/docs/tutorial/how-to-setup-slack-agent.mdx
index bb9f9119e..1f5ec7df4 100644
--- a/apps/docs/src/content/docs/tutorial/how-to-setup-slack-agent.mdx
+++ b/apps/docs/src/content/docs/tutorial/how-to-setup-slack-agent.mdx
@@ -7,6 +7,12 @@ import { Aside } from '@astrojs/starlight/components';
## What you'll learn
+| | |
+|---|---|
+| **Time** | ~5 minutes |
+| **Level** | Beginner |
+| **Prerequisites** | OpenStatus account, Slack workspace admin access |
+
In this tutorial, you'll learn how to install the OpenStatus Slack agent so you can manage incidents directly from your Slack workspace — no need to switch to the dashboard.
### Prerequisites
@@ -34,11 +40,21 @@ Grant the requested permissions and click **Allow** to complete the installation
<Aside>Make sure you select the correct Slack workspace if you belong to multiple workspaces.</Aside>
-### 3. Start Managing Incidents from Slack
+### 3. Verify the Installation
+
+After completing the OAuth flow, go to the Slack channel you selected and type:
+
+```
+@openstatus what's the status of my monitors?
+```
+
+The bot should respond with a summary of your monitors. If you see a response, the installation is working.
+
+<Aside type="tip">The bot only responds when mentioned with `@openstatus` — it won't interrupt your conversations.</Aside>
-Once installed, mention **@openstatus** in any channel to interact with the agent. This keeps threads clean — the bot only responds when mentioned.
+### 4. Start Managing Incidents from Slack
-Here are some examples:
+Here are some examples of what you can do:
#### Create an incident
@@ -75,9 +91,25 @@ Plan downtime so subscribers are informed in advance.
## What you've accomplished
Congratulations! You've successfully:
-- Installed the OpenStatus Slack agent in your workspace
-- Connected your OpenStatus account to Slack
-- Learned how to manage incidents directly from Slack
+- ✅ Installed the OpenStatus Slack agent in your workspace
+- ✅ Connected your OpenStatus account to Slack
+- ✅ Learned how to manage incidents directly from Slack
+
+## Troubleshooting
+
+### The bot doesn't respond when mentioned
+
+1. **Check the channel:** Make sure you're mentioning `@openstatus` in the channel you selected during installation.
+2. **Check permissions:** Go to **Settings** > **Integrations** and verify the Slack integration shows as connected.
+3. **Reinstall:** If the integration appears disconnected, click **Install Slack** again to re-authorize.
+
+### "Not authorized" or permission errors
+
+Your Slack workspace admin may need to approve the app. Ask your workspace admin to go to **Slack Admin** > **Manage Apps** and approve the OpenStatus integration.
+
+### Bot responds but can't find monitors
+
+Make sure you have at least one monitor and one status page created in your OpenStatus workspace before using incident commands.
## What's next?
diff --git a/apps/web/package.json b/apps/web/package.json
index ef269f44f..3af4d4032 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -87,7 +87,7 @@
"resend": "6.6.0",
"sanitize-html": "2.17.0",
"schema-dts": "1.1.5",
- "shiki": "0.14.4",
+ "shiki": "3.23.0",
"slugify": "1.6.6",
"sonner": "2.0.5",
"stripe": "13.8.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0cae14fe8..d0d900d9c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -381,6 +381,9 @@ importers:
sharp:
specifier: 0.33.5
version: 0.33.5
+ shiki:
+ specifier: 3.23.0
+ version: 3.23.0
starlight-image-zoom:
specifier: 0.13.2
@@ -1097,8 +1100,8 @@ importers:
specifier: 1.1.5
version: 1.1.5
shiki:
- specifier: 0.14.4
- version: 0.14.4
+ specifier: 3.23.0
+ version: 3.23.0
slugify:
specifier: 1.6.6
version: 1.6.6
@@ -1243,7 +1246,7 @@ importers:
version: 2.6.2
drizzle-orm:
specifier: 0.44.4
- version: 0.44.4(@libsql/[email protected])(@opentelemetry/[email protected])(@types/[email protected])([email protected])
+ version: 0.44.4(@libsql/[email protected])(@opentelemetry/[email protected])(@types/[email protected])([email protected])
effect:
specifier: 3.19.12
version: 3.19.12
@@ -1262,7 +1265,7 @@ importers:
version: link:../../packages/tsconfig
'@types/bun':
specifier: latest
- version: 1.3.9
+ version: 1.3.10
typescript:
specifier: 5.9.3
version: 5.9.3
@@ -1427,10 +1430,10 @@ importers:
version: 3.0.3
drizzle-orm:
specifier: 0.44.4
- version: 0.44.4(@libsql/[email protected])(@opentelemetry/[email protected])(@types/[email protected])([email protected])
+ version: 0.44.4(@libsql/[email protected])(@opentelemetry/[email protected])(@types/[email protected])([email protected])
drizzle-zod:
specifier: 0.8.3
zod:
specifier: 4.1.13
version: 4.1.13
@@ -2021,7 +2024,7 @@ importers:
devDependencies:
'@types/bun':
specifier: latest
- version: 1.3.9
+ version: 1.3.10
packages/subscriptions:
dependencies:
@@ -2040,7 +2043,7 @@ importers:
version: link:../tsconfig
'@types/bun':
specifier: latest
- version: 1.3.9
+ version: 1.3.10
typescript:
specifier: 5.9.3
version: 5.9.3
@@ -6502,23 +6505,23 @@ packages:
peerDependencies:
webpack: '>=4.40.0'
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-f2ED7HYV4JEk827mtMDwe/yQ25pRiXZmtHjWF8uzZKuKiEsJR7Ce1nuQ+HhV9FzDcbIo4ObBCD9GPTzNuy9S1g==}
+ '@shikijs/[email protected]':
+ resolution: {integrity: sha512-NSWQz0riNb67xthdm5br6lAkvpDJRTgB36fxlo37ZzM2yq0PQFFzbd8psqC2XMPgCzo1fW6cVi18+ArJ44wqgA==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-OFx8fHAZuk7I42Z9YAdZ95To6jDePQ9Rnfbw9uSRTSbBhYBp1kEOKv/3jOimcj3VRUKusDYM6DswLauwfhboLg==}
+ '@shikijs/[email protected]':
+ resolution: {integrity: sha512-aHt9eiGFobmWR5uqJUViySI1bHMqrAgamWE1TYSUoftkAeCCAiGawPMwM+VCadylQtF4V3VNOZ5LmfItH5f3yA==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-Yx3gy7xLzM0ZOjqoxciHjA7dAt5tyzJE3L4uQoM83agahy+PlW244XJSrmJRSBvGYELDhYXPacD4R/cauV5bzQ==}
+ '@shikijs/[email protected]':
+ resolution: {integrity: sha512-1nWINwKXxKKLqPibT5f4pAFLej9oZzQTsby8942OTlsJzOBZ0MWKiwzMsd+jhzu8YPCHAswGnnN1YtQfirL35g==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-le+bssCxcSHrygCWuOrYJHvjus6zhQ2K7q/0mgjiffRbkhM4o1EWu2m+29l0yEsHDbWaWPNnDUTRVVBvBBeKaA==}
+ '@shikijs/[email protected]':
+ resolution: {integrity: sha512-2Ep4W3Re5aB1/62RSYQInK9mM3HsLeB91cHqznAJMuylqjzNVAVCMnNWRHFtcNHXsoNRayP9z1qj4Sq3nMqYXg==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-U1NSU7Sl26Q7ErRvJUouArxfM2euWqq1xaSrbqMu2iqa+tSp0D1Yah8216sDYbdDHw4C8b75UpE65eWorm2erQ==}
+ '@shikijs/[email protected]':
+ resolution: {integrity: sha512-5qySYa1ZgAT18HR/ypENL9cUSGOeI2x+4IvYJu4JgVJdizn6kG4ia5Q1jDEOi7gTbN4RbuYtmHh0W3eccOrjMA==}
- '@shikijs/[email protected]':
- resolution: {integrity: sha512-lhYAATn10nkZcBQ0BlzSbJA3wcmL5MXUUF8d2Zzon6saZDlToKaiRX60n2+ZaHJCmXEcZRWNzn+k9vplr8Jhsw==}
+ '@shikijs/[email protected]':
+ resolution: {integrity: sha512-3JZ5HXOZfYjsYSk0yPwBrkupyYSLpAE26Qc0HLghhZNGTZg/SKxXIIgoxOpmmeQP0RRSDJTk1/vPfw9tbw+jSQ==}
'@shikijs/[email protected]':
resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
@@ -7109,8 +7112,8 @@ packages:
resolution: {integrity: sha512-SQFof9H+LXeWNz8wDe7oN5zu7ket0qwMu5vZubW4GCJ8Kkeh6nBWUz87+KTz/G3Kqsrp0j/W253XJb3KMEeg3w==}
- '@types/[email protected]':
- resolution: {integrity: sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ==}
resolution: {integrity: sha512-hWtVTC2q7hc7xZ/RLbxapMvDMgUnDvKvMOpKal4DrMyfGBUfB1oKaZlIRr6mJL+If3bAP6sV/QneGzF6tJjZDg==}
@@ -7524,9 +7527,6 @@ packages:
resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
engines: {node: '>=12'}
- resolution: {integrity: sha512-+fksAx9eG3Ab6LDnLs3ZqZa8KVJ/jYnX+D4Qe1azX+LFGFAXqynCQLOdLpNYN/l9e7l6hMWwZbrnctqr6eSQSw==}
-
resolution: {integrity: sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==}
engines: {node: '>=4'}
@@ -7646,6 +7646,7 @@ packages:
resolution: {integrity: sha512-4Bcg1P8xhUuqcii/S0Z9wiHIrQVPMermM1any+MX5GeGD7faD3/msQUDGLol9wOcz4/jbg/WJnGqoJF6LiBdtg==}
engines: {node: '>=10.0.0'}
+ deprecated: Security vulnerability fixed in 5.2.0, please upgrade
resolution: {integrity: sha512-JtTezzbAibu8G0R9op9zb3vcWZd9JF6M0xOYGPn0fNCd7wOpRB1mU2mH9T8gaBGbAAyIIVgB2G7xG0GP98zMAQ==}
@@ -7716,8 +7717,8 @@ packages:
peerDependencies:
'@types/react': ^19
- resolution: {integrity: sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg==}
+ resolution: {integrity: sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg==}
resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
@@ -8881,6 +8882,7 @@ packages:
resolution: {integrity: sha512-9UiX/Bl6J2yaBbxKoEBRm4Cipxgok8kQYcOPEhScPwebu2I0HoQOuYdIO6S3hLuWoZgpDpwQZMzTFxgpkyT76g==}
engines: {node: 20 || >=22}
+ deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting [email protected]
hasBin: true
@@ -11078,11 +11080,8 @@ packages:
resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
engines: {node: '>=8'}
- resolution: {integrity: sha512-IXCRip2IQzKwxArNNq1S+On4KPML3Yyn8Zzs/xRgcgOWIr8ntIK3IKzjFPfjy/7kt9ZMjc+FItfqHRBg8b6tNQ==}
-
- resolution: {integrity: sha512-kgCOlsnyWb+p0WU+01RjkCH+eBVsjL1jOwUYWv0YDWkM2/A46+LDKVs5yZCUXjJG6bj4ndFoAg5iLIIue6dulg==}
+ resolution: {integrity: sha512-55Dj73uq9ZXL5zyeRPzHQsK7Nbyt6Y10k5s7OjuFZGMhpp4r/rsLBH0o/0fstIzX1Lep9VxefWljK/SKCzygIA==}
resolution: {integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==}
@@ -12107,12 +12106,6 @@ packages:
resolution: {integrity: sha512-RAaHx7B14ZU04EU31pT+rKz2/zSl7xMsfIZuo8pd+KZO6PXtQmpevpq3vxvWNcrGbdmhM/rr5Uw5Mz+NBfhVng==}
- resolution: {integrity: sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==}
-
- resolution: {integrity: sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==}
-
resolution: {integrity: sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==}
@@ -12482,7 +12475,7 @@ snapshots:
remark-parse: 11.0.0
remark-rehype: 11.1.2
remark-smartypants: 3.0.2
- shiki: 3.20.0
+ shiki: 3.23.0
smol-toml: 1.6.0
unified: 11.0.5
unist-util-remove-position: 5.0.0
@@ -13833,7 +13826,7 @@ snapshots:
'@expressive-code/[email protected]':
dependencies:
'@expressive-code/core': 0.41.3
- shiki: 3.20.0
+ shiki: 3.23.0
'@expressive-code/[email protected]':
dependencies:
@@ -16952,33 +16945,33 @@ snapshots:
- encoding
- supports-color
- '@shikijs/[email protected]':
+ '@shikijs/[email protected]':
dependencies:
- '@shikijs/types': 3.20.0
+ '@shikijs/types': 3.23.0
'@shikijs/vscode-textmate': 10.0.2
'@types/hast': 3.0.4
hast-util-to-html: 9.0.5
- '@shikijs/[email protected]':
+ '@shikijs/[email protected]':
dependencies:
- '@shikijs/types': 3.20.0
+ '@shikijs/types': 3.23.0
'@shikijs/vscode-textmate': 10.0.2
oniguruma-to-es: 4.3.4
- '@shikijs/[email protected]':
+ '@shikijs/[email protected]':
dependencies:
- '@shikijs/types': 3.20.0
+ '@shikijs/types': 3.23.0
'@shikijs/vscode-textmate': 10.0.2
- '@shikijs/[email protected]':
+ '@shikijs/[email protected]':
dependencies:
- '@shikijs/types': 3.20.0
+ '@shikijs/types': 3.23.0
- '@shikijs/[email protected]':
+ '@shikijs/[email protected]':
dependencies:
- '@shikijs/types': 3.20.0
+ '@shikijs/types': 3.23.0
- '@shikijs/[email protected]':
+ '@shikijs/[email protected]':
dependencies:
'@shikijs/vscode-textmate': 10.0.2
'@types/hast': 3.0.4
@@ -17676,9 +17669,9 @@ snapshots:
'@types/[email protected]': {}
- '@types/[email protected]':
+ '@types/[email protected]':
dependencies:
- bun-types: 1.3.9
+ bun-types: 1.3.10
'@types/[email protected]': {}
@@ -18158,8 +18151,6 @@ snapshots:
-
dependencies:
color-convert: 1.9.3
@@ -18260,7 +18251,7 @@ snapshots:
prompts: 2.4.2
rehype: 13.0.2
semver: 7.7.3
- shiki: 3.20.0
+ shiki: 3.23.0
smol-toml: 1.6.0
svgo: 4.0.0
tinyexec: 1.0.2
@@ -18449,7 +18440,7 @@ snapshots:
'@types/node': 24.0.8
'@types/react': 19.2.2
dependencies:
'@types/node': 24.0.8
@@ -18977,16 +18968,16 @@ snapshots:
transitivePeerDependencies:
- supports-color
optionalDependencies:
'@libsql/client': 0.15.15
'@opentelemetry/api': 1.9.0
'@types/pg': 8.15.6
- bun-types: 1.3.9
+ bun-types: 1.3.10
dependencies:
- drizzle-orm: 0.44.4(@libsql/[email protected])(@opentelemetry/[email protected])(@types/[email protected])([email protected])
+ drizzle-orm: 0.44.4(@libsql/[email protected])(@opentelemetry/[email protected])(@types/[email protected])([email protected])
zod: 4.1.13
@@ -22649,21 +22640,14 @@ snapshots:
- dependencies:
- ansi-sequence-parser: 1.1.3
- jsonc-parser: 3.3.1
- vscode-oniguruma: 1.7.0
- vscode-textmate: 8.0.0
-
dependencies:
- '@shikijs/core': 3.20.0
- '@shikijs/engine-javascript': 3.20.0
- '@shikijs/engine-oniguruma': 3.20.0
- '@shikijs/langs': 3.20.0
- '@shikijs/themes': 3.20.0
- '@shikijs/types': 3.20.0
+ '@shikijs/core': 3.23.0
+ '@shikijs/engine-javascript': 3.23.0
+ '@shikijs/engine-oniguruma': 3.23.0
+ '@shikijs/langs': 3.23.0
+ '@shikijs/themes': 3.23.0
+ '@shikijs/types': 3.23.0
'@shikijs/vscode-textmate': 10.0.2
'@types/hast': 3.0.4
@@ -23743,10 +23727,6 @@ snapshots:
-
-