@vibe-agent-toolkit/vat-development-agents 0.1.14 → 0.1.15-rc.2

package/agents/agent-generator/DESIGN-NOTES.md

@@ -45,7 +45,7 @@ Document schema refinements and learnings discovered while designing agent-gener
 **Key Design Principles:**
 1. **Agent outputs data, not files**: Wrapper script handles file I/O
 2. **Validation built-in**: Agent validates its own output before returning
-3. **Portability**: Works in any environment (CLI, web, Claude Skills)
+3. **Portability**: Works in any environment (CLI, web, Agent Skills)
 4. **Transparency**: Architecture decisions documented for user understanding
 
 **Validation Strategy:**
@@ -87,7 +87,7 @@ Document schema refinements and learnings discovered while designing agent-gener
 - Phase 4 (GENERATE): Structured output with validation
 
 **Key Design Principle:**
-Agent outputs data (JSON object with file contents), not files. This makes the agent portable across different execution environments (CLI, web, Claude Skills).
+Agent outputs data (JSON object with file contents), not files. This makes the agent portable across different execution environments (CLI, web, Agent Skills).
 
 ### User Prompt Template Design
 
@@ -510,7 +510,7 @@ The four-phase workflow pattern (GATHER → ANALYZE → DESIGN → GENERATE) dis
 4. **Separation of concerns** - Agent outputs data (JSON), not files
    - Wrapper script handles file I/O and portability
    - Agent focuses on design logic, not system integration
-   - Same agent output can be used in CLI, web, Claude Skills without modification
+   - Same agent output can be used in CLI, web, Agent Skills without modification
 
 5. **Examples in input schema** - Providing concrete examples for each input field significantly improves user guidance
    - Users understand what level of detail is needed

package/dist/generated/resources/skills/SKILL.d.ts

@@ -17,19 +17,15 @@ export const text: string;
 
 export const fragments: {
   readonly purposeForUsersNotContributors: Fragment;
-  readonly whatIsVat: Fragment;
   readonly whenToUseVat: Fragment;
-  readonly creatingAgentsWithAgentGenerator: Fragment;
-  readonly understandingAgentPatterns: Fragment;
-  readonly vatCliWorkflows: Fragment;
-  readonly resultEnvelopesAndErrorHandling: Fragment;
-  readonly orchestrationPatterns: Fragment;
-  readonly testingAgents: Fragment;
-  readonly ragKnowledgeBases: Fragment;
-  readonly bestPractices: Fragment;
-  readonly nextSteps: Fragment;
-  readonly documentationIndex: Fragment;
+  readonly skillRoutingTable: Fragment;
+  readonly agentArchetypesQuickReference: Fragment;
+  readonly coreCliCommands: Fragment;
+  readonly agentGeneratorCreatingNewAgents: Fragment;
+  readonly packagingMarkdownForReuse: Fragment;
+  readonly commonWorkflows: Fragment;
   readonly successCriteria: Fragment;
+  readonly documentationIndex: Fragment;
   readonly gettingHelp: Fragment;
 };
 

package/dist/generated/resources/skills/SKILL.js

@@ -7,82 +7,62 @@ export const meta = {
   description: "User adoption guide for building portable AI agents with VAT - agent creation, CLI workflows, and best practices"
 };
 
