@vibe-agent-toolkit/vat-development-agents 0.1.13 → 0.1.14

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

@@ -25,6 +25,7 @@ export const fragments: {
   readonly resultEnvelopesAndErrorHandling: Fragment;
   readonly orchestrationPatterns: Fragment;
   readonly testingAgents: Fragment;
+  readonly ragKnowledgeBases: Fragment;
   readonly bestPractices: Fragment;
   readonly nextSteps: Fragment;
   readonly documentationIndex: Fragment;

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

@@ -7,7 +7,7 @@ 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-generator README](../../agents/agent-generator/README.md) - Full 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### 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## 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- [Main README](../../../../README.md) - Project overview\n\n**Agent Development:**\n- [agent-generator README](../../agents/agent-generator/README.md) - Meta-agent for creating agents\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) - Patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) - Multi-agent workflows\n\n**Architecture:**\n- [Architecture Overview](../../../../docs/architecture/README.md) - Package structure\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:** [docs/README.md](../../../../docs/README.md)\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\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 fragments = {
   purposeForUsersNotContributors: {
@@ -27,8 +27,8 @@ export const fragments = {
   },
   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-generator README](../../agents/agent-generator/README.md) - Full 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-generator README](../../agents/agent-generator/README.md) - Full documentation\n- [agent-authoring.md](../../../../docs/agent-authoring.md) - Agent patterns and examples\n- [orchestration.md](../../../../docs/orchestration.md) - Multi-agent workflows"