-export const text = "\n# Vibe Agent Toolkit Skill\n\nComprehensive guide for creating portable AI agents using the Vibe Agent Toolkit (VAT). This skill covers agent creation, CLI workflows, and practical usage patterns.\n\n## Purpose: For Users, Not Contributors\n\n**Key distinction:**\n- **This skill** = How to USE VAT to build agents\n- **Root CLAUDE.md** = How to DEVELOP VAT itself\n\nThis skill focuses on agent authoring, not VAT codebase development.\n\n## What is VAT?\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across multiple LLM frameworks and deployment targets.\n\n### What VAT IS\n\n- **Agent authoring framework** - Define agents once, run anywhere\n- **Multi-runtime support** - Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK\n- **Standardized patterns** - Consistent result envelopes, error handling, orchestration\n- **Type-safe** - Full TypeScript support with Zod schemas\n- **Framework agnostic** - Agents are plain functions, no vendor lock-in\n\n### What VAT IS NOT\n\n- **NOT a chat UI** - VAT provides the agent logic, not the interface\n- **NOT an LLM provider** - Bring your own API keys (OpenAI, Anthropic, etc.)\n- **NOT a deployment platform** - Deploy agents where you want (cloud, edge, local)\n- **NOT opinionated about domains** - Use for any domain (code analysis, data processing, customer service, etc.)\n\n### Core Value Proposition\n\n**Write Once, Run Anywhere**\n\n\`\`\`typescript\n// 1. Define agent once (plain TypeScript)\nexport async function analyzeSentiment(text: string) {\n  // Your logic here\n  return { sentiment: \'positive\', confidence: 0.9 };\n}\n\n// 2. Adapt to ANY runtime\n// Vercel AI SDK\nconst vercelTool = createVercelAISDKAdapter(analyzeSentiment);\n\n// LangChain\nconst langchainTool = createLangChainAdapter(analyzeSentiment);\n\n// OpenAI\nconst openaiTool = createOpenAIAdapter(analyzeSentiment);\n\n// Claude Agent SDK\nconst claudeTool = createClaudeAgentSDKAdapter(analyzeSentiment);\n\`\`\`\n\nNo framework-specific code in your agent. Runtime adapters handle the translation.\n\n## When to Use VAT\n\n### VAT is Great For\n\n**✅ Multi-framework projects**\n- Team uses different LLM frameworks\n- Want flexibility to switch frameworks later\n- Building a platform that supports multiple frameworks\n\n**✅ Reusable agent libraries**\n- Creating internal agent packages\n- Open-source agent collections\n- Marketplace/plugin systems\n\n**✅ Testing and experimentation**\n- Compare LLM performance across providers\n- A/B test different frameworks\n- Validate agent logic without framework lock-in\n\n**✅ Complex orchestration**\n- Multi-agent workflows\n- Validation loops (generate → validate → retry)\n- Human-in-the-loop approval gates\n- Conversational multi-turn agents\n\n### VAT May NOT Be Needed For\n\n**❌ Simple one-off scripts**\n- Single-use agent, not reused\n- Framework is already decided\n- No portability required\n\n**❌ Framework-specific features**\n- Need deep integration with one framework\n- Using advanced framework-specific capabilities\n- Framework provides everything you need\n\n**❌ No TypeScript/JavaScript projects**\n- VAT is TypeScript-first\n- Other languages not currently supported\n\n## Creating Agents with agent-generator\n\nThe **agent-generator** is a meta-agent that helps you design high-quality agents through guided conversation.\n\n### What agent-generator Does\n\nAgent-generator guides you through a **4-phase workflow**:\n\n1. **GATHER** - Understand your intent and goals\n2. **ANALYZE** - Identify agent pattern and requirements\n3. **DESIGN** - Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** - Create validated agent package\n\n### How to Use agent-generator\n\n**Step 1: Provide Requirements**\n\nMinimum viable input:\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nOptional context (improves recommendations):\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\",\n  \"typicalInputs\": \"GitHub PR diff\",\n  \"expectedOutputs\": \"List of security issues with severity\",\n  \"performanceRequirements\": {\n    \"latency\": \"Under 30 seconds per PR\",\n    \"accuracy\": \"Zero false negatives on critical issues\",\n    \"cost\": \"Under $0.10 per PR\"\n  }\n}\n\`\`\`\n\n**Step 2: Conversational Refinement**\n\nAgent-generator asks follow-up questions:\n- What tools does the agent need? (file readers, APIs, etc.)\n- What domain knowledge is required?\n- What are edge cases to handle?\n- What\'s the input/output format?\n\n**Step 3: Architecture Recommendations**\n\nAgent-generator makes informed decisions:\n- **LLM selection** - Based on accuracy/speed/cost requirements\n- **Tool selection** - Minimizes count, justifies each\n- **Prompt strategy** - Context-efficient, high-signal\n- **Resource planning** - References, examples, schemas\n\n**Step 4: Generated Agent Package**\n\nOutput includes:\n- \`agent.yaml\` - Validated agent manifest\n- \`prompts/system.md\` - System prompt\n- \`prompts/user.md\` - User prompt template\n- \`schemas/input.schema.json\` - Input validation\n- \`schemas/output.schema.json\` - Output validation\n- \`README.md\` - Usage documentation\n\n**Step 5: Customize and Deploy**\n\n- Review generated prompts, adjust as needed\n- Test agent with sample inputs\n- Deploy using runtime adapters\n\n### agent-generator Best Practices\n\n**Be specific about success criteria:**\n\`\`\`\n❌ \"Make it work well\"\n✅ \"Catches 100% of SQL injection vulnerabilities\"\n\`\`\`\n\n**Provide performance requirements:**\n\`\`\`\n❌ \"Fast enough\"\n✅ \"Under 5 seconds per request, under $0.01 per call\"\n\`\`\`\n\n**Describe domain context:**\n\`\`\`\n❌ \"Security stuff\"\n✅ \"OWASP Top 10, CWE database, company coding standards\"\n\`\`\`\n\n**Identify tools early:**\n\`\`\`\n❌ \"Whatever it needs\"\n✅ \"File reader, GitHub API, static analysis tool\"\n\`\`\`\n\n### agent-generator Resources\n\nThe generator incorporates best practices from:\n- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)\n- [Effective Context Engineering - Anthropic](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)\n- [Agent System Design Patterns - Databricks](https://docs.databricks.com/aws/en/generative-ai/guide/agent-system-design-patterns)\n- [AI Agent Orchestration - Microsoft Azure](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)\n\n**Documentation:**\n- [agent-authoring.md](../../../../docs/agent-authoring.md) - Agent patterns and examples\n- [orchestration.md](../../../../docs/orchestration.md) - Multi-agent workflows\n\n## Understanding Agent Patterns\n\nVAT supports multiple agent patterns (archetypes) for different use cases.\n\n### Pattern 1: Pure Function Tool\n\n**When to use:** Stateless validation, transformation, computation\n\n**Characteristics:**\n- No LLM calls\n- Deterministic output\n- Fast execution\n- Easy to test\n\n**Example use cases:**\n- Input validation\n- Data transformation\n- Format conversion\n- Rules-based logic\n\n**Code pattern:**\n\`\`\`typescript\nexport async function validateInput(input: MyInput): Promise<ValidationResult> {\n  if (input.text.length < 5) {\n    return { status: \'error\', error: \'too-short\' };\n  }\n  return { status: \'success\', data: { valid: true } };\n}\n\`\`\`\n\n### Pattern 2: One-Shot LLM Analyzer\n\n**When to use:** Single LLM call for analysis, classification, generation\n\n**Characteristics:**\n- One LLM call per execution\n- Stateless\n- Handles LLM errors\n- Parses and validates output\n\n**Example use cases:**\n- Sentiment analysis\n- Text classification\n- Entity extraction\n- Creative generation\n\n**Code pattern:**\n\`\`\`typescript\nexport async function analyzeSentiment(text: string, context: AgentContext) {\n  const response = await context.callLLM([\n    { role: \'user\', content: \`Analyze sentiment: \"${text}\"\` }\n  ]);\n\n  const parsed = JSON.parse(response);\n  return { status: \'success\', data: parsed };\n}\n\`\`\`\n\n### Pattern 3: Conversational Assistant\n\n**When to use:** Multi-turn dialogue, progressive data collection\n\n**Characteristics:**\n- Multiple LLM calls across turns\n- Maintains session state\n- Phases (gathering → ready → complete)\n- Natural language replies + machine-readable results\n\n**Example use cases:**\n- Customer support chatbots\n- Product advisors\n- Interview/survey agents\n- Multi-step form filling\n\n**Code pattern:**\n\`\`\`typescript\nexport async function conversationalAgent(\n  message: string,\n  sessionState: SessionState\n) {\n  if (sessionState.phase === \'gathering\') {\n    // Collect more info\n    return {\n      reply: \"Can you tell me more about X?\",\n      sessionState: { ...sessionState },\n      result: { status: \'in-progress\' }\n    };\n  }\n\n  // Ready to complete\n  return {\n    reply: \"Here\'s your result!\",\n    sessionState: { ...sessionState, phase: \'complete\' },\n    result: { status: \'success\', data: finalResult }\n  };\n}\n\`\`\`\n\n### Pattern 4: External Event Integrator\n\n**When to use:** Waiting for external events (approvals, webhooks)\n\n**Characteristics:**\n- Emits event, blocks waiting for response\n- Timeout handling\n- External system unavailability\n- Can be mocked for testing\n\n**Example use cases:**\n- Human-in-the-loop approval\n- Webhook integrations\n- External API polling\n- Third-party service calls\n\n**Code pattern:**\n\`\`\`typescript\nexport async function humanApproval(\n  request: ApprovalRequest,\n  options = { mockable: true, timeout: 30000 }\n) {\n  if (options.mockable) {\n    // Mock mode for testing\n    return { status: \'success\', data: { approved: true } };\n  }\n\n  // Real mode - emit event and wait\n  const response = await emitEvent(request, options.timeout);\n  return { status: \'success\', data: response };\n}\n\`\`\`\n\n**See also:**\n- [agent-authoring.md](../../../../docs/agent-authoring.md) - Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) - Chaining and workflows\n\n## VAT CLI Workflows\n\nThe VAT CLI (\`vat\`) provides commands for working with agents, skills, and resources.\n\n### Installation\n\n\`\`\`bash\n# Global installation (recommended)\nnpm install -g vibe-agent-toolkit\n\n# Or install just the CLI\nnpm install -g @vibe-agent-toolkit/cli\n\n# Verify installation\nvat --version\n\`\`\`\n\n### Skills Commands\n\n**List available skills:**\n\`\`\`bash\n# Scan for SKILL.md files in current directory\nvat skills list\n\n# Show user-installed skills (~/.claude/plugins)\nvat skills list --user\n\`\`\`\n\n**Install skills:**\n\`\`\`bash\n# From npm package\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\n\n# From local directory\nvat skills install ./my-skills\n\n# From zip file\nvat skills install ./skills.zip\n\`\`\`\n\n**Validate skill quality:**\n\`\`\`bash\n# Validate all skills declared in package.json vat.skills\nvat skills validate\n\n# Validate a specific skill by name\nvat skills validate --skill my-skill\n\n# Show verbose output (excluded reference details)\nvat skills validate --verbose\n\`\`\`\n\n**Build skills for distribution:**\n\`\`\`bash\n# Build all skills in package\nvat skills build\n\n# Build specific skill\nvat skills build --skill my-skill\n\n# Dry-run (preview)\nvat skills build --dry-run\n\`\`\`\n\n### Packaging Options\n\nConfigure \`packagingOptions\` in your skill\'s \`vat.skills[]\` entry in package.json:\n\n\`\`\`json\n{\n  \"vat\": {\n    \"skills\": [{\n      \"name\": \"my-skill\",\n      \"source\": \"./SKILL.md\",\n      \"path\": \"./dist/skills/my-skill\",\n      \"packagingOptions\": {\n        \"linkFollowDepth\": 1,\n        \"resourceNaming\": \"resource-id\",\n        \"stripPrefix\": \"knowledge-base\",\n        \"excludeReferencesFromBundle\": {\n          \"rules\": [\n            { \"patterns\": [\"**/concepts/**\"], \"template\": \"Use search to find: {{link.text}}\" }\n          ],\n          \"defaultTemplate\": \"{{link.text}} (search knowledge base)\"\n        }\n      }\n    }]\n  }\n}\n\`\`\`\n\n**\`linkFollowDepth\`** — Controls how deep links are followed from SKILL.md:\n\n| Value | Behavior |\n|-------|----------|\n| \`0\` | Skill file only (no links followed) |\n| \`1\` | Direct links only |\n| \`2\` | Direct + one transitive level **(default)** |\n| \`N\` | N levels of transitive links |\n| \`\"full\"\` | Complete transitive closure |\n\n**\`resourceNaming\`** — How bundled files are named in output:\n\n| Strategy | Example Output | Use When |\n|----------|---------------|----------|\n| \`basename\` | \`overview.md\` | Few files, unique names **(default)** |\n| \`resource-id\` | \`topics-quickstart-overview.md\` | Many files, flat output needed |\n| \`preserve-path\` | \`topics/quickstart/overview.md\` | Preserve original structure |\n\nUse \`stripPrefix\` to remove a common directory prefix (e.g., \`\"knowledge-base\"\`).\n\n**\`excludeReferencesFromBundle\`** — Rules for excluding files and rewriting their links:\n\n- \`rules[]\` — Ordered glob patterns (first match wins), each with optional Handlebars template\n- \`defaultTemplate\` — Applied to depth-exceeded links not matching any rule\n\n**Template variables:**\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| \`{{link.text}}\` | Link display text | \`\"Setup Guide\"\` |\n| \`{{link.uri}}\` | Original href | \`\"./docs/setup.md\"\` |\n| \`{{link.fileName}}\` | Target filename | \`\"setup.md\"\` |\n| \`{{link.filePath}}\` | Path relative to skill root | \`\"docs/setup.md\"\` |\n| \`{{skill.name}}\` | Skill name from frontmatter | \`\"my-skill\"\` |\n\n**\`ignoreValidationErrors\`** — Override validation rules:\n\n\`\`\`json\n\"ignoreValidationErrors\": {\n  \"SKILL_LENGTH_EXCEEDS_RECOMMENDED\": \"Large domain requires detailed examples\",\n  \"NO_PROGRESSIVE_DISCLOSURE\": {\n    \"reason\": \"Temporary — refactoring planned\",\n    \"expires\": \"2026-06-30\"\n  }\n}\n\`\`\`\n\n### Agent Commands\n\n**Import Claude Skills to VAT format:**\n\`\`\`bash\n# Import skill to agent.yaml\nvat agent import my-skill/SKILL.md\n\n# Custom output path\nvat agent import my-skill/SKILL.md --output my-agent/agent.yaml\n\n# Force overwrite\nvat agent import my-skill/SKILL.md --force\n\`\`\`\n\n**Audit agent/skill quality:**\n\`\`\`bash\n# Audit single file\nvat agent audit my-agent/agent.yaml\n\n# Audit directory recursively\nvat agent audit agents/ --recursive\n\n# Detailed validation errors\nvat agent audit my-agent/agent.yaml --debug\n\`\`\`\n\nThe audit checks for:\n- Required frontmatter fields\n- Naming conventions\n- Description length limits\n- Link integrity\n- Console tool availability\n\n### RAG Commands\n\n**Index documentation into a vector database:**\n\`\`\`bash\n# Index all markdown files in docs/\nvat rag index docs/\n\n# Index with specific database path\nvat rag index docs/ --db ./dist/rag-db\n\`\`\`\n\n**Search indexed documentation:**\n\`\`\`bash\n# Semantic search\nvat rag query \"How do I configure authentication?\"\n\n# Limit results\nvat rag query \"error handling\" --limit 5\n\n# Query specific database\nvat rag query \"setup guide\" --db ./dist/rag-db\n\`\`\`\n\n**Manage the database:**\n\`\`\`bash\n# View database statistics\nvat rag stats\n\n# Clear and rebuild\nvat rag clear\nvat rag index docs/\n\`\`\`\n\n### Resources Commands\n\n**Validate markdown resources:**\n\`\`\`bash\n# Validate directory\nvat resources validate docs/\n\n# With frontmatter schema validation\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Strict mode (warnings become errors)\nvat resources validate docs/ --strict\n\`\`\`\n\n**Parse and extract resource metadata:**\n\`\`\`bash\n# Parse directory and output JSON\nvat resources parse docs/ --output resources.json\n\n# Parse with link resolution\nvat resources parse docs/ --resolve-links\n\`\`\`\n\n### Common Workflows\n\n**Workflow 1: Create New Agent**\n\`\`\`bash\n# 1. Use agent-generator (interactive)\n# Follow prompts to define your agent\n\n# 2. Review generated files\ncat my-agent/agent.yaml\ncat my-agent/prompts/system.md\n\n# 3. Test agent\ncd my-agent\nvat test\n\n# 4. Package for distribution\nvat package\n\`\`\`\n\n**Workflow 2: Install and Use Skills**\n\`\`\`bash\n# 1. Install skill from npm\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\n\n# 2. List installed skills\nvat skills list --user\n\n# 3. Use in Claude Code\n# Skills appear in ~/.claude/plugins/\n# Claude Code auto-loads them\n\`\`\`\n\n**Workflow 3: Validate and Audit**\n\`\`\`bash\n# 1. Create/edit skill\nvim my-skill/SKILL.md\n\n# 2. Validate before import\nvat skills validate my-skill/SKILL.md\n\n# 3. Audit for quality issues\nvat agent audit my-skill/SKILL.md\n\n# 4. Import to VAT format\nvat agent import my-skill/SKILL.md\n\`\`\`\n\n**Workflow 4: Build and Distribute**\n\`\`\`bash\n# 1. Add vat.skills to package.json\n# (See distribution standard docs)\n\n# 2. Build skills\nbun run build  # Includes vat skills build\n\n# 3. Test locally\nvat skills install ./packages/my-skills\n\n# 4. Publish to npm\nnpm publish\n\n# 5. Install from npm\nvat skills install npm:@my-org/my-skills\n\`\`\`\n\n### CLI Tips\n\n**Use --help for any command:**\n\`\`\`bash\nvat --help\nvat skills --help\nvat skills install --help\n\`\`\`\n\n**Use --dry-run for preview:**\n\`\`\`bash\nvat skills build --dry-run\nvat skills install my-skill --dry-run\n\`\`\`\n\n**Use --debug for troubleshooting:**\n\`\`\`bash\nvat skills validate my-skill --debug\nvat agent audit my-agent --debug\n\`\`\`\n\n**Check skill installation location:**\n\`\`\`bash\n# User skills\nls ~/.claude/plugins/\n\n# Project skills\nls .claude/skills/\n\`\`\`\n\n## Result Envelopes and Error Handling\n\nVAT uses standardized result envelopes for type-safe composition and error handling.\n\n### Core Result Types\n\n**AgentResult<TData, TError>** - For single-execution agents:\n\`\`\`typescript\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\n**StatefulAgentResult<TData, TError, TMetadata>** - For conversational agents:\n\`\`\`typescript\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\n### Standard Error Types\n\n**LLM errors:**\n\`\`\`typescript\ntype LLMError =\n  | \'llm-refusal\'          // LLM refused to generate\n  | \'llm-invalid-output\'   // Output format incorrect\n  | \'llm-timeout\'          // Request timed out\n  | \'llm-rate-limit\'       // Hit rate limit\n  | \'llm-token-limit\'      // Exceeded token limit\n  | \'llm-unavailable\';     // Service unavailable\n\`\`\`\n\n**Event integration errors:**\n\`\`\`typescript\ntype ExternalEventError =\n  | \'event-timeout\'           // External event timed out\n  | \'event-unavailable\'       // System unavailable\n  | \'event-rejected\'          // Request rejected\n  | \'event-invalid-response\'; // Invalid response\n\`\`\`\n\n### Error Handling Pattern\n\nAlways check status before accessing data:\n\n\`\`\`typescript\nconst output = await myAgent.execute(input);\n\nif (output.result.status === \'success\') {\n  // Type-safe access to data\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  // Type-safe access to error\n  console.error(\'Failed:\', output.result.error);\n} else {\n  // In-progress (conversational agents)\n  console.log(\'Still working:\', output.result.metadata);\n}\n\`\`\`\n\n### Result Helpers\n\nVAT provides helpers for working with results:\n\n**mapResult()** - Transform success data:\n\`\`\`typescript\nimport { mapResult } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst result = { status: \'success\', data: 10 };\nconst doubled = mapResult(result, (n) => n * 2);\n// doubled = { status: \'success\', data: 20 }\n\`\`\`\n\n**andThen()** - Chain operations:\n\`\`\`typescript\nimport { andThen } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst output1 = await agent1.execute(input);\nconst output2 = await andThen(output1.result, async (data) => {\n  const out = await agent2.execute(data);\n  return out.result;\n});\n\`\`\`\n\n**match()** - Pattern match on status:\n\`\`\`typescript\nimport { match } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst message = match(result, {\n  success: (data) => \`Success: ${data}\`,\n  error: (err) => \`Error: ${err}\`,\n  inProgress: (meta) => \`Working: ${meta.step}\`,\n});\n\`\`\`\n\n**See also:** [orchestration.md](../../../../docs/orchestration.md) for composition patterns\n\n## Orchestration Patterns\n\nCombine agents into workflows using standardized result envelopes.\n\n### Sequential Pipeline\n\nExecute agents in order, passing results forward:\n\n\`\`\`typescript\n// Step 1: Analyze\nconst analysisOutput = await analyzer.execute(input);\n\n// Step 2: Process (only if step 1 succeeded)\nconst processedOutput = await andThen(\n  analysisOutput.result,\n  async (data) => {\n    const out = await processor.execute(data);\n    return out.result;\n  }\n);\n\n// Step 3: Validate (only if step 2 succeeded)\nconst finalOutput = await andThen(\n  processedOutput,\n  async (data) => {\n    const out = await validator.execute(data);\n    return out.result;\n  }\n);\n\`\`\`\n\n### Parallel Execution\n\nRun multiple agents concurrently:\n\n\`\`\`typescript\n// Execute in parallel\nconst [output1, output2, output3] = await Promise.all([\n  agent1.execute(input),\n  agent2.execute(input),\n  agent3.execute(input),\n]);\n\n// Combine results\nif (output1.result.status === \'success\' &&\n    output2.result.status === \'success\' &&\n    output3.result.status === \'success\') {\n  // All succeeded\n  const combined = combineResults(\n    output1.result.data,\n    output2.result.data,\n    output3.result.data\n  );\n}\n\`\`\`\n\n### Validation Loop\n\nGenerator + Validator with retry:\n\n\`\`\`typescript\nasync function generateValidOutput(\n  input: MyInput,\n  maxAttempts: number = 5\n) {\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    // Generate\n    const generatorOutput = await generator.execute(input);\n    if (generatorOutput.result.status === \'error\') continue;\n\n    // Validate\n    const validatorOutput = await validator.execute(\n      generatorOutput.result.data\n    );\n\n    if (validatorOutput.result.status === \'success\' &&\n        validatorOutput.result.data.valid) {\n      // Found valid output!\n      return generatorOutput.result.data;\n    }\n\n    // Invalid, retry with feedback\n    console.log(\'Attempt\', attempt + 1, \'invalid:\',\n      validatorOutput.result.data.reason);\n  }\n\n  throw new Error(\'Max attempts exceeded\');\n}\n\`\`\`\n\n### Human-in-the-Loop\n\nIntegrate human approval:\n\n\`\`\`typescript\n// Generate content\nconst generatorOutput = await generator.execute(input);\n\nif (generatorOutput.result.status === \'success\') {\n  // Request approval\n  const approvalOutput = await humanApproval.execute({\n    content: generatorOutput.result.data,\n    context: input,\n  });\n\n  if (approvalOutput.result.status === \'success\' &&\n      approvalOutput.result.data.approved) {\n    // Approved - continue\n    return generatorOutput.result.data;\n  } else {\n    // Rejected - handle feedback\n    console.log(\'Rejected:\', approvalOutput.result.data.feedback);\n  }\n}\n\`\`\`\n\n### Conversational Multi-Turn\n\nHandle stateful conversations:\n\n\`\`\`typescript\nlet session = {\n  state: { phase: \'gathering\' },\n  history: [],\n};\n\nwhile (true) {\n  const userMessage = await getUserInput();\n\n  const output = await conversationalAgent.execute({\n    message: userMessage,\n    sessionState: session.state,\n  });\n\n  console.log(\'Agent:\', output.reply);\n\n  // Update session\n  session = {\n    state: output.sessionState,\n    history: [\n      ...session.history,\n      { role: \'user\', content: userMessage },\n      { role: \'assistant\', content: output.reply },\n    ],\n  };\n\n  // Check completion\n  if (output.result.status === \'success\') {\n    console.log(\'Final result:\', output.result.data);\n    break;\n  } else if (output.result.status === \'error\') {\n    console.error(\'Failed:\', output.result.error);\n    break;\n  }\n  // Otherwise status === \'in-progress\', continue\n}\n\`\`\`\n\n**See also:** [orchestration.md](../../../../docs/orchestration.md) for complete guide\n\n## Testing Agents\n\nVAT provides test helpers and patterns for agent testing.\n\n### Unit Testing Pure Functions\n\n\`\`\`typescript\nimport { describe, expect, it } from \'vitest\';\nimport { resultMatchers } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myValidator\', () => {\n  it(\'should validate correct input\', async () => {\n    const output = await myValidator.execute({ text: \'valid\' });\n\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.valid).toBe(true);\n  });\n\n  it(\'should reject invalid input\', async () => {\n    const output = await myValidator.execute({ text: \'x\' });\n\n    resultMatchers.expectError(output.result);\n    expect(output.result.error).toBe(\'too-short\');\n  });\n});\n\`\`\`\n\n### Integration Testing with Mock LLM\n\n\`\`\`typescript\nimport { createMockContext } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myAnalyzer with mock LLM\', () => {\n  it(\'should parse LLM response\', async () => {\n    const mockContext = createMockContext(\n      JSON.stringify({ sentiment: \'positive\', confidence: 0.9 })\n    );\n\n    const output = await myAnalyzer.execute(\n      { text: \'Great!\' },\n      mockContext\n    );\n\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.sentiment).toBe(\'positive\');\n  });\n});\n\`\`\`\n\n### Testing Conversational Flows\n\n\`\`\`typescript\ndescribe(\'conversational agent flow\', () => {\n  it(\'should gather info progressively\', async () => {\n    // Turn 1\n    const output1 = await agent.execute({\n      message: \'Hello\',\n    });\n    expect(output1.reply).toContain(\'name?\');\n    resultMatchers.expectInProgress(output1.result);\n\n    // Turn 2\n    const output2 = await agent.execute({\n      message: \'My name is Alice\',\n      sessionState: output1.sessionState,\n    });\n    expect(output2.reply).toContain(\'age?\');\n    resultMatchers.expectInProgress(output2.result);\n\n    // Turn 3 (complete)\n    const output3 = await agent.execute({\n      message: \'I am 30\',\n      sessionState: output2.sessionState,\n    });\n    resultMatchers.expectSuccess(output3.result);\n    expect(output3.result.data).toBeDefined();\n  });\n});\n\`\`\`\n\n## RAG Knowledge Bases\n\nVAT includes a full RAG (Retrieval-Augmented Generation) system for building searchable knowledge bases from markdown documentation. Key capabilities:\n\n- **Semantic search** over markdown files using vector embeddings\n- **Content transforms** — rewrite markdown links before indexing (e.g., convert local file links to plain text references)\n- **Document storage** — optionally persist full source documents alongside chunks for search-then-retrieve patterns\n- **Incremental indexing** — skip unchanged files, re-index only modifications\n- **Multiple embedding providers** — offline Transformers.js (default), ONNX Runtime, or OpenAI\n\nFor complete usage examples, configuration, and the programmatic TypeScript API, see the [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md).\n\n## Best Practices\n\n### 1. Use Result Envelopes Consistently\n\nAlways return result envelopes, never throw exceptions for expected errors:\n\n\`\`\`typescript\n// ✅ GOOD\nreturn { result: { status: \'error\', error: \'invalid-input\' } };\n\n// ❌ BAD\nthrow new Error(\'Invalid input\');\n\`\`\`\n\n### 2. Define Clear Error Types\n\nUse enums or literal unions:\n\n\`\`\`typescript\n// ✅ GOOD\ntype MyError = \'invalid-format\' | \'processing-failed\' | \'timeout\';\n\n// ❌ BAD\ntype MyError = string;\n\`\`\`\n\n### 3. Validate Input and Output\n\nUse Zod schemas for type safety:\n\n\`\`\`typescript\nimport { z } from \'zod\';\n\nconst InputSchema = z.object({\n  text: z.string().min(1).max(1000),\n});\n\nconst OutputSchema = z.object({\n  result: z.boolean(),\n  reason: z.string().optional(),\n});\n\n// Validate at runtime\nconst input = InputSchema.parse(userInput);\nconst output = OutputSchema.parse(agentOutput);\n\`\`\`\n\n### 4. Test All Paths\n\nCover success, errors, and edge cases:\n\n\`\`\`typescript\ndescribe(\'myAgent\', () => {\n  it(\'should handle success case\');\n  it(\'should handle validation error\');\n  it(\'should handle LLM timeout\');\n  it(\'should handle malformed input\');\n});\n\`\`\`\n\n### 5. Use Mock Mode for External Dependencies\n\nEnable testing without API calls:\n\n\`\`\`typescript\nasync execute(input, options = { mockable: true }) {\n  if (options.mockable) {\n    // Fast, deterministic mock\n    return getMockResponse(input);\n  }\n  // Real API call\n  return await callExternalAPI(input);\n}\n\`\`\`\n\n### 6. Document Agent Behavior\n\nClear documentation helps users:\n\n\`\`\`typescript\n/**\n * Analyzes sentiment of text input.\n *\n * @param text - Text to analyze (max 1000 chars)\n * @returns Sentiment (positive/negative/neutral) with confidence score\n *\n * @example\n * const result = await analyzeSentiment(\"Great product!\");\n * // { sentiment: \'positive\', confidence: 0.9 }\n *\n * @throws Never throws - returns error result envelope on failure\n */\nexport async function analyzeSentiment(text: string) {\n  // ...\n}\n\`\`\`\n\n## Next Steps\n\nNow that you understand VAT basics:\n\n1. **Create your first agent** using agent-generator\n2. **Review examples** in \`@vibe-agent-toolkit/vat-example-cat-agents\`\n3. **Read detailed docs**:\n   - [agent-authoring.md](../../../../docs/agent-authoring.md)\n   - [orchestration.md](../../../../docs/orchestration.md)\n   - [getting-started.md](../../../../docs/getting-started.md)\n4. **Explore runtime adapters** for your preferred framework\n5. **Join the community** and share your agents\n\n## Documentation Index\n\n**Getting Started:**\n- [Getting Started Guide](../../../../docs/getting-started.md) - Setup and first steps\n\n**Agent Development:**\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) - Patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) - Multi-agent workflows\n\n**RAG & Knowledge Bases:**\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md) - Configuration, content transforms, document storage\n\n**Architecture:**\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md) - Multi-framework support\n\n**Examples:**\n- \`@vibe-agent-toolkit/vat-example-cat-agents\` - Reference implementations\n- Run demos: \`bun run demo:photos\`, \`bun run demo:conversation\`\n\n## Success Criteria\n\nYou\'ve successfully adopted VAT when:\n\n**For Single Agents:**\n- Agent has clear input/output schemas\n- Errors are handled as data (result envelopes)\n- Tests cover success and error paths\n- Agent works across multiple runtimes\n\n**For Workflows:**\n- Multi-agent pipelines compose cleanly\n- Retry logic handles transient failures\n- State management is explicit\n- Observability shows performance/cost\n\n**For Teams:**\n- Agents are reusable across projects\n- Framework choice is flexible\n- Testing doesn\'t require real APIs\n- Documentation enables self-service\n\n## Getting Help\n\n- **Documentation:** See Architecture Overview and Getting Started links above\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n\nHappy agent building!\n";
+export const text = "\n# Vibe Agent Toolkit Skill\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across\nmultiple LLM frameworks and deployment targets. Write your agent logic once as plain TypeScript,\nthen deploy it to Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK, or any other runtime using\nframework adapters. No vendor lock-in.\n\n## Purpose: For Users, Not Contributors\n\n- **This skill** = How to USE VAT to build agents\n- **Root CLAUDE.md** = How to DEVELOP the VAT codebase itself\n\n## When to Use VAT\n\n**VAT is great for:** Multi-framework projects, reusable agent libraries, testing across LLM\nproviders, complex multi-agent orchestration, human-in-the-loop workflows.\n\n**VAT may not be needed for:** Simple one-off scripts where the framework is already decided,\nnon-TypeScript/JavaScript projects, or cases where you need deep framework-specific features.\n\n## Skill Routing Table\n\n| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:agent-authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:agent-authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:agent-authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Packaging skills, \`--target claude-web\`, ZIP format | \`vibe-agent-toolkit:distribution\` |\n| Sideloading with \`vat install\`, npm postinstall hooks | \`vibe-agent-toolkit:distribution\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n\n## Agent Archetypes (Quick Reference)\n\nFour patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:agent-authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |\n\n## Core CLI Commands\n\n\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Skills\nvat skills list                          # list skills in current project\nvat skills list --user                   # list user-installed skills\nvat skills install npm:@org/my-skills    # install from npm\nvat skills build                         # build skills for distribution\nvat skills validate                      # validate skill quality\n\n# Resources\nvat resources validate                   # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit                                # audit current directory recursively\nvat audit --user                         # audit entire Claude installation\nvat audit ./plugins/ --compat            # check surface compatibility\n\n# RAG\nvat rag index docs/                      # index markdown into vector DB\nvat rag query \"my question\" --limit 5    # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`\n\n## agent-generator: Creating New Agents\n\nThe **agent-generator** is a built-in meta-agent that guides you through designing\nhigh-quality agents via a 4-phase workflow:\n\n1. **GATHER** — Understand your intent and goals\n2. **ANALYZE** — Identify agent pattern and requirements\n3. **DESIGN** — Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** — Create validated agent package\n\nMinimum input needed:\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nThe generator produces: \`agent.yaml\`, \`prompts/system.md\`, \`prompts/user.md\`,\n\`schemas/input.schema.json\`, \`schemas/output.schema.json\`, and \`README.md\`.\n\n**Tips for better results:**\n- Be specific about success criteria (\"Under 30s, zero false negatives\") not vague (\"fast enough\")\n- Name the tools the agent needs upfront (file readers, APIs, etc.)\n- Describe domain context (OWASP Top 10, company coding standards, etc.)\n\n## Packaging Markdown for Reuse\n\nVAT\'s resource compiler transforms markdown files into type-safe TypeScript modules,\nenabling prompt libraries, RAG knowledge bases, and shared content across projects.\n\n\`\`\`bash\nnpm install -D @vibe-agent-toolkit/resource-compiler\nnpx vat-compile-resources compile resources/ generated/resources/\n\`\`\`\n\n\`\`\`typescript\nimport * as Doc from \'./generated/resources/doc.js\';\n\nDoc.meta.title;                        // type-safe frontmatter\nDoc.fragments.introduction.text;       // H2 section content\nDoc.text;                              // full markdown\n\`\`\`\n\nUse cases: agent prompt libraries, RAG knowledge bases packaged as npm modules,\nmulti-project content sharing with versioning.\n\n## Common Workflows\n\n**Create a new agent:**\n\`\`\`bash\n# Use agent-generator interactively, then:\nvat agent import my-skill/SKILL.md   # import to VAT format\nvat skills validate                   # check quality\nvat skills build                      # package for distribution\n\`\`\`\n\n**Install and use a community skill:**\n\`\`\`bash\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\nvat skills list --user\n# Skills appear in ~/.claude/skills/ and are auto-loaded by Claude Code\n\`\`\`\n\n**Build and publish your own skill package:**\n\`\`\`bash\n# Add vat.skills to package.json, then:\nvat skills build          # builds all declared skills\nnpm publish               # publishes to npm\n# Users install with: vat skills install npm:@myorg/my-skills\n\`\`\`\n\n## Success Criteria\n\nYou\'ve successfully adopted VAT when:\n- Agents have clear input/output schemas (Zod-validated)\n- Errors are handled as data (result envelopes), never thrown\n- Tests cover success and error paths without real API calls (mock mode)\n- Agents work across multiple runtimes via adapters\n- Multi-agent pipelines compose via \`andThen()\` / \`match()\` helpers\n\n## Documentation Index\n\n- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`\n\n## Getting Help\n\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n\nHappy agent building!\n";
 
 export const fragments = {
   purposeForUsersNotContributors: {
     header: "## Purpose: For Users, Not Contributors",
-    body: "**Key distinction:**\n- **This skill** = How to USE VAT to build agents\n- **Root CLAUDE.md** = How to DEVELOP VAT itself\n\nThis skill focuses on agent authoring, not VAT codebase development.",
-    text: "## Purpose: For Users, Not Contributors\n\n**Key distinction:**\n- **This skill** = How to USE VAT to build agents\n- **Root CLAUDE.md** = How to DEVELOP VAT itself\n\nThis skill focuses on agent authoring, not VAT codebase development."
-  },
-  whatIsVat: {
-    header: "## What is VAT?",
-    body: "**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across multiple LLM frameworks and deployment targets.\n\n### What VAT IS\n\n- **Agent authoring framework** - Define agents once, run anywhere\n- **Multi-runtime support** - Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK\n- **Standardized patterns** - Consistent result envelopes, error handling, orchestration\n- **Type-safe** - Full TypeScript support with Zod schemas\n- **Framework agnostic** - Agents are plain functions, no vendor lock-in\n\n### What VAT IS NOT\n\n- **NOT a chat UI** - VAT provides the agent logic, not the interface\n- **NOT an LLM provider** - Bring your own API keys (OpenAI, Anthropic, etc.)\n- **NOT a deployment platform** - Deploy agents where you want (cloud, edge, local)\n- **NOT opinionated about domains** - Use for any domain (code analysis, data processing, customer service, etc.)\n\n### Core Value Proposition\n\n**Write Once, Run Anywhere**\n\n\`\`\`typescript\n// 1. Define agent once (plain TypeScript)\nexport async function analyzeSentiment(text: string) {\n  // Your logic here\n  return { sentiment: \'positive\', confidence: 0.9 };\n}\n\n// 2. Adapt to ANY runtime\n// Vercel AI SDK\nconst vercelTool = createVercelAISDKAdapter(analyzeSentiment);\n\n// LangChain\nconst langchainTool = createLangChainAdapter(analyzeSentiment);\n\n// OpenAI\nconst openaiTool = createOpenAIAdapter(analyzeSentiment);\n\n// Claude Agent SDK\nconst claudeTool = createClaudeAgentSDKAdapter(analyzeSentiment);\n\`\`\`\n\nNo framework-specific code in your agent. Runtime adapters handle the translation.",
-    text: "## What is VAT?\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across multiple LLM frameworks and deployment targets.\n\n### What VAT IS\n\n- **Agent authoring framework** - Define agents once, run anywhere\n- **Multi-runtime support** - Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK\n- **Standardized patterns** - Consistent result envelopes, error handling, orchestration\n- **Type-safe** - Full TypeScript support with Zod schemas\n- **Framework agnostic** - Agents are plain functions, no vendor lock-in\n\n### What VAT IS NOT\n\n- **NOT a chat UI** - VAT provides the agent logic, not the interface\n- **NOT an LLM provider** - Bring your own API keys (OpenAI, Anthropic, etc.)\n- **NOT a deployment platform** - Deploy agents where you want (cloud, edge, local)\n- **NOT opinionated about domains** - Use for any domain (code analysis, data processing, customer service, etc.)\n\n### Core Value Proposition\n\n**Write Once, Run Anywhere**\n\n\`\`\`typescript\n// 1. Define agent once (plain TypeScript)\nexport async function analyzeSentiment(text: string) {\n  // Your logic here\n  return { sentiment: \'positive\', confidence: 0.9 };\n}\n\n// 2. Adapt to ANY runtime\n// Vercel AI SDK\nconst vercelTool = createVercelAISDKAdapter(analyzeSentiment);\n\n// LangChain\nconst langchainTool = createLangChainAdapter(analyzeSentiment);\n\n// OpenAI\nconst openaiTool = createOpenAIAdapter(analyzeSentiment);\n\n// Claude Agent SDK\nconst claudeTool = createClaudeAgentSDKAdapter(analyzeSentiment);\n\`\`\`\n\nNo framework-specific code in your agent. Runtime adapters handle the translation."
+    body: "- **This skill** = How to USE VAT to build agents\n- **Root CLAUDE.md** = How to DEVELOP the VAT codebase itself",
+    text: "## Purpose: For Users, Not Contributors\n\n- **This skill** = How to USE VAT to build agents\n- **Root CLAUDE.md** = How to DEVELOP the VAT codebase itself"
   },
   whenToUseVat: {
     header: "## When to Use VAT",
-    body: "### VAT is Great For\n\n**✅ Multi-framework projects**\n- Team uses different LLM frameworks\n- Want flexibility to switch frameworks later\n- Building a platform that supports multiple frameworks\n\n**✅ Reusable agent libraries**\n- Creating internal agent packages\n- Open-source agent collections\n- Marketplace/plugin systems\n\n**✅ Testing and experimentation**\n- Compare LLM performance across providers\n- A/B test different frameworks\n- Validate agent logic without framework lock-in\n\n**✅ Complex orchestration**\n- Multi-agent workflows\n- Validation loops (generate → validate → retry)\n- Human-in-the-loop approval gates\n- Conversational multi-turn agents\n\n### VAT May NOT Be Needed For\n\n**❌ Simple one-off scripts**\n- Single-use agent, not reused\n- Framework is already decided\n- No portability required\n\n**❌ Framework-specific features**\n- Need deep integration with one framework\n- Using advanced framework-specific capabilities\n- Framework provides everything you need\n\n**❌ No TypeScript/JavaScript projects**\n- VAT is TypeScript-first\n- Other languages not currently supported",
-    text: "## When to Use VAT\n\n### VAT is Great For\n\n**✅ Multi-framework projects**\n- Team uses different LLM frameworks\n- Want flexibility to switch frameworks later\n- Building a platform that supports multiple frameworks\n\n**✅ Reusable agent libraries**\n- Creating internal agent packages\n- Open-source agent collections\n- Marketplace/plugin systems\n\n**✅ Testing and experimentation**\n- Compare LLM performance across providers\n- A/B test different frameworks\n- Validate agent logic without framework lock-in\n\n**✅ Complex orchestration**\n- Multi-agent workflows\n- Validation loops (generate → validate → retry)\n- Human-in-the-loop approval gates\n- Conversational multi-turn agents\n\n### VAT May NOT Be Needed For\n\n**❌ Simple one-off scripts**\n- Single-use agent, not reused\n- Framework is already decided\n- No portability required\n\n**❌ Framework-specific features**\n- Need deep integration with one framework\n- Using advanced framework-specific capabilities\n- Framework provides everything you need\n\n**❌ No TypeScript/JavaScript projects**\n- VAT is TypeScript-first\n- Other languages not currently supported"
-  },
-  creatingAgentsWithAgentGenerator: {
-    header: "## Creating Agents with agent-generator",
-    body: "The **agent-generator** is a meta-agent that helps you design high-quality agents through guided conversation.\n\n### What agent-generator Does\n\nAgent-generator guides you through a **4-phase workflow**:\n\n1. **GATHER** - Understand your intent and goals\n2. **ANALYZE** - Identify agent pattern and requirements\n3. **DESIGN** - Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** - Create validated agent package\n\n### How to Use agent-generator\n\n**Step 1: Provide Requirements**\n\nMinimum viable input:\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nOptional context (improves recommendations):\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\",\n  \"typicalInputs\": \"GitHub PR diff\",\n  \"expectedOutputs\": \"List of security issues with severity\",\n  \"performanceRequirements\": {\n    \"latency\": \"Under 30 seconds per PR\",\n    \"accuracy\": \"Zero false negatives on critical issues\",\n    \"cost\": \"Under $0.10 per PR\"\n  }\n}\n\`\`\`\n\n**Step 2: Conversational Refinement**\n\nAgent-generator asks follow-up questions:\n- What tools does the agent need? (file readers, APIs, etc.)\n- What domain knowledge is required?\n- What are edge cases to handle?\n- What\'s the input/output format?\n\n**Step 3: Architecture Recommendations**\n\nAgent-generator makes informed decisions:\n- **LLM selection** - Based on accuracy/speed/cost requirements\n- **Tool selection** - Minimizes count, justifies each\n- **Prompt strategy** - Context-efficient, high-signal\n- **Resource planning** - References, examples, schemas\n\n**Step 4: Generated Agent Package**\n\nOutput includes:\n- \`agent.yaml\` - Validated agent manifest\n- \`prompts/system.md\` - System prompt\n- \`prompts/user.md\` - User prompt template\n- \`schemas/input.schema.json\` - Input validation\n- \`schemas/output.schema.json\` - Output validation\n- \`README.md\` - Usage documentation\n\n**Step 5: Customize and Deploy**\n\n- Review generated prompts, adjust as needed\n- Test agent with sample inputs\n- Deploy using runtime adapters\n\n### agent-generator Best Practices\n\n**Be specific about success criteria:**\n\`\`\`\n❌ \"Make it work well\"\n✅ \"Catches 100% of SQL injection vulnerabilities\"\n\`\`\`\n\n**Provide performance requirements:**\n\`\`\`\n❌ \"Fast enough\"\n✅ \"Under 5 seconds per request, under $0.01 per call\"\n\`\`\`\n\n**Describe domain context:**\n\`\`\`\n❌ \"Security stuff\"\n✅ \"OWASP Top 10, CWE database, company coding standards\"\n\`\`\`\n\n**Identify tools early:**\n\`\`\`\n❌ \"Whatever it needs\"\n✅ \"File reader, GitHub API, static analysis tool\"\n\`\`\`\n\n### agent-generator Resources\n\nThe generator incorporates best practices from:\n- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)\n- [Effective Context Engineering - Anthropic](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)\n- [Agent System Design Patterns - Databricks](https://docs.databricks.com/aws/en/generative-ai/guide/agent-system-design-patterns)\n- [AI Agent Orchestration - Microsoft Azure](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)\n\n**Documentation:**\n- [agent-authoring.md](../../../../docs/agent-authoring.md) - Agent patterns and examples\n- [orchestration.md](../../../../docs/orchestration.md) - Multi-agent workflows",
-    text: "## Creating Agents with agent-generator\n\nThe **agent-generator** is a meta-agent that helps you design high-quality agents through guided conversation.\n\n### What agent-generator Does\n\nAgent-generator guides you through a **4-phase workflow**:\n\n1. **GATHER** - Understand your intent and goals\n2. **ANALYZE** - Identify agent pattern and requirements\n3. **DESIGN** - Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** - Create validated agent package\n\n### How to Use agent-generator\n\n**Step 1: Provide Requirements**\n\nMinimum viable input:\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nOptional context (improves recommendations):\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\",\n  \"typicalInputs\": \"GitHub PR diff\",\n  \"expectedOutputs\": \"List of security issues with severity\",\n  \"performanceRequirements\": {\n    \"latency\": \"Under 30 seconds per PR\",\n    \"accuracy\": \"Zero false negatives on critical issues\",\n    \"cost\": \"Under $0.10 per PR\"\n  }\n}\n\`\`\`\n\n**Step 2: Conversational Refinement**\n\nAgent-generator asks follow-up questions:\n- What tools does the agent need? (file readers, APIs, etc.)\n- What domain knowledge is required?\n- What are edge cases to handle?\n- What\'s the input/output format?\n\n**Step 3: Architecture Recommendations**\n\nAgent-generator makes informed decisions:\n- **LLM selection** - Based on accuracy/speed/cost requirements\n- **Tool selection** - Minimizes count, justifies each\n- **Prompt strategy** - Context-efficient, high-signal\n- **Resource planning** - References, examples, schemas\n\n**Step 4: Generated Agent Package**\n\nOutput includes:\n- \`agent.yaml\` - Validated agent manifest\n- \`prompts/system.md\` - System prompt\n- \`prompts/user.md\` - User prompt template\n- \`schemas/input.schema.json\` - Input validation\n- \`schemas/output.schema.json\` - Output validation\n- \`README.md\` - Usage documentation\n\n**Step 5: Customize and Deploy**\n\n- Review generated prompts, adjust as needed\n- Test agent with sample inputs\n- Deploy using runtime adapters\n\n### agent-generator Best Practices\n\n**Be specific about success criteria:**\n\`\`\`\n❌ \"Make it work well\"\n✅ \"Catches 100% of SQL injection vulnerabilities\"\n\`\`\`\n\n**Provide performance requirements:**\n\`\`\`\n❌ \"Fast enough\"\n✅ \"Under 5 seconds per request, under $0.01 per call\"\n\`\`\`\n\n**Describe domain context:**\n\`\`\`\n❌ \"Security stuff\"\n✅ \"OWASP Top 10, CWE database, company coding standards\"\n\`\`\`\n\n**Identify tools early:**\n\`\`\`\n❌ \"Whatever it needs\"\n✅ \"File reader, GitHub API, static analysis tool\"\n\`\`\`\n\n### agent-generator Resources\n\nThe generator incorporates best practices from:\n- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)\n- [Effective Context Engineering - Anthropic](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)\n- [Agent System Design Patterns - Databricks](https://docs.databricks.com/aws/en/generative-ai/guide/agent-system-design-patterns)\n- [AI Agent Orchestration - Microsoft Azure](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)\n\n**Documentation:**\n- [agent-authoring.md](../../../../docs/agent-authoring.md) - Agent patterns and examples\n- [orchestration.md](../../../../docs/orchestration.md) - Multi-agent workflows"
+    body: "**VAT is great for:** Multi-framework projects, reusable agent libraries, testing across LLM\nproviders, complex multi-agent orchestration, human-in-the-loop workflows.\n\n**VAT may not be needed for:** Simple one-off scripts where the framework is already decided,\nnon-TypeScript/JavaScript projects, or cases where you need deep framework-specific features.",
+    text: "## When to Use VAT\n\n**VAT is great for:** Multi-framework projects, reusable agent libraries, testing across LLM\nproviders, complex multi-agent orchestration, human-in-the-loop workflows.\n\n**VAT may not be needed for:** Simple one-off scripts where the framework is already decided,\nnon-TypeScript/JavaScript projects, or cases where you need deep framework-specific features."
   },
-  understandingAgentPatterns: {
-    header: "## Understanding Agent Patterns",
-    body: "VAT supports multiple agent patterns (archetypes) for different use cases.\n\n### Pattern 1: Pure Function Tool\n\n**When to use:** Stateless validation, transformation, computation\n\n**Characteristics:**\n- No LLM calls\n- Deterministic output\n- Fast execution\n- Easy to test\n\n**Example use cases:**\n- Input validation\n- Data transformation\n- Format conversion\n- Rules-based logic\n\n**Code pattern:**\n\`\`\`typescript\nexport async function validateInput(input: MyInput): Promise<ValidationResult> {\n  if (input.text.length < 5) {\n    return { status: \'error\', error: \'too-short\' };\n  }\n  return { status: \'success\', data: { valid: true } };\n}\n\`\`\`\n\n### Pattern 2: One-Shot LLM Analyzer\n\n**When to use:** Single LLM call for analysis, classification, generation\n\n**Characteristics:**\n- One LLM call per execution\n- Stateless\n- Handles LLM errors\n- Parses and validates output\n\n**Example use cases:**\n- Sentiment analysis\n- Text classification\n- Entity extraction\n- Creative generation\n\n**Code pattern:**\n\`\`\`typescript\nexport async function analyzeSentiment(text: string, context: AgentContext) {\n  const response = await context.callLLM([\n    { role: \'user\', content: \`Analyze sentiment: \"${text}\"\` }\n  ]);\n\n  const parsed = JSON.parse(response);\n  return { status: \'success\', data: parsed };\n}\n\`\`\`\n\n### Pattern 3: Conversational Assistant\n\n**When to use:** Multi-turn dialogue, progressive data collection\n\n**Characteristics:**\n- Multiple LLM calls across turns\n- Maintains session state\n- Phases (gathering → ready → complete)\n- Natural language replies + machine-readable results\n\n**Example use cases:**\n- Customer support chatbots\n- Product advisors\n- Interview/survey agents\n- Multi-step form filling\n\n**Code pattern:**\n\`\`\`typescript\nexport async function conversationalAgent(\n  message: string,\n  sessionState: SessionState\n) {\n  if (sessionState.phase === \'gathering\') {\n    // Collect more info\n    return {\n      reply: \"Can you tell me more about X?\",\n      sessionState: { ...sessionState },\n      result: { status: \'in-progress\' }\n    };\n  }\n\n  // Ready to complete\n  return {\n    reply: \"Here\'s your result!\",\n    sessionState: { ...sessionState, phase: \'complete\' },\n    result: { status: \'success\', data: finalResult }\n  };\n}\n\`\`\`\n\n### Pattern 4: External Event Integrator\n\n**When to use:** Waiting for external events (approvals, webhooks)\n\n**Characteristics:**\n- Emits event, blocks waiting for response\n- Timeout handling\n- External system unavailability\n- Can be mocked for testing\n\n**Example use cases:**\n- Human-in-the-loop approval\n- Webhook integrations\n- External API polling\n- Third-party service calls\n\n**Code pattern:**\n\`\`\`typescript\nexport async function humanApproval(\n  request: ApprovalRequest,\n  options = { mockable: true, timeout: 30000 }\n) {\n  if (options.mockable) {\n    // Mock mode for testing\n    return { status: \'success\', data: { approved: true } };\n  }\n\n  // Real mode - emit event and wait\n  const response = await emitEvent(request, options.timeout);\n  return { status: \'success\', data: response };\n}\n\`\`\`\n\n**See also:**\n- [agent-authoring.md](../../../../docs/agent-authoring.md) - Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) - Chaining and workflows",
-    text: "## Understanding Agent Patterns\n\nVAT supports multiple agent patterns (archetypes) for different use cases.\n\n### Pattern 1: Pure Function Tool\n\n**When to use:** Stateless validation, transformation, computation\n\n**Characteristics:**\n- No LLM calls\n- Deterministic output\n- Fast execution\n- Easy to test\n\n**Example use cases:**\n- Input validation\n- Data transformation\n- Format conversion\n- Rules-based logic\n\n**Code pattern:**\n\`\`\`typescript\nexport async function validateInput(input: MyInput): Promise<ValidationResult> {\n  if (input.text.length < 5) {\n    return { status: \'error\', error: \'too-short\' };\n  }\n  return { status: \'success\', data: { valid: true } };\n}\n\`\`\`\n\n### Pattern 2: One-Shot LLM Analyzer\n\n**When to use:** Single LLM call for analysis, classification, generation\n\n**Characteristics:**\n- One LLM call per execution\n- Stateless\n- Handles LLM errors\n- Parses and validates output\n\n**Example use cases:**\n- Sentiment analysis\n- Text classification\n- Entity extraction\n- Creative generation\n\n**Code pattern:**\n\`\`\`typescript\nexport async function analyzeSentiment(text: string, context: AgentContext) {\n  const response = await context.callLLM([\n    { role: \'user\', content: \`Analyze sentiment: \"${text}\"\` }\n  ]);\n\n  const parsed = JSON.parse(response);\n  return { status: \'success\', data: parsed };\n}\n\`\`\`\n\n### Pattern 3: Conversational Assistant\n\n**When to use:** Multi-turn dialogue, progressive data collection\n\n**Characteristics:**\n- Multiple LLM calls across turns\n- Maintains session state\n- Phases (gathering → ready → complete)\n- Natural language replies + machine-readable results\n\n**Example use cases:**\n- Customer support chatbots\n- Product advisors\n- Interview/survey agents\n- Multi-step form filling\n\n**Code pattern:**\n\`\`\`typescript\nexport async function conversationalAgent(\n  message: string,\n  sessionState: SessionState\n) {\n  if (sessionState.phase === \'gathering\') {\n    // Collect more info\n    return {\n      reply: \"Can you tell me more about X?\",\n      sessionState: { ...sessionState },\n      result: { status: \'in-progress\' }\n    };\n  }\n\n  // Ready to complete\n  return {\n    reply: \"Here\'s your result!\",\n    sessionState: { ...sessionState, phase: \'complete\' },\n    result: { status: \'success\', data: finalResult }\n  };\n}\n\`\`\`\n\n### Pattern 4: External Event Integrator\n\n**When to use:** Waiting for external events (approvals, webhooks)\n\n**Characteristics:**\n- Emits event, blocks waiting for response\n- Timeout handling\n- External system unavailability\n- Can be mocked for testing\n\n**Example use cases:**\n- Human-in-the-loop approval\n- Webhook integrations\n- External API polling\n- Third-party service calls\n\n**Code pattern:**\n\`\`\`typescript\nexport async function humanApproval(\n  request: ApprovalRequest,\n  options = { mockable: true, timeout: 30000 }\n) {\n  if (options.mockable) {\n    // Mock mode for testing\n    return { status: \'success\', data: { approved: true } };\n  }\n\n  // Real mode - emit event and wait\n  const response = await emitEvent(request, options.timeout);\n  return { status: \'success\', data: response };\n}\n\`\`\`\n\n**See also:**\n- [agent-authoring.md](../../../../docs/agent-authoring.md) - Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) - Chaining and workflows"
+  skillRoutingTable: {
+    header: "## Skill Routing Table",
+    body: "| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:agent-authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:agent-authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:agent-authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Packaging skills, \`--target claude-web\`, ZIP format | \`vibe-agent-toolkit:distribution\` |\n| Sideloading with \`vat install\`, npm postinstall hooks | \`vibe-agent-toolkit:distribution\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |",
+    text: "## Skill Routing Table\n\n| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:agent-authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:agent-authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:agent-authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Packaging skills, \`--target claude-web\`, ZIP format | \`vibe-agent-toolkit:distribution\` |\n| Sideloading with \`vat install\`, npm postinstall hooks | \`vibe-agent-toolkit:distribution\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |"
   },
-  vatCliWorkflows: {
-    header: "## VAT CLI Workflows",
-    body: "The VAT CLI (\`vat\`) provides commands for working with agents, skills, and resources.\n\n### Installation\n\n\`\`\`bash\n# Global installation (recommended)\nnpm install -g vibe-agent-toolkit\n\n# Or install just the CLI\nnpm install -g @vibe-agent-toolkit/cli\n\n# Verify installation\nvat --version\n\`\`\`\n\n### Skills Commands\n\n**List available skills:**\n\`\`\`bash\n# Scan for SKILL.md files in current directory\nvat skills list\n\n# Show user-installed skills (~/.claude/plugins)\nvat skills list --user\n\`\`\`\n\n**Install skills:**\n\`\`\`bash\n# From npm package\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\n\n# From local directory\nvat skills install ./my-skills\n\n# From zip file\nvat skills install ./skills.zip\n\`\`\`\n\n**Validate skill quality:**\n\`\`\`bash\n# Validate all skills declared in package.json vat.skills\nvat skills validate\n\n# Validate a specific skill by name\nvat skills validate --skill my-skill\n\n# Show verbose output (excluded reference details)\nvat skills validate --verbose\n\`\`\`\n\n**Build skills for distribution:**\n\`\`\`bash\n# Build all skills in package\nvat skills build\n\n# Build specific skill\nvat skills build --skill my-skill\n\n# Dry-run (preview)\nvat skills build --dry-run\n\`\`\`\n\n### Packaging Options\n\nConfigure \`packagingOptions\` in your skill\'s \`vat.skills[]\` entry in package.json:\n\n\`\`\`json\n{\n  \"vat\": {\n    \"skills\": [{\n      \"name\": \"my-skill\",\n      \"source\": \"./SKILL.md\",\n      \"path\": \"./dist/skills/my-skill\",\n      \"packagingOptions\": {\n        \"linkFollowDepth\": 1,\n        \"resourceNaming\": \"resource-id\",\n        \"stripPrefix\": \"knowledge-base\",\n        \"excludeReferencesFromBundle\": {\n          \"rules\": [\n            { \"patterns\": [\"**/concepts/**\"], \"template\": \"Use search to find: {{link.text}}\" }\n          ],\n          \"defaultTemplate\": \"{{link.text}} (search knowledge base)\"\n        }\n      }\n    }]\n  }\n}\n\`\`\`\n\n**\`linkFollowDepth\`** — Controls how deep links are followed from SKILL.md:\n\n| Value | Behavior |\n|-------|----------|\n| \`0\` | Skill file only (no links followed) |\n| \`1\` | Direct links only |\n| \`2\` | Direct + one transitive level **(default)** |\n| \`N\` | N levels of transitive links |\n| \`\"full\"\` | Complete transitive closure |\n\n**\`resourceNaming\`** — How bundled files are named in output:\n\n| Strategy | Example Output | Use When |\n|----------|---------------|----------|\n| \`basename\` | \`overview.md\` | Few files, unique names **(default)** |\n| \`resource-id\` | \`topics-quickstart-overview.md\` | Many files, flat output needed |\n| \`preserve-path\` | \`topics/quickstart/overview.md\` | Preserve original structure |\n\nUse \`stripPrefix\` to remove a common directory prefix (e.g., \`\"knowledge-base\"\`).\n\n**\`excludeReferencesFromBundle\`** — Rules for excluding files and rewriting their links:\n\n- \`rules[]\` — Ordered glob patterns (first match wins), each with optional Handlebars template\n- \`defaultTemplate\` — Applied to depth-exceeded links not matching any rule\n\n**Template variables:**\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| \`{{link.text}}\` | Link display text | \`\"Setup Guide\"\` |\n| \`{{link.uri}}\` | Original href | \`\"./docs/setup.md\"\` |\n| \`{{link.fileName}}\` | Target filename | \`\"setup.md\"\` |\n| \`{{link.filePath}}\` | Path relative to skill root | \`\"docs/setup.md\"\` |\n| \`{{skill.name}}\` | Skill name from frontmatter | \`\"my-skill\"\` |\n\n**\`ignoreValidationErrors\`** — Override validation rules:\n\n\`\`\`json\n\"ignoreValidationErrors\": {\n  \"SKILL_LENGTH_EXCEEDS_RECOMMENDED\": \"Large domain requires detailed examples\",\n  \"NO_PROGRESSIVE_DISCLOSURE\": {\n    \"reason\": \"Temporary — refactoring planned\",\n    \"expires\": \"2026-06-30\"\n  }\n}\n\`\`\`\n\n### Agent Commands\n\n**Import Claude Skills to VAT format:**\n\`\`\`bash\n# Import skill to agent.yaml\nvat agent import my-skill/SKILL.md\n\n# Custom output path\nvat agent import my-skill/SKILL.md --output my-agent/agent.yaml\n\n# Force overwrite\nvat agent import my-skill/SKILL.md --force\n\`\`\`\n\n**Audit agent/skill quality:**\n\`\`\`bash\n# Audit single file\nvat agent audit my-agent/agent.yaml\n\n# Audit directory recursively\nvat agent audit agents/ --recursive\n\n# Detailed validation errors\nvat agent audit my-agent/agent.yaml --debug\n\`\`\`\n\nThe audit checks for:\n- Required frontmatter fields\n- Naming conventions\n- Description length limits\n- Link integrity\n- Console tool availability\n\n### RAG Commands\n\n**Index documentation into a vector database:**\n\`\`\`bash\n# Index all markdown files in docs/\nvat rag index docs/\n\n# Index with specific database path\nvat rag index docs/ --db ./dist/rag-db\n\`\`\`\n\n**Search indexed documentation:**\n\`\`\`bash\n# Semantic search\nvat rag query \"How do I configure authentication?\"\n\n# Limit results\nvat rag query \"error handling\" --limit 5\n\n# Query specific database\nvat rag query \"setup guide\" --db ./dist/rag-db\n\`\`\`\n\n**Manage the database:**\n\`\`\`bash\n# View database statistics\nvat rag stats\n\n# Clear and rebuild\nvat rag clear\nvat rag index docs/\n\`\`\`\n\n### Resources Commands\n\n**Validate markdown resources:**\n\`\`\`bash\n# Validate directory\nvat resources validate docs/\n\n# With frontmatter schema validation\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Strict mode (warnings become errors)\nvat resources validate docs/ --strict\n\`\`\`\n\n**Parse and extract resource metadata:**\n\`\`\`bash\n# Parse directory and output JSON\nvat resources parse docs/ --output resources.json\n\n# Parse with link resolution\nvat resources parse docs/ --resolve-links\n\`\`\`\n\n### Common Workflows\n\n**Workflow 1: Create New Agent**\n\`\`\`bash\n# 1. Use agent-generator (interactive)\n# Follow prompts to define your agent\n\n# 2. Review generated files\ncat my-agent/agent.yaml\ncat my-agent/prompts/system.md\n\n# 3. Test agent\ncd my-agent\nvat test\n\n# 4. Package for distribution\nvat package\n\`\`\`\n\n**Workflow 2: Install and Use Skills**\n\`\`\`bash\n# 1. Install skill from npm\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\n\n# 2. List installed skills\nvat skills list --user\n\n# 3. Use in Claude Code\n# Skills appear in ~/.claude/plugins/\n# Claude Code auto-loads them\n\`\`\`\n\n**Workflow 3: Validate and Audit**\n\`\`\`bash\n# 1. Create/edit skill\nvim my-skill/SKILL.md\n\n# 2. Validate before import\nvat skills validate my-skill/SKILL.md\n\n# 3. Audit for quality issues\nvat agent audit my-skill/SKILL.md\n\n# 4. Import to VAT format\nvat agent import my-skill/SKILL.md\n\`\`\`\n\n**Workflow 4: Build and Distribute**\n\`\`\`bash\n# 1. Add vat.skills to package.json\n# (See distribution standard docs)\n\n# 2. Build skills\nbun run build  # Includes vat skills build\n\n# 3. Test locally\nvat skills install ./packages/my-skills\n\n# 4. Publish to npm\nnpm publish\n\n# 5. Install from npm\nvat skills install npm:@my-org/my-skills\n\`\`\`\n\n### CLI Tips\n\n**Use --help for any command:**\n\`\`\`bash\nvat --help\nvat skills --help\nvat skills install --help\n\`\`\`\n\n**Use --dry-run for preview:**\n\`\`\`bash\nvat skills build --dry-run\nvat skills install my-skill --dry-run\n\`\`\`\n\n**Use --debug for troubleshooting:**\n\`\`\`bash\nvat skills validate my-skill --debug\nvat agent audit my-agent --debug\n\`\`\`\n\n**Check skill installation location:**\n\`\`\`bash\n# User skills\nls ~/.claude/plugins/\n\n# Project skills\nls .claude/skills/\n\`\`\`",
-    text: "## VAT CLI Workflows\n\nThe VAT CLI (\`vat\`) provides commands for working with agents, skills, and resources.\n\n### Installation\n\n\`\`\`bash\n# Global installation (recommended)\nnpm install -g vibe-agent-toolkit\n\n# Or install just the CLI\nnpm install -g @vibe-agent-toolkit/cli\n\n# Verify installation\nvat --version\n\`\`\`\n\n### Skills Commands\n\n**List available skills:**\n\`\`\`bash\n# Scan for SKILL.md files in current directory\nvat skills list\n\n# Show user-installed skills (~/.claude/plugins)\nvat skills list --user\n\`\`\`\n\n**Install skills:**\n\`\`\`bash\n# From npm package\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\n\n# From local directory\nvat skills install ./my-skills\n\n# From zip file\nvat skills install ./skills.zip\n\`\`\`\n\n**Validate skill quality:**\n\`\`\`bash\n# Validate all skills declared in package.json vat.skills\nvat skills validate\n\n# Validate a specific skill by name\nvat skills validate --skill my-skill\n\n# Show verbose output (excluded reference details)\nvat skills validate --verbose\n\`\`\`\n\n**Build skills for distribution:**\n\`\`\`bash\n# Build all skills in package\nvat skills build\n\n# Build specific skill\nvat skills build --skill my-skill\n\n# Dry-run (preview)\nvat skills build --dry-run\n\`\`\`\n\n### Packaging Options\n\nConfigure \`packagingOptions\` in your skill\'s \`vat.skills[]\` entry in package.json:\n\n\`\`\`json\n{\n  \"vat\": {\n    \"skills\": [{\n      \"name\": \"my-skill\",\n      \"source\": \"./SKILL.md\",\n      \"path\": \"./dist/skills/my-skill\",\n      \"packagingOptions\": {\n        \"linkFollowDepth\": 1,\n        \"resourceNaming\": \"resource-id\",\n        \"stripPrefix\": \"knowledge-base\",\n        \"excludeReferencesFromBundle\": {\n          \"rules\": [\n            { \"patterns\": [\"**/concepts/**\"], \"template\": \"Use search to find: {{link.text}}\" }\n          ],\n          \"defaultTemplate\": \"{{link.text}} (search knowledge base)\"\n        }\n      }\n    }]\n  }\n}\n\`\`\`\n\n**\`linkFollowDepth\`** — Controls how deep links are followed from SKILL.md:\n\n| Value | Behavior |\n|-------|----------|\n| \`0\` | Skill file only (no links followed) |\n| \`1\` | Direct links only |\n| \`2\` | Direct + one transitive level **(default)** |\n| \`N\` | N levels of transitive links |\n| \`\"full\"\` | Complete transitive closure |\n\n**\`resourceNaming\`** — How bundled files are named in output:\n\n| Strategy | Example Output | Use When |\n|----------|---------------|----------|\n| \`basename\` | \`overview.md\` | Few files, unique names **(default)** |\n| \`resource-id\` | \`topics-quickstart-overview.md\` | Many files, flat output needed |\n| \`preserve-path\` | \`topics/quickstart/overview.md\` | Preserve original structure |\n\nUse \`stripPrefix\` to remove a common directory prefix (e.g., \`\"knowledge-base\"\`).\n\n**\`excludeReferencesFromBundle\`** — Rules for excluding files and rewriting their links:\n\n- \`rules[]\` — Ordered glob patterns (first match wins), each with optional Handlebars template\n- \`defaultTemplate\` — Applied to depth-exceeded links not matching any rule\n\n**Template variables:**\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| \`{{link.text}}\` | Link display text | \`\"Setup Guide\"\` |\n| \`{{link.uri}}\` | Original href | \`\"./docs/setup.md\"\` |\n| \`{{link.fileName}}\` | Target filename | \`\"setup.md\"\` |\n| \`{{link.filePath}}\` | Path relative to skill root | \`\"docs/setup.md\"\` |\n| \`{{skill.name}}\` | Skill name from frontmatter | \`\"my-skill\"\` |\n\n**\`ignoreValidationErrors\`** — Override validation rules:\n\n\`\`\`json\n\"ignoreValidationErrors\": {\n  \"SKILL_LENGTH_EXCEEDS_RECOMMENDED\": \"Large domain requires detailed examples\",\n  \"NO_PROGRESSIVE_DISCLOSURE\": {\n    \"reason\": \"Temporary — refactoring planned\",\n    \"expires\": \"2026-06-30\"\n  }\n}\n\`\`\`\n\n### Agent Commands\n\n**Import Claude Skills to VAT format:**\n\`\`\`bash\n# Import skill to agent.yaml\nvat agent import my-skill/SKILL.md\n\n# Custom output path\nvat agent import my-skill/SKILL.md --output my-agent/agent.yaml\n\n# Force overwrite\nvat agent import my-skill/SKILL.md --force\n\`\`\`\n\n**Audit agent/skill quality:**\n\`\`\`bash\n# Audit single file\nvat agent audit my-agent/agent.yaml\n\n# Audit directory recursively\nvat agent audit agents/ --recursive\n\n# Detailed validation errors\nvat agent audit my-agent/agent.yaml --debug\n\`\`\`\n\nThe audit checks for:\n- Required frontmatter fields\n- Naming conventions\n- Description length limits\n- Link integrity\n- Console tool availability\n\n### RAG Commands\n\n**Index documentation into a vector database:**\n\`\`\`bash\n# Index all markdown files in docs/\nvat rag index docs/\n\n# Index with specific database path\nvat rag index docs/ --db ./dist/rag-db\n\`\`\`\n\n**Search indexed documentation:**\n\`\`\`bash\n# Semantic search\nvat rag query \"How do I configure authentication?\"\n\n# Limit results\nvat rag query \"error handling\" --limit 5\n\n# Query specific database\nvat rag query \"setup guide\" --db ./dist/rag-db\n\`\`\`\n\n**Manage the database:**\n\`\`\`bash\n# View database statistics\nvat rag stats\n\n# Clear and rebuild\nvat rag clear\nvat rag index docs/\n\`\`\`\n\n### Resources Commands\n\n**Validate markdown resources:**\n\`\`\`bash\n# Validate directory\nvat resources validate docs/\n\n# With frontmatter schema validation\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Strict mode (warnings become errors)\nvat resources validate docs/ --strict\n\`\`\`\n\n**Parse and extract resource metadata:**\n\`\`\`bash\n# Parse directory and output JSON\nvat resources parse docs/ --output resources.json\n\n# Parse with link resolution\nvat resources parse docs/ --resolve-links\n\`\`\`\n\n### Common Workflows\n\n**Workflow 1: Create New Agent**\n\`\`\`bash\n# 1. Use agent-generator (interactive)\n# Follow prompts to define your agent\n\n# 2. Review generated files\ncat my-agent/agent.yaml\ncat my-agent/prompts/system.md\n\n# 3. Test agent\ncd my-agent\nvat test\n\n# 4. Package for distribution\nvat package\n\`\`\`\n\n**Workflow 2: Install and Use Skills**\n\`\`\`bash\n# 1. Install skill from npm\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\n\n# 2. List installed skills\nvat skills list --user\n\n# 3. Use in Claude Code\n# Skills appear in ~/.claude/plugins/\n# Claude Code auto-loads them\n\`\`\`\n\n**Workflow 3: Validate and Audit**\n\`\`\`bash\n# 1. Create/edit skill\nvim my-skill/SKILL.md\n\n# 2. Validate before import\nvat skills validate my-skill/SKILL.md\n\n# 3. Audit for quality issues\nvat agent audit my-skill/SKILL.md\n\n# 4. Import to VAT format\nvat agent import my-skill/SKILL.md\n\`\`\`\n\n**Workflow 4: Build and Distribute**\n\`\`\`bash\n# 1. Add vat.skills to package.json\n# (See distribution standard docs)\n\n# 2. Build skills\nbun run build  # Includes vat skills build\n\n# 3. Test locally\nvat skills install ./packages/my-skills\n\n# 4. Publish to npm\nnpm publish\n\n# 5. Install from npm\nvat skills install npm:@my-org/my-skills\n\`\`\`\n\n### CLI Tips\n\n**Use --help for any command:**\n\`\`\`bash\nvat --help\nvat skills --help\nvat skills install --help\n\`\`\`\n\n**Use --dry-run for preview:**\n\`\`\`bash\nvat skills build --dry-run\nvat skills install my-skill --dry-run\n\`\`\`\n\n**Use --debug for troubleshooting:**\n\`\`\`bash\nvat skills validate my-skill --debug\nvat agent audit my-agent --debug\n\`\`\`\n\n**Check skill installation location:**\n\`\`\`bash\n# User skills\nls ~/.claude/plugins/\n\n# Project skills\nls .claude/skills/\n\`\`\`"
+  agentArchetypesQuickReference: {
+    header: "## Agent Archetypes (Quick Reference)",
+    body: "Four patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:agent-authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |",
+    text: "## Agent Archetypes (Quick Reference)\n\nFour patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:agent-authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |"
   },
-  resultEnvelopesAndErrorHandling: {
-    header: "## Result Envelopes and Error Handling",
-    body: "VAT uses standardized result envelopes for type-safe composition and error handling.\n\n### Core Result Types\n\n**AgentResult<TData, TError>** - For single-execution agents:\n\`\`\`typescript\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\n**StatefulAgentResult<TData, TError, TMetadata>** - For conversational agents:\n\`\`\`typescript\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\n### Standard Error Types\n\n**LLM errors:**\n\`\`\`typescript\ntype LLMError =\n  | \'llm-refusal\'          // LLM refused to generate\n  | \'llm-invalid-output\'   // Output format incorrect\n  | \'llm-timeout\'          // Request timed out\n  | \'llm-rate-limit\'       // Hit rate limit\n  | \'llm-token-limit\'      // Exceeded token limit\n  | \'llm-unavailable\';     // Service unavailable\n\`\`\`\n\n**Event integration errors:**\n\`\`\`typescript\ntype ExternalEventError =\n  | \'event-timeout\'           // External event timed out\n  | \'event-unavailable\'       // System unavailable\n  | \'event-rejected\'          // Request rejected\n  | \'event-invalid-response\'; // Invalid response\n\`\`\`\n\n### Error Handling Pattern\n\nAlways check status before accessing data:\n\n\`\`\`typescript\nconst output = await myAgent.execute(input);\n\nif (output.result.status === \'success\') {\n  // Type-safe access to data\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  // Type-safe access to error\n  console.error(\'Failed:\', output.result.error);\n} else {\n  // In-progress (conversational agents)\n  console.log(\'Still working:\', output.result.metadata);\n}\n\`\`\`\n\n### Result Helpers\n\nVAT provides helpers for working with results:\n\n**mapResult()** - Transform success data:\n\`\`\`typescript\nimport { mapResult } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst result = { status: \'success\', data: 10 };\nconst doubled = mapResult(result, (n) => n * 2);\n// doubled = { status: \'success\', data: 20 }\n\`\`\`\n\n**andThen()** - Chain operations:\n\`\`\`typescript\nimport { andThen } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst output1 = await agent1.execute(input);\nconst output2 = await andThen(output1.result, async (data) => {\n  const out = await agent2.execute(data);\n  return out.result;\n});\n\`\`\`\n\n**match()** - Pattern match on status:\n\`\`\`typescript\nimport { match } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst message = match(result, {\n  success: (data) => \`Success: ${data}\`,\n  error: (err) => \`Error: ${err}\`,\n  inProgress: (meta) => \`Working: ${meta.step}\`,\n});\n\`\`\`\n\n**See also:** [orchestration.md](../../../../docs/orchestration.md) for composition patterns",
-    text: "## Result Envelopes and Error Handling\n\nVAT uses standardized result envelopes for type-safe composition and error handling.\n\n### Core Result Types\n\n**AgentResult<TData, TError>** - For single-execution agents:\n\`\`\`typescript\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\n**StatefulAgentResult<TData, TError, TMetadata>** - For conversational agents:\n\`\`\`typescript\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\n### Standard Error Types\n\n**LLM errors:**\n\`\`\`typescript\ntype LLMError =\n  | \'llm-refusal\'          // LLM refused to generate\n  | \'llm-invalid-output\'   // Output format incorrect\n  | \'llm-timeout\'          // Request timed out\n  | \'llm-rate-limit\'       // Hit rate limit\n  | \'llm-token-limit\'      // Exceeded token limit\n  | \'llm-unavailable\';     // Service unavailable\n\`\`\`\n\n**Event integration errors:**\n\`\`\`typescript\ntype ExternalEventError =\n  | \'event-timeout\'           // External event timed out\n  | \'event-unavailable\'       // System unavailable\n  | \'event-rejected\'          // Request rejected\n  | \'event-invalid-response\'; // Invalid response\n\`\`\`\n\n### Error Handling Pattern\n\nAlways check status before accessing data:\n\n\`\`\`typescript\nconst output = await myAgent.execute(input);\n\nif (output.result.status === \'success\') {\n  // Type-safe access to data\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  // Type-safe access to error\n  console.error(\'Failed:\', output.result.error);\n} else {\n  // In-progress (conversational agents)\n  console.log(\'Still working:\', output.result.metadata);\n}\n\`\`\`\n\n### Result Helpers\n\nVAT provides helpers for working with results:\n\n**mapResult()** - Transform success data:\n\`\`\`typescript\nimport { mapResult } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst result = { status: \'success\', data: 10 };\nconst doubled = mapResult(result, (n) => n * 2);\n// doubled = { status: \'success\', data: 20 }\n\`\`\`\n\n**andThen()** - Chain operations:\n\`\`\`typescript\nimport { andThen } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst output1 = await agent1.execute(input);\nconst output2 = await andThen(output1.result, async (data) => {\n  const out = await agent2.execute(data);\n  return out.result;\n});\n\`\`\`\n\n**match()** - Pattern match on status:\n\`\`\`typescript\nimport { match } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst message = match(result, {\n  success: (data) => \`Success: ${data}\`,\n  error: (err) => \`Error: ${err}\`,\n  inProgress: (meta) => \`Working: ${meta.step}\`,\n});\n\`\`\`\n\n**See also:** [orchestration.md](../../../../docs/orchestration.md) for composition patterns"
+  coreCliCommands: {
+    header: "## Core CLI Commands",
+    body: "\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Skills\nvat skills list                          # list skills in current project\nvat skills list --user                   # list user-installed skills\nvat skills install npm:@org/my-skills    # install from npm\nvat skills build                         # build skills for distribution\nvat skills validate                      # validate skill quality\n\n# Resources\nvat resources validate                   # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit                                # audit current directory recursively\nvat audit --user                         # audit entire Claude installation\nvat audit ./plugins/ --compat            # check surface compatibility\n\n# RAG\nvat rag index docs/                      # index markdown into vector DB\nvat rag query \"my question\" --limit 5    # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`",
+    text: "## Core CLI Commands\n\n\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Skills\nvat skills list                          # list skills in current project\nvat skills list --user                   # list user-installed skills\nvat skills install npm:@org/my-skills    # install from npm\nvat skills build                         # build skills for distribution\nvat skills validate                      # validate skill quality\n\n# Resources\nvat resources validate                   # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit                                # audit current directory recursively\nvat audit --user                         # audit entire Claude installation\nvat audit ./plugins/ --compat            # check surface compatibility\n\n# RAG\nvat rag index docs/                      # index markdown into vector DB\nvat rag query \"my question\" --limit 5    # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`"
   },
-  orchestrationPatterns: {
-    header: "## Orchestration Patterns",
-    body: "Combine agents into workflows using standardized result envelopes.\n\n### Sequential Pipeline\n\nExecute agents in order, passing results forward:\n\n\`\`\`typescript\n// Step 1: Analyze\nconst analysisOutput = await analyzer.execute(input);\n\n// Step 2: Process (only if step 1 succeeded)\nconst processedOutput = await andThen(\n  analysisOutput.result,\n  async (data) => {\n    const out = await processor.execute(data);\n    return out.result;\n  }\n);\n\n// Step 3: Validate (only if step 2 succeeded)\nconst finalOutput = await andThen(\n  processedOutput,\n  async (data) => {\n    const out = await validator.execute(data);\n    return out.result;\n  }\n);\n\`\`\`\n\n### Parallel Execution\n\nRun multiple agents concurrently:\n\n\`\`\`typescript\n// Execute in parallel\nconst [output1, output2, output3] = await Promise.all([\n  agent1.execute(input),\n  agent2.execute(input),\n  agent3.execute(input),\n]);\n\n// Combine results\nif (output1.result.status === \'success\' &&\n    output2.result.status === \'success\' &&\n    output3.result.status === \'success\') {\n  // All succeeded\n  const combined = combineResults(\n    output1.result.data,\n    output2.result.data,\n    output3.result.data\n  );\n}\n\`\`\`\n\n### Validation Loop\n\nGenerator + Validator with retry:\n\n\`\`\`typescript\nasync function generateValidOutput(\n  input: MyInput,\n  maxAttempts: number = 5\n) {\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    // Generate\n    const generatorOutput = await generator.execute(input);\n    if (generatorOutput.result.status === \'error\') continue;\n\n    // Validate\n    const validatorOutput = await validator.execute(\n      generatorOutput.result.data\n    );\n\n    if (validatorOutput.result.status === \'success\' &&\n        validatorOutput.result.data.valid) {\n      // Found valid output!\n      return generatorOutput.result.data;\n    }\n\n    // Invalid, retry with feedback\n    console.log(\'Attempt\', attempt + 1, \'invalid:\',\n      validatorOutput.result.data.reason);\n  }\n\n  throw new Error(\'Max attempts exceeded\');\n}\n\`\`\`\n\n### Human-in-the-Loop\n\nIntegrate human approval:\n\n\`\`\`typescript\n// Generate content\nconst generatorOutput = await generator.execute(input);\n\nif (generatorOutput.result.status === \'success\') {\n  // Request approval\n  const approvalOutput = await humanApproval.execute({\n    content: generatorOutput.result.data,\n    context: input,\n  });\n\n  if (approvalOutput.result.status === \'success\' &&\n      approvalOutput.result.data.approved) {\n    // Approved - continue\n    return generatorOutput.result.data;\n  } else {\n    // Rejected - handle feedback\n    console.log(\'Rejected:\', approvalOutput.result.data.feedback);\n  }\n}\n\`\`\`\n\n### Conversational Multi-Turn\n\nHandle stateful conversations:\n\n\`\`\`typescript\nlet session = {\n  state: { phase: \'gathering\' },\n  history: [],\n};\n\nwhile (true) {\n  const userMessage = await getUserInput();\n\n  const output = await conversationalAgent.execute({\n    message: userMessage,\n    sessionState: session.state,\n  });\n\n  console.log(\'Agent:\', output.reply);\n\n  // Update session\n  session = {\n    state: output.sessionState,\n    history: [\n      ...session.history,\n      { role: \'user\', content: userMessage },\n      { role: \'assistant\', content: output.reply },\n    ],\n  };\n\n  // Check completion\n  if (output.result.status === \'success\') {\n    console.log(\'Final result:\', output.result.data);\n    break;\n  } else if (output.result.status === \'error\') {\n    console.error(\'Failed:\', output.result.error);\n    break;\n  }\n  // Otherwise status === \'in-progress\', continue\n}\n\`\`\`\n\n**See also:** [orchestration.md](../../../../docs/orchestration.md) for complete guide",
-    text: "## Orchestration Patterns\n\nCombine agents into workflows using standardized result envelopes.\n\n### Sequential Pipeline\n\nExecute agents in order, passing results forward:\n\n\`\`\`typescript\n// Step 1: Analyze\nconst analysisOutput = await analyzer.execute(input);\n\n// Step 2: Process (only if step 1 succeeded)\nconst processedOutput = await andThen(\n  analysisOutput.result,\n  async (data) => {\n    const out = await processor.execute(data);\n    return out.result;\n  }\n);\n\n// Step 3: Validate (only if step 2 succeeded)\nconst finalOutput = await andThen(\n  processedOutput,\n  async (data) => {\n    const out = await validator.execute(data);\n    return out.result;\n  }\n);\n\`\`\`\n\n### Parallel Execution\n\nRun multiple agents concurrently:\n\n\`\`\`typescript\n// Execute in parallel\nconst [output1, output2, output3] = await Promise.all([\n  agent1.execute(input),\n  agent2.execute(input),\n  agent3.execute(input),\n]);\n\n// Combine results\nif (output1.result.status === \'success\' &&\n    output2.result.status === \'success\' &&\n    output3.result.status === \'success\') {\n  // All succeeded\n  const combined = combineResults(\n    output1.result.data,\n    output2.result.data,\n    output3.result.data\n  );\n}\n\`\`\`\n\n### Validation Loop\n\nGenerator + Validator with retry:\n\n\`\`\`typescript\nasync function generateValidOutput(\n  input: MyInput,\n  maxAttempts: number = 5\n) {\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    // Generate\n    const generatorOutput = await generator.execute(input);\n    if (generatorOutput.result.status === \'error\') continue;\n\n    // Validate\n    const validatorOutput = await validator.execute(\n      generatorOutput.result.data\n    );\n\n    if (validatorOutput.result.status === \'success\' &&\n        validatorOutput.result.data.valid) {\n      // Found valid output!\n      return generatorOutput.result.data;\n    }\n\n    // Invalid, retry with feedback\n    console.log(\'Attempt\', attempt + 1, \'invalid:\',\n      validatorOutput.result.data.reason);\n  }\n\n  throw new Error(\'Max attempts exceeded\');\n}\n\`\`\`\n\n### Human-in-the-Loop\n\nIntegrate human approval:\n\n\`\`\`typescript\n// Generate content\nconst generatorOutput = await generator.execute(input);\n\nif (generatorOutput.result.status === \'success\') {\n  // Request approval\n  const approvalOutput = await humanApproval.execute({\n    content: generatorOutput.result.data,\n    context: input,\n  });\n\n  if (approvalOutput.result.status === \'success\' &&\n      approvalOutput.result.data.approved) {\n    // Approved - continue\n    return generatorOutput.result.data;\n  } else {\n    // Rejected - handle feedback\n    console.log(\'Rejected:\', approvalOutput.result.data.feedback);\n  }\n}\n\`\`\`\n\n### Conversational Multi-Turn\n\nHandle stateful conversations:\n\n\`\`\`typescript\nlet session = {\n  state: { phase: \'gathering\' },\n  history: [],\n};\n\nwhile (true) {\n  const userMessage = await getUserInput();\n\n  const output = await conversationalAgent.execute({\n    message: userMessage,\n    sessionState: session.state,\n  });\n\n  console.log(\'Agent:\', output.reply);\n\n  // Update session\n  session = {\n    state: output.sessionState,\n    history: [\n      ...session.history,\n      { role: \'user\', content: userMessage },\n      { role: \'assistant\', content: output.reply },\n    ],\n  };\n\n  // Check completion\n  if (output.result.status === \'success\') {\n    console.log(\'Final result:\', output.result.data);\n    break;\n  } else if (output.result.status === \'error\') {\n    console.error(\'Failed:\', output.result.error);\n    break;\n  }\n  // Otherwise status === \'in-progress\', continue\n}\n\`\`\`\n\n**See also:** [orchestration.md](../../../../docs/orchestration.md) for complete guide"
+  agentGeneratorCreatingNewAgents: {
+    header: "## agent-generator: Creating New Agents",
+    body: "The **agent-generator** is a built-in meta-agent that guides you through designing\nhigh-quality agents via a 4-phase workflow:\n\n1. **GATHER** — Understand your intent and goals\n2. **ANALYZE** — Identify agent pattern and requirements\n3. **DESIGN** — Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** — Create validated agent package\n\nMinimum input needed:\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nThe generator produces: \`agent.yaml\`, \`prompts/system.md\`, \`prompts/user.md\`,\n\`schemas/input.schema.json\`, \`schemas/output.schema.json\`, and \`README.md\`.\n\n**Tips for better results:**\n- Be specific about success criteria (\"Under 30s, zero false negatives\") not vague (\"fast enough\")\n- Name the tools the agent needs upfront (file readers, APIs, etc.)\n- Describe domain context (OWASP Top 10, company coding standards, etc.)",
+    text: "## agent-generator: Creating New Agents\n\nThe **agent-generator** is a built-in meta-agent that guides you through designing\nhigh-quality agents via a 4-phase workflow:\n\n1. **GATHER** — Understand your intent and goals\n2. **ANALYZE** — Identify agent pattern and requirements\n3. **DESIGN** — Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** — Create validated agent package\n\nMinimum input needed:\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nThe generator produces: \`agent.yaml\`, \`prompts/system.md\`, \`prompts/user.md\`,\n\`schemas/input.schema.json\`, \`schemas/output.schema.json\`, and \`README.md\`.\n\n**Tips for better results:**\n- Be specific about success criteria (\"Under 30s, zero false negatives\") not vague (\"fast enough\")\n- Name the tools the agent needs upfront (file readers, APIs, etc.)\n- Describe domain context (OWASP Top 10, company coding standards, etc.)"
   },
-  testingAgents: {
-    header: "## Testing Agents",
-    body: "VAT provides test helpers and patterns for agent testing.\n\n### Unit Testing Pure Functions\n\n\`\`\`typescript\nimport { describe, expect, it } from \'vitest\';\nimport { resultMatchers } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myValidator\', () => {\n  it(\'should validate correct input\', async () => {\n    const output = await myValidator.execute({ text: \'valid\' });\n\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.valid).toBe(true);\n  });\n\n  it(\'should reject invalid input\', async () => {\n    const output = await myValidator.execute({ text: \'x\' });\n\n    resultMatchers.expectError(output.result);\n    expect(output.result.error).toBe(\'too-short\');\n  });\n});\n\`\`\`\n\n### Integration Testing with Mock LLM\n\n\`\`\`typescript\nimport { createMockContext } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myAnalyzer with mock LLM\', () => {\n  it(\'should parse LLM response\', async () => {\n    const mockContext = createMockContext(\n      JSON.stringify({ sentiment: \'positive\', confidence: 0.9 })\n    );\n\n    const output = await myAnalyzer.execute(\n      { text: \'Great!\' },\n      mockContext\n    );\n\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.sentiment).toBe(\'positive\');\n  });\n});\n\`\`\`\n\n### Testing Conversational Flows\n\n\`\`\`typescript\ndescribe(\'conversational agent flow\', () => {\n  it(\'should gather info progressively\', async () => {\n    // Turn 1\n    const output1 = await agent.execute({\n      message: \'Hello\',\n    });\n    expect(output1.reply).toContain(\'name?\');\n    resultMatchers.expectInProgress(output1.result);\n\n    // Turn 2\n    const output2 = await agent.execute({\n      message: \'My name is Alice\',\n      sessionState: output1.sessionState,\n    });\n    expect(output2.reply).toContain(\'age?\');\n    resultMatchers.expectInProgress(output2.result);\n\n    // Turn 3 (complete)\n    const output3 = await agent.execute({\n      message: \'I am 30\',\n      sessionState: output2.sessionState,\n    });\n    resultMatchers.expectSuccess(output3.result);\n    expect(output3.result.data).toBeDefined();\n  });\n});\n\`\`\`",
-    text: "## Testing Agents\n\nVAT provides test helpers and patterns for agent testing.\n\n### Unit Testing Pure Functions\n\n\`\`\`typescript\nimport { describe, expect, it } from \'vitest\';\nimport { resultMatchers } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myValidator\', () => {\n  it(\'should validate correct input\', async () => {\n    const output = await myValidator.execute({ text: \'valid\' });\n\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.valid).toBe(true);\n  });\n\n  it(\'should reject invalid input\', async () => {\n    const output = await myValidator.execute({ text: \'x\' });\n\n    resultMatchers.expectError(output.result);\n    expect(output.result.error).toBe(\'too-short\');\n  });\n});\n\`\`\`\n\n### Integration Testing with Mock LLM\n\n\`\`\`typescript\nimport { createMockContext } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myAnalyzer with mock LLM\', () => {\n  it(\'should parse LLM response\', async () => {\n    const mockContext = createMockContext(\n      JSON.stringify({ sentiment: \'positive\', confidence: 0.9 })\n    );\n\n    const output = await myAnalyzer.execute(\n      { text: \'Great!\' },\n      mockContext\n    );\n\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.sentiment).toBe(\'positive\');\n  });\n});\n\`\`\`\n\n### Testing Conversational Flows\n\n\`\`\`typescript\ndescribe(\'conversational agent flow\', () => {\n  it(\'should gather info progressively\', async () => {\n    // Turn 1\n    const output1 = await agent.execute({\n      message: \'Hello\',\n    });\n    expect(output1.reply).toContain(\'name?\');\n    resultMatchers.expectInProgress(output1.result);\n\n    // Turn 2\n    const output2 = await agent.execute({\n      message: \'My name is Alice\',\n      sessionState: output1.sessionState,\n    });\n    expect(output2.reply).toContain(\'age?\');\n    resultMatchers.expectInProgress(output2.result);\n\n    // Turn 3 (complete)\n    const output3 = await agent.execute({\n      message: \'I am 30\',\n      sessionState: output2.sessionState,\n    });\n    resultMatchers.expectSuccess(output3.result);\n    expect(output3.result.data).toBeDefined();\n  });\n});\n\`\`\`"
+  packagingMarkdownForReuse: {
+    header: "## Packaging Markdown for Reuse",
+    body: "VAT\'s resource compiler transforms markdown files into type-safe TypeScript modules,\nenabling prompt libraries, RAG knowledge bases, and shared content across projects.\n\n\`\`\`bash\nnpm install -D @vibe-agent-toolkit/resource-compiler\nnpx vat-compile-resources compile resources/ generated/resources/\n\`\`\`\n\n\`\`\`typescript\nimport * as Doc from \'./generated/resources/doc.js\';\n\nDoc.meta.title;                        // type-safe frontmatter\nDoc.fragments.introduction.text;       // H2 section content\nDoc.text;                              // full markdown\n\`\`\`\n\nUse cases: agent prompt libraries, RAG knowledge bases packaged as npm modules,\nmulti-project content sharing with versioning.",
+    text: "## Packaging Markdown for Reuse\n\nVAT\'s resource compiler transforms markdown files into type-safe TypeScript modules,\nenabling prompt libraries, RAG knowledge bases, and shared content across projects.\n\n\`\`\`bash\nnpm install -D @vibe-agent-toolkit/resource-compiler\nnpx vat-compile-resources compile resources/ generated/resources/\n\`\`\`\n\n\`\`\`typescript\nimport * as Doc from \'./generated/resources/doc.js\';\n\nDoc.meta.title;                        // type-safe frontmatter\nDoc.fragments.introduction.text;       // H2 section content\nDoc.text;                              // full markdown\n\`\`\`\n\nUse cases: agent prompt libraries, RAG knowledge bases packaged as npm modules,\nmulti-project content sharing with versioning."
   },
-  ragKnowledgeBases: {
-    header: "## RAG Knowledge Bases",
-    body: "VAT includes a full RAG (Retrieval-Augmented Generation) system for building searchable knowledge bases from markdown documentation. Key capabilities:\n\n- **Semantic search** over markdown files using vector embeddings\n- **Content transforms** — rewrite markdown links before indexing (e.g., convert local file links to plain text references)\n- **Document storage** — optionally persist full source documents alongside chunks for search-then-retrieve patterns\n- **Incremental indexing** — skip unchanged files, re-index only modifications\n- **Multiple embedding providers** — offline Transformers.js (default), ONNX Runtime, or OpenAI\n\nFor complete usage examples, configuration, and the programmatic TypeScript API, see the [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md).",
-    text: "## RAG Knowledge Bases\n\nVAT includes a full RAG (Retrieval-Augmented Generation) system for building searchable knowledge bases from markdown documentation. Key capabilities:\n\n- **Semantic search** over markdown files using vector embeddings\n- **Content transforms** — rewrite markdown links before indexing (e.g., convert local file links to plain text references)\n- **Document storage** — optionally persist full source documents alongside chunks for search-then-retrieve patterns\n- **Incremental indexing** — skip unchanged files, re-index only modifications\n- **Multiple embedding providers** — offline Transformers.js (default), ONNX Runtime, or OpenAI\n\nFor complete usage examples, configuration, and the programmatic TypeScript API, see the [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)."
+  commonWorkflows: {
+    header: "## Common Workflows",
+    body: "**Create a new agent:**\n\`\`\`bash\n# Use agent-generator interactively, then:\nvat agent import my-skill/SKILL.md   # import to VAT format\nvat skills validate                   # check quality\nvat skills build                      # package for distribution\n\`\`\`\n\n**Install and use a community skill:**\n\`\`\`bash\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\nvat skills list --user\n# Skills appear in ~/.claude/skills/ and are auto-loaded by Claude Code\n\`\`\`\n\n**Build and publish your own skill package:**\n\`\`\`bash\n# Add vat.skills to package.json, then:\nvat skills build          # builds all declared skills\nnpm publish               # publishes to npm\n# Users install with: vat skills install npm:@myorg/my-skills\n\`\`\`",
+    text: "## Common Workflows\n\n**Create a new agent:**\n\`\`\`bash\n# Use agent-generator interactively, then:\nvat agent import my-skill/SKILL.md   # import to VAT format\nvat skills validate                   # check quality\nvat skills build                      # package for distribution\n\`\`\`\n\n**Install and use a community skill:**\n\`\`\`bash\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\nvat skills list --user\n# Skills appear in ~/.claude/skills/ and are auto-loaded by Claude Code\n\`\`\`\n\n**Build and publish your own skill package:**\n\`\`\`bash\n# Add vat.skills to package.json, then:\nvat skills build          # builds all declared skills\nnpm publish               # publishes to npm\n# Users install with: vat skills install npm:@myorg/my-skills\n\`\`\`"
   },
-  bestPractices: {
-    header: "## Best Practices",
-    body: "### 1. Use Result Envelopes Consistently\n\nAlways return result envelopes, never throw exceptions for expected errors:\n\n\`\`\`typescript\n// ✅ GOOD\nreturn { result: { status: \'error\', error: \'invalid-input\' } };\n\n// ❌ BAD\nthrow new Error(\'Invalid input\');\n\`\`\`\n\n### 2. Define Clear Error Types\n\nUse enums or literal unions:\n\n\`\`\`typescript\n// ✅ GOOD\ntype MyError = \'invalid-format\' | \'processing-failed\' | \'timeout\';\n\n// ❌ BAD\ntype MyError = string;\n\`\`\`\n\n### 3. Validate Input and Output\n\nUse Zod schemas for type safety:\n\n\`\`\`typescript\nimport { z } from \'zod\';\n\nconst InputSchema = z.object({\n  text: z.string().min(1).max(1000),\n});\n\nconst OutputSchema = z.object({\n  result: z.boolean(),\n  reason: z.string().optional(),\n});\n\n// Validate at runtime\nconst input = InputSchema.parse(userInput);\nconst output = OutputSchema.parse(agentOutput);\n\`\`\`\n\n### 4. Test All Paths\n\nCover success, errors, and edge cases:\n\n\`\`\`typescript\ndescribe(\'myAgent\', () => {\n  it(\'should handle success case\');\n  it(\'should handle validation error\');\n  it(\'should handle LLM timeout\');\n  it(\'should handle malformed input\');\n});\n\`\`\`\n\n### 5. Use Mock Mode for External Dependencies\n\nEnable testing without API calls:\n\n\`\`\`typescript\nasync execute(input, options = { mockable: true }) {\n  if (options.mockable) {\n    // Fast, deterministic mock\n    return getMockResponse(input);\n  }\n  // Real API call\n  return await callExternalAPI(input);\n}\n\`\`\`\n\n### 6. Document Agent Behavior\n\nClear documentation helps users:\n\n\`\`\`typescript\n/**\n * Analyzes sentiment of text input.\n *\n * @param text - Text to analyze (max 1000 chars)\n * @returns Sentiment (positive/negative/neutral) with confidence score\n *\n * @example\n * const result = await analyzeSentiment(\"Great product!\");\n * // { sentiment: \'positive\', confidence: 0.9 }\n *\n * @throws Never throws - returns error result envelope on failure\n */\nexport async function analyzeSentiment(text: string) {\n  // ...\n}\n\`\`\`",
-    text: "## Best Practices\n\n### 1. Use Result Envelopes Consistently\n\nAlways return result envelopes, never throw exceptions for expected errors:\n\n\`\`\`typescript\n// ✅ GOOD\nreturn { result: { status: \'error\', error: \'invalid-input\' } };\n\n// ❌ BAD\nthrow new Error(\'Invalid input\');\n\`\`\`\n\n### 2. Define Clear Error Types\n\nUse enums or literal unions:\n\n\`\`\`typescript\n// ✅ GOOD\ntype MyError = \'invalid-format\' | \'processing-failed\' | \'timeout\';\n\n// ❌ BAD\ntype MyError = string;\n\`\`\`\n\n### 3. Validate Input and Output\n\nUse Zod schemas for type safety:\n\n\`\`\`typescript\nimport { z } from \'zod\';\n\nconst InputSchema = z.object({\n  text: z.string().min(1).max(1000),\n});\n\nconst OutputSchema = z.object({\n  result: z.boolean(),\n  reason: z.string().optional(),\n});\n\n// Validate at runtime\nconst input = InputSchema.parse(userInput);\nconst output = OutputSchema.parse(agentOutput);\n\`\`\`\n\n### 4. Test All Paths\n\nCover success, errors, and edge cases:\n\n\`\`\`typescript\ndescribe(\'myAgent\', () => {\n  it(\'should handle success case\');\n  it(\'should handle validation error\');\n  it(\'should handle LLM timeout\');\n  it(\'should handle malformed input\');\n});\n\`\`\`\n\n### 5. Use Mock Mode for External Dependencies\n\nEnable testing without API calls:\n\n\`\`\`typescript\nasync execute(input, options = { mockable: true }) {\n  if (options.mockable) {\n    // Fast, deterministic mock\n    return getMockResponse(input);\n  }\n  // Real API call\n  return await callExternalAPI(input);\n}\n\`\`\`\n\n### 6. Document Agent Behavior\n\nClear documentation helps users:\n\n\`\`\`typescript\n/**\n * Analyzes sentiment of text input.\n *\n * @param text - Text to analyze (max 1000 chars)\n * @returns Sentiment (positive/negative/neutral) with confidence score\n *\n * @example\n * const result = await analyzeSentiment(\"Great product!\");\n * // { sentiment: \'positive\', confidence: 0.9 }\n *\n * @throws Never throws - returns error result envelope on failure\n */\nexport async function analyzeSentiment(text: string) {\n  // ...\n}\n\`\`\`"
-  },
-  nextSteps: {
-    header: "## Next Steps",
-    body: "Now that you understand VAT basics:\n\n1. **Create your first agent** using agent-generator\n2. **Review examples** in \`@vibe-agent-toolkit/vat-example-cat-agents\`\n3. **Read detailed docs**:\n   - [agent-authoring.md](../../../../docs/agent-authoring.md)\n   - [orchestration.md](../../../../docs/orchestration.md)\n   - [getting-started.md](../../../../docs/getting-started.md)\n4. **Explore runtime adapters** for your preferred framework\n5. **Join the community** and share your agents",
-    text: "## Next Steps\n\nNow that you understand VAT basics:\n\n1. **Create your first agent** using agent-generator\n2. **Review examples** in \`@vibe-agent-toolkit/vat-example-cat-agents\`\n3. **Read detailed docs**:\n   - [agent-authoring.md](../../../../docs/agent-authoring.md)\n   - [orchestration.md](../../../../docs/orchestration.md)\n   - [getting-started.md](../../../../docs/getting-started.md)\n4. **Explore runtime adapters** for your preferred framework\n5. **Join the community** and share your agents"
+  successCriteria: {
+    header: "## Success Criteria",
+    body: "You\'ve successfully adopted VAT when:\n- Agents have clear input/output schemas (Zod-validated)\n- Errors are handled as data (result envelopes), never thrown\n- Tests cover success and error paths without real API calls (mock mode)\n- Agents work across multiple runtimes via adapters\n- Multi-agent pipelines compose via \`andThen()\` / \`match()\` helpers",
+    text: "## Success Criteria\n\nYou\'ve successfully adopted VAT when:\n- Agents have clear input/output schemas (Zod-validated)\n- Errors are handled as data (result envelopes), never thrown\n- Tests cover success and error paths without real API calls (mock mode)\n- Agents work across multiple runtimes via adapters\n- Multi-agent pipelines compose via \`andThen()\` / \`match()\` helpers"
   },
   documentationIndex: {
     header: "## Documentation Index",
-    body: "**Getting Started:**\n- [Getting Started Guide](../../../../docs/getting-started.md) - Setup and first steps\n\n**Agent Development:**\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) - Patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) - Multi-agent workflows\n\n**RAG & Knowledge Bases:**\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md) - Configuration, content transforms, document storage\n\n**Architecture:**\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md) - Multi-framework support\n\n**Examples:**\n- \`@vibe-agent-toolkit/vat-example-cat-agents\` - Reference implementations\n- Run demos: \`bun run demo:photos\`, \`bun run demo:conversation\`",
-    text: "## Documentation Index\n\n**Getting Started:**\n- [Getting Started Guide](../../../../docs/getting-started.md) - Setup and first steps\n\n**Agent Development:**\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) - Patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) - Multi-agent workflows\n\n**RAG & Knowledge Bases:**\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md) - Configuration, content transforms, document storage\n\n**Architecture:**\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md) - Multi-framework support\n\n**Examples:**\n- \`@vibe-agent-toolkit/vat-example-cat-agents\` - Reference implementations\n- Run demos: \`bun run demo:photos\`, \`bun run demo:conversation\`"
-  },
-  successCriteria: {
-    header: "## Success Criteria",
-    body: "You\'ve successfully adopted VAT when:\n\n**For Single Agents:**\n- Agent has clear input/output schemas\n- Errors are handled as data (result envelopes)\n- Tests cover success and error paths\n- Agent works across multiple runtimes\n\n**For Workflows:**\n- Multi-agent pipelines compose cleanly\n- Retry logic handles transient failures\n- State management is explicit\n- Observability shows performance/cost\n\n**For Teams:**\n- Agents are reusable across projects\n- Framework choice is flexible\n- Testing doesn\'t require real APIs\n- Documentation enables self-service",
-    text: "## Success Criteria\n\nYou\'ve successfully adopted VAT when:\n\n**For Single Agents:**\n- Agent has clear input/output schemas\n- Errors are handled as data (result envelopes)\n- Tests cover success and error paths\n- Agent works across multiple runtimes\n\n**For Workflows:**\n- Multi-agent pipelines compose cleanly\n- Retry logic handles transient failures\n- State management is explicit\n- Observability shows performance/cost\n\n**For Teams:**\n- Agents are reusable across projects\n- Framework choice is flexible\n- Testing doesn\'t require real APIs\n- Documentation enables self-service"
+    body: "- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`",
+    text: "## Documentation Index\n\n- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`"
   },
   gettingHelp: {
     header: "## Getting Help",
-    body: "- **Documentation:** See Architecture Overview and Getting Started links above\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n\nHappy agent building!",
-    text: "## Getting Help\n\n- **Documentation:** See Architecture Overview and Getting Started links above\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n\nHappy agent building!"
+    body: "- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n\nHappy agent building!",
+    text: "## Getting Help\n\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n\nHappy agent building!"
   }
 };

package/dist/generated/resources/skills/vat-agent-authoring.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generated TypeScript declarations - DO NOT EDIT
+ */
+
+export interface Fragment {
+  readonly header: string;
+  readonly body: string;
+  readonly text: string;
+}
+
+export const meta: {
+  readonly name: string;
+  readonly description: string;
+};
+
+export const text: string;
+
+export const fragments: {
+  readonly skillmdStructure: Fragment;
+  readonly agentArchetypes: Fragment;
+  readonly resultEnvelopes: Fragment;
+  readonly orchestrationPatterns: Fragment;
+  readonly packagingoptionsReference: Fragment;
+  readonly testingAgents: Fragment;
+  readonly bestPractices: Fragment;
+  readonly references: Fragment;
+};
+
+export type FragmentName = keyof typeof fragments;