+    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"
   },
   understandingAgentPatterns: {
     header: "## Understanding Agent Patterns",
@@ -37,8 +37,8 @@ export const fragments = {
   },
   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### 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### 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\`\`\`"
+    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\`\`\`"
   },
   resultEnvelopesAndErrorHandling: {
     header: "## Result Envelopes and Error Handling",
@@ -55,6 +55,11 @@ export const fragments = {
     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\`\`\`"
   },
+  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)."
+  },
   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\`\`\`",
@@ -67,8 +72,8 @@ export const fragments = {
   },
   documentationIndex: {
     header: "## Documentation Index",
-    body: "**Getting Started:**\n- [Getting Started Guide](../../../../docs/getting-started.md) - Setup and first steps\n- [Main README](../../../../README.md) - Project overview\n\n**Agent Development:**\n- [agent-generator README](../../agents/agent-generator/README.md) - Meta-agent for creating agents\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) - Patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) - Multi-agent workflows\n\n**Architecture:**\n- [Architecture Overview](../../../../docs/architecture/README.md) - Package structure\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- [Main README](../../../../README.md) - Project overview\n\n**Agent Development:**\n- [agent-generator README](../../agents/agent-generator/README.md) - Meta-agent for creating agents\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) - Patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) - Multi-agent workflows\n\n**Architecture:**\n- [Architecture Overview](../../../../docs/architecture/README.md) - Package structure\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\`"
+    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",
@@ -77,7 +82,7 @@ export const fragments = {
   },
   gettingHelp: {
     header: "## Getting Help",
-    body: "- **Documentation:** [docs/README.md](../../../../docs/README.md)\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:** [docs/README.md](../../../../docs/README.md)\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: "- **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!"
   }
 };

package/dist/skills/vibe-agent-toolkit/SKILL.md

@@ -209,9 +209,8 @@ The generator incorporates best practices from:
 - [AI Agent Orchestration - Microsoft Azure](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns)
 
 **Documentation:**
-- [agent-generator README](README.md) - Full documentation
-- [agent-authoring.md](../../../../docs/agent-authoring.md) - Agent patterns and examples
-- [orchestration.md](../../../../docs/orchestration.md) - Multi-agent workflows
+- agent-authoring.md - Agent patterns and examples
+- [orchestration.md](resources/orchestration.md) - Multi-agent workflows
 
 ## Understanding Agent Patterns
 
@@ -345,8 +344,8 @@ export async function humanApproval(
 ```
 
 **See also:**
-- [agent-authoring.md](../../../../docs/agent-authoring.md) - Complete patterns guide
-- [orchestration.md](../../../../docs/orchestration.md) - Chaining and workflows
+- agent-authoring.md - Complete patterns guide
+- [orchestration.md](resources/orchestration.md) - Chaining and workflows
 
 ## VAT CLI Workflows
 
@@ -519,6 +518,39 @@ The audit checks for:
 - Link integrity
 - Console tool availability
 
+### RAG Commands
+
+**Index documentation into a vector database:**
+```bash
+# Index all markdown files in docs/
+vat rag index docs/
+
+# Index with specific database path
+vat rag index docs/ --db ./dist/rag-db
+```
+
+**Search indexed documentation:**
+```bash
+# Semantic search
+vat rag query "How do I configure authentication?"
+
+# Limit results
+vat rag query "error handling" --limit 5
+
+# Query specific database
+vat rag query "setup guide" --db ./dist/rag-db
+```
+
+**Manage the database:**
+```bash
+# View database statistics
+vat rag stats
+
+# Clear and rebuild
+vat rag clear
+vat rag index docs/
+```
+
 ### Resources Commands
 
 **Validate markdown resources:**
@@ -734,7 +766,7 @@ const message = match(result, {
 });
 ```
 
-**See also:** [orchestration.md](../../../../docs/orchestration.md) for composition patterns
+**See also:** [orchestration.md](resources/orchestration.md) for composition patterns
 
 ## Orchestration Patterns
 
@@ -894,7 +926,7 @@ while (true) {
 }
 ```
 
-**See also:** [orchestration.md](../../../../docs/orchestration.md) for complete guide
+**See also:** [orchestration.md](resources/orchestration.md) for complete guide
 
 ## Testing Agents
 
@@ -976,6 +1008,18 @@ describe('conversational agent flow', () => {
 });
 ```
 
+## RAG Knowledge Bases
+
+VAT includes a full RAG (Retrieval-Augmented Generation) system for building searchable knowledge bases from markdown documentation. Key capabilities:
+
+- **Semantic search** over markdown files using vector embeddings
+- **Content transforms** — rewrite markdown links before indexing (e.g., convert local file links to plain text references)
+- **Document storage** — optionally persist full source documents alongside chunks for search-then-retrieve patterns
+- **Incremental indexing** — skip unchanged files, re-index only modifications
+- **Multiple embedding providers** — offline Transformers.js (default), ONNX Runtime, or OpenAI
+
+For complete usage examples, configuration, and the programmatic TypeScript API, see the [RAG Usage Guide](resources/rag-usage-guide.md).
+
 ## Best Practices
 
 ### 1. Use Result Envelopes Consistently
@@ -1080,26 +1124,26 @@ Now that you understand VAT basics:
 1. **Create your first agent** using agent-generator
 2. **Review examples** in `@vibe-agent-toolkit/vat-example-cat-agents`
 3. **Read detailed docs**:
-   - [agent-authoring.md](../../../../docs/agent-authoring.md)
-   - [orchestration.md](../../../../docs/orchestration.md)
-   - [getting-started.md](../../../../docs/getting-started.md)
+   - agent-authoring.md
+   - [orchestration.md](resources/orchestration.md)
+   - getting-started.md
 4. **Explore runtime adapters** for your preferred framework
 5. **Join the community** and share your agents
 
 ## Documentation Index
 
 **Getting Started:**
-- [Getting Started Guide](../../../../docs/getting-started.md) - Setup and first steps
-- [Main README](../../../../README.md) - Project overview
+- Getting Started Guide - Setup and first steps
 
 **Agent Development:**
-- [agent-generator README](README.md) - Meta-agent for creating agents
-- [Agent Authoring Guide](../../../../docs/agent-authoring.md) - Patterns and code examples
-- [Orchestration Guide](../../../../docs/orchestration.md) - Multi-agent workflows
+- Agent Authoring Guide - Patterns and code examples
+- [Orchestration Guide](resources/orchestration.md) - Multi-agent workflows
+
+**RAG & Knowledge Bases:**
+- [RAG Usage Guide](resources/rag-usage-guide.md) - Configuration, content transforms, document storage
 
 **Architecture:**
-- [Architecture Overview](../../../../docs/architecture/README.md) - Package structure
-- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md) - Multi-framework support
+- [Runtime Adapters](resources/adding-runtime-adapters.md) - Multi-framework support
 
 **Examples:**
 - `@vibe-agent-toolkit/vat-example-cat-agents` - Reference implementations
@@ -1129,7 +1173,7 @@ You've successfully adopted VAT when:
 
 ## Getting Help
 
-- **Documentation:** [docs/README.md](../../../../docs/README.md)
+- **Documentation:** See Architecture Overview and Getting Started links above
 - **Examples:** `packages/vat-example-cat-agents/`
 - **GitHub Issues:** Report bugs or ask questions
 - **CLI Help:** `vat --help`, `vat skills --help`, etc.