@vpxa/kb 0.1.13 → 0.1.16

package/packages/tui/dist/store.interface-CnY6SPOH.d.ts

@@ -0,0 +1,150 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+//#region packages/core/dist/types.d.ts
+//#region packages/core/src/types.d.ts
+/**
+ * Core types for the MCP Knowledge Base system.
+ */
+/** The origin of a knowledge record — how it was created */
+declare const KNOWLEDGE_ORIGINS: readonly ["indexed", "curated", "produced"];
+type KnowledgeOrigin = (typeof KNOWLEDGE_ORIGINS)[number];
+/** Coarse source classification derived from ContentType */
+declare const SOURCE_TYPES: readonly ["source", "documentation", "test", "config", "generated"];
+type SourceType = (typeof SOURCE_TYPES)[number];
+/** Content type classification */
+declare const CONTENT_TYPES: readonly ["documentation", "code-typescript", "code-javascript", "code-python", "code-other", "config-json", "config-yaml", "config-toml", "config-env", "test-code", "cdk-stack", "markdown", "curated-knowledge", "produced-knowledge", "unknown"];
+type ContentType = (typeof CONTENT_TYPES)[number];
+/** A single knowledge record stored in the vector DB */
+interface KnowledgeRecord {
+  /** Unique identifier (deterministic hash of source + chunk index) */
+  id: string;
+  /** The text content of this chunk */
+  content: string;
+  /** Source file path relative to workspace root */
+  sourcePath: string;
+  /** Content type classification */
+  contentType: ContentType;
+  /** Heading path for markdown (e.g., "## Setup > ### Prerequisites") */
+  headingPath?: string;
+  /** Zero-based chunk index within the source file */
+  chunkIndex: number;
+  /** Total number of chunks from this source file */
+  totalChunks: number;
+  /** Start line in source file (1-based) */
+  startLine: number;
+  /** End line in source file (1-based) */
+  endLine: number;
+  /** File hash for incremental indexing */
+  fileHash: string;
+  /** ISO timestamp when this record was created/updated */
+  indexedAt: string;
+  /** How this record was created */
+  origin: KnowledgeOrigin;
+  /** User-defined tags for categorization */
+  tags: string[];
+  /** Category for curated/produced knowledge */
+  category?: string;
+  /** Version number for curated knowledge updates */
+  version: number;
+}
+/** A raw chunk produced by a chunker before embedding */
+/** Search result returned by the store */
+interface SearchResult {
+  /** The matching knowledge record */
+  record: KnowledgeRecord;
+  /** Similarity score (0-1, higher = more similar) */
+  score: number;
+}
+/** Configuration loaded from kb.config.json */
+interface KBConfig {
+  /** MCP server name. Defaults to 'kb'. */
+  serverName?: string;
+  sources: Array<{
+    path: string;
+    excludePatterns: string[];
+  }>;
+  indexing: {
+    chunkSize: number;
+    chunkOverlap: number;
+    minChunkSize: number; /** Max files processed concurrently. Defaults to half of available CPU cores. */
+    concurrency?: number;
+  };
+  embedding: {
+    model: string;
+    dimensions: number;
+  };
+  store: {
+    backend: string;
+    path: string;
+  };
+  curated: {
+    path: string;
+  };
+  /** Enterprise RAG bridge configuration (optional) */
+  er?: {
+    /** Whether ER integration is enabled */enabled: boolean; /** Base URL of the ER API (e.g., https://xxx.execute-api.region.amazonaws.com/prod) */
+    baseUrl: string; /** Request timeout in milliseconds. Defaults to 5000. */
+    timeoutMs?: number; /** Cache TTL in milliseconds. Defaults to 21600000 (6 hours). */
+    cacheTtlMs?: number; /** Maximum cache entries. Defaults to 100. */
+    cacheMaxEntries?: number; /** Vector similarity threshold below which ER fallback triggers. Defaults to 0.45. */
+    fallbackThreshold?: number;
+  };
+}
+/** Index statistics */
+interface IndexStats {
+  totalRecords: number;
+  totalFiles: number;
+  contentTypeBreakdown: Record<string, number>;
+  lastIndexedAt: string | null;
+  storeBackend: string;
+  embeddingModel: string;
+} //#endregion
+//#endregion
+//#region packages/store/dist/store.interface.d.ts
+//#region packages/store/src/store.interface.d.ts
+/** Options for searching the store */
+interface SearchOptions {
+  /** Maximum number of results to return */
+  limit?: number;
+  /** Minimum similarity score (0-1) */
+  minScore?: number;
+  /** Filter by content type */
+  contentType?: ContentType;
+  /** Filter by coarse source type (source, documentation, test, config, generated) */
+  sourceType?: SourceType;
+  /** Filter by origin */
+  origin?: KnowledgeOrigin;
+  /** Filter by category */
+  category?: string;
+  /** Filter by tags (any match) */
+  tags?: string[];
+}
+interface IKnowledgeStore {
+  /** Initialize the store (create tables, etc.) */
+  initialize(): Promise<void>;
+  /** Add or update records with their embedding vectors */
+  upsert(records: KnowledgeRecord[], vectors: Float32Array[]): Promise<void>;
+  /** Search by vector similarity */
+  search(queryVector: Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+  /** Get a specific record by ID */
+  getById(id: string): Promise<KnowledgeRecord | null>;
+  /** Delete records by source path (used during re-indexing) */
+  deleteBySourcePath(sourcePath: string): Promise<number>;
+  /** Delete a specific record by ID */
+  deleteById(id: string): Promise<boolean>;
+  /** Get all records for a source path */
+  getBySourcePath(sourcePath: string): Promise<KnowledgeRecord[]>;
+  /** Get index statistics */
+  getStats(): Promise<IndexStats>;
+  /** List all unique source paths in the store */
+  listSourcePaths(): Promise<string[]>;
+  /** Create a full-text search index on the content column for keyword search */
+  createFtsIndex(): Promise<void>;
+  /** Full-text keyword search (requires FTS index) */
+  ftsSearch(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+  /** Drop the backing table entirely — used for hard resets (e.g. dimension changes) */
+  dropTable(): Promise<void>;
+  /** Close the store connection */
+  close(): Promise<void>;
+} //#endregion
+//#endregion
+export { KBConfig as n, IKnowledgeStore as t };

package/scaffold/adapters/claude-code.mjs

@@ -0,0 +1,20 @@
+/**
+ * Claude Code adapter — generates Claude Code config from definitions.
+ *
+ * Output format:
+ *   CLAUDE.md                     — Main instructions (agents + protocols inline)
+ *   .claude/settings.json         — Hooks config
+ *   .mcp.json                     — MCP server config
+ *   .claude/commands/{name}.md    — Slash commands (from prompts)
+ *
+ * Status: STUB — not yet implemented.
+ */
+
+export function generateClaudeCode() {
+  // TODO: Implement Claude Code adapter
+  // - Inline agent instructions into CLAUDE.md sections
+  // - Map prompts to slash commands
+  // - Map hooks to .claude/settings.json hooks config
+  // - Generate .mcp.json
+  return [];
+}

package/scaffold/adapters/copilot.mjs

@@ -0,0 +1,320 @@
+/**
+ * Copilot adapter — generates GitHub Copilot agent files from definitions.
+ *
+ * Output format:
+ *   agents/{Name}.agent.md          — YAML frontmatter + markdown body
+ *   agents/_shared/{name}.md        — Shared protocol files
+ *   agents/templates/execution-state.md
+ *   agents/README.md
+ *   prompts/{name}.prompt.md        — YAML frontmatter + markdown body
+ *
+ * Copilot-specific conventions:
+ *   - model field appends " (copilot)" suffix
+ *   - tools are listed as YAML array in frontmatter
+ *   - prompts target a specific agent via `agent:` field
+ *   - hooks are embedded in copilot-instructions.md (not separate files)
+ *   - plugins/skills are SKILL.md files in .github/skills/
+ */
+
+import { AGENTS } from '../definitions/agents.mjs';
+import { AGENT_BODIES } from '../definitions/bodies.mjs';
+import { MODELS, VARIANT_GROUPS } from '../definitions/models.mjs';
+import { PROMPTS } from '../definitions/prompts.mjs';
+import { PROTOCOLS } from '../definitions/protocols.mjs';
+import { IDE_CAPABILITIES, KB_TOOLS } from '../definitions/tools.mjs';
+
+// ─── Copilot tool mapping ─────────────────────────────────────────────────
+
+/** Map abstract IDE capability names to Copilot tool identifiers */
+const COPILOT_TOOL_MAP = {
+  terminal: 'execute/runInTerminal',
+  problems: 'read/problems',
+  readFile: 'read/readFile',
+  lastCommand: 'read/terminalLastCommand',
+  subagent: 'agent/runSubagent',
+  createFile: 'edit/createFile',
+  editFiles: 'edit/editFiles',
+  search: 'search/changes, search/codebase, search/usages',
+  web: 'web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch',
+  todo: 'todo',
+  memory: 'vscode/memory',
+  runCommand: 'vscode/runCommand',
+  switchAgent: 'vscode/switchAgent',
+  killTerminal: 'execute/killTerminal',
+  createTask: 'execute/createAndRunTask',
+  terminalSel: 'read/terminalSelection',
+  fileSearch: 'search/fileSearch',
+  listDir: 'search/listDirectory',
+  textSearch: 'search/textSearch',
+  searchResults: 'search/searchResults',
+};
+
+function buildToolsYaml(toolRole) {
+  const capabilities = IDE_CAPABILITIES[toolRole] || [];
+  const copilotTools = capabilities.map((cap) => COPILOT_TOOL_MAP[cap]).filter(Boolean);
+  const kbTools = KB_TOOLS.map((t) => `knowledge-base/${t}`);
+  return `[${[...copilotTools, ...kbTools].join(', ')}]`;
+}
+
+function copilotModel(agentName) {
+  const base = MODELS[agentName];
+  return base ? `${base} (copilot)` : 'Claude Opus 4.6 (copilot)';
+}
+
+// ─── Agent file generators ────────────────────────────────────────────────
+
+function buildAgentTable() {
+  const rows = [];
+  for (const [name, def] of Object.entries(AGENTS)) {
+    if (def.variants) {
+      for (const suffix of VARIANT_GROUPS[name] || []) {
+        const fullName = `${name}-${suffix}`;
+        const model = MODELS[fullName] || 'Unknown';
+        const varDef = def.variants[suffix] || {};
+        const desc = varDef.description || def.description;
+        rows.push(`| **${fullName}** | ${desc} | ${model} | ${def.category} |`);
+      }
+    } else {
+      const model = MODELS[name] || 'Unknown';
+      rows.push(`| **${name}** | ${def.description} | ${model} | ${def.category} |`);
+    }
+  }
+  return `| Agent | Purpose | Model | Category |\n|-------|---------|-------|----------|\n${rows.join('\n')}`;
+}
+
+function generateVariantAgent(roleName, suffix, def) {
+  const fullName = `${roleName}-${suffix}`;
+  const varDef = def.variants[suffix] || {};
+  const model = copilotModel(fullName);
+  const desc = varDef.description || def.description;
+  const identity =
+    varDef.identity ||
+    (suffix === VARIANT_GROUPS[roleName]?.[0]
+      ? `, the primary ${roleName} agent.`
+      : `, a variant of ${roleName}. Same responsibilities, different model perspective.`);
+
+  const sharedRef = def.sharedBase
+    ? `\n**Read .github/agents/_shared/${def.sharedBase}.md NOW** — it contains your complete workflow and guidelines. All instructions there apply to you.`
+    : '';
+
+  const extra = def.extraBody ? `\n\n${def.extraBody}` : '';
+
+  const titleMap = {
+    Researcher: 'The Context Gatherer',
+    'Code-Reviewer': 'The Quality Guardian',
+    'Architect-Reviewer': 'The Structural Guardian',
+  };
+  const title = titleMap[roleName] || roleName;
+
+  return `---
+description: '${desc}'
+${def.argumentHint ? `argument-hint: ${def.argumentHint}\n` : ''}tools: ${buildToolsYaml(def.toolRole)}
+model: ${model}
+---
+
+# ${fullName} - ${title}
+
+You are **${fullName}**${identity}${extra}
+${sharedRef}
+`;
+}
+
+function generateSingleAgent(name, def) {
+  const model = copilotModel(name);
+  const body =
+    typeof AGENT_BODIES[name] === 'function'
+      ? AGENT_BODIES[name](buildAgentTable())
+      : AGENT_BODIES[name] || '';
+
+  const titleMap = {
+    Orchestrator: 'The Master Conductor',
+    Planner: 'The Strategic Architect',
+    Implementer: 'The Code Builder',
+    Frontend: 'The UI Specialist',
+    Debugger: 'The Problem Solver',
+    Refactor: 'The Code Sculptor',
+    Security: 'The Vulnerability Hunter',
+    Documenter: 'The Knowledge Keeper',
+    Explorer: 'The Rapid Scout',
+  };
+  const title = titleMap[name] || name;
+
+  return `---
+description: '${def.description}'
+${def.argumentHint ? `argument-hint: ${def.argumentHint}\n` : ''}tools: ${buildToolsYaml(def.toolRole)}
+model: ${model}
+---
+
+# ${name} - ${title}
+
+You are the **${name}**, ${def.description.toLowerCase().replace(/^./, (c) => c.toLowerCase())}
+
+${body}
+`;
+}
+
+// ─── Prompt file generator ────────────────────────────────────────────────
+
+function generatePrompt(_name, def) {
+  const kbTools = (def.tools || []).map((t) => `knowledge-base/${t}`);
+  const toolsYaml = kbTools.map((t) => `  - ${t}`).join('\n');
+  return `---
+description: "${def.description}"
+agent: "${def.agent}"
+tools:
+${toolsYaml}
+---
+
+${def.content}
+`;
+}
+
+// ─── Templates ────────────────────────────────────────────────────────────
+
+const EXECUTION_STATE = `# Execution State: {Task Title}
+
+**Status:** PLANNING | IN_PROGRESS | REVIEW | COMPLETED | BLOCKED
+**Started:** {timestamp}
+**Plan:** {link to plan file}
+
+## Phases
+
+| # | Title | Agent | Status | Batch |
+|---|-------|-------|--------|-------|
+
+## Current Batch
+
+**Batch {N}:** {phases in this batch}
+**Status:** IMPLEMENTING | REVIEWING | APPROVED
+
+## Decisions Log
+
+| Decision | Rationale | ADR |
+|----------|-----------|-----|
+
+## Blockers
+
+| Issue | Severity | Assigned |
+|-------|----------|----------|
+`;
+
+const ADR_TEMPLATE = `# DR-NNN: {Short Title}
+
+**Status:** Proposed | Accepted | Rejected | Deprecated | Superseded
+**Date:** YYYY-MM-DD
+**Participants:** {which Researcher variants participated}
+
+## Context
+{What is the issue? Why are we making this decision?}
+{If superseding, link: "Supersedes DR-NNN."}
+
+## Decision
+{What was decided and why — 2-5 sentences max}
+
+## Decision Analysis Summary
+| Model | Recommendation | Key Reasoning |
+|-------|---------------|---------------|
+
+**Agreements:** {what 3+ models agreed on}
+**Disagreements:** {where they diverged}
+
+## Consequences
+**Positive:** {benefits}
+**Negative:** {trade-offs accepted}
+**Risks:** {what could go wrong, and any mitigations}
+
+## Alternatives Considered
+{Other approaches evaluated and why they were rejected — keeps the "why not" alongside the "why"}
+`;
+
+// ─── README generator ─────────────────────────────────────────────────────
+
+function generateReadme() {
+  return `# Agents
+
+This directory contains AI agent definitions generated by \`@vpxa/kb init\`.
+
+## Agent Roster
+
+${buildAgentTable()}
+
+## Multi-Model Pattern
+
+Variant agents (Researcher-Alpha/Beta/Gamma/Delta, Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta) share the same methodology via files in \`_shared/\`. They differ only in which LLM model backs them — enabling multi-model decision analysis and dual-review workflows.
+
+**Agent names are model-agnostic.** The model behind Alpha/Beta/Gamma/Delta can be changed in \`scaffold/definitions/models.mjs\` without renaming any agent files.
+
+## Structure
+
+\`\`\`
+agents/
+  {Name}.agent.md          — Agent definition (YAML frontmatter + instructions)
+  _shared/                  — Shared protocols referenced by multiple agents
+    code-agent-base.md      — Base for all code-modifying agents
+    researcher-base.md      — Base for all Researcher variants
+    code-reviewer-base.md   — Base for all Code-Reviewer variants
+    architect-reviewer-base.md — Base for all Architect-Reviewer variants
+    decision-protocol.md    — Multi-model decision protocol rules
+    forge-protocol.md       — FORGE quality gate protocol
+  templates/
+    execution-state.md      — Orchestrator state tracking template
+    adr-template.md         — Architecture Decision Record template
+\`\`\`
+
+## Regenerating
+
+To regenerate after changing models or agent definitions:
+
+\`\`\`bash
+cd knowledge-base
+node scaffold/generate.mjs
+\`\`\`
+`;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Generate all Copilot scaffold files.
+ * Returns an array of { path, content } objects.
+ * The caller (generate.mjs) is responsible for writing them to disk.
+ */
+export function generateCopilot() {
+  const files = [];
+
+  // Agent files
+  for (const [name, def] of Object.entries(AGENTS)) {
+    if (def.variants) {
+      for (const suffix of VARIANT_GROUPS[name] || []) {
+        files.push({
+          path: `agents/${name}-${suffix}.agent.md`,
+          content: generateVariantAgent(name, suffix, def),
+        });
+      }
+    } else {
+      files.push({
+        path: `agents/${name}.agent.md`,
+        content: generateSingleAgent(name, def),
+      });
+    }
+  }
+
+  // Shared protocols
+  for (const [name, content] of Object.entries(PROTOCOLS)) {
+    files.push({ path: `agents/_shared/${name}.md`, content: `${content}\n` });
+  }
+
+  // Templates
+  files.push({ path: 'agents/templates/execution-state.md', content: EXECUTION_STATE });
+  files.push({ path: 'agents/templates/adr-template.md', content: ADR_TEMPLATE });
+
+  // README
+  files.push({ path: 'agents/README.md', content: generateReadme() });
+
+  // Prompts
+  for (const [name, def] of Object.entries(PROMPTS)) {
+    files.push({ path: `prompts/${name}.prompt.md`, content: generatePrompt(name, def) });
+  }
+
+  return files;
+}

package/scaffold/copilot/agents/Architect-Reviewer-Alpha.agent.md

@@ -0,0 +1,21 @@
+---
+description: 'Primary architecture reviewer'
+argument-hint: Files, PR, or subsystem to architecture-review
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/analyze_dependencies, knowledge-base/analyze_diagram, knowledge-base/analyze_entry_points, knowledge-base/analyze_patterns, knowledge-base/analyze_structure, knowledge-base/analyze_symbols, knowledge-base/audit, knowledge-base/batch, knowledge-base/blast_radius, knowledge-base/changelog, knowledge-base/check, knowledge-base/checkpoint, knowledge-base/codemod, knowledge-base/compact, knowledge-base/data_transform, knowledge-base/dead_symbols, knowledge-base/delegate, knowledge-base/diff_parse, knowledge-base/digest, knowledge-base/encode, knowledge-base/env, knowledge-base/eval, knowledge-base/evidence_map, knowledge-base/file_summary, knowledge-base/find, knowledge-base/forge_classify, knowledge-base/forge_ground, knowledge-base/forget, knowledge-base/git_context, knowledge-base/graph, knowledge-base/guide, knowledge-base/health, knowledge-base/http, knowledge-base/lane, knowledge-base/list, knowledge-base/lookup, knowledge-base/measure, knowledge-base/onboard, knowledge-base/parse_output, knowledge-base/process, knowledge-base/produce_knowledge, knowledge-base/queue, knowledge-base/read, knowledge-base/regex_test, knowledge-base/reindex, knowledge-base/remember, knowledge-base/rename, knowledge-base/replay, knowledge-base/schema_validate, knowledge-base/scope_map, knowledge-base/search, knowledge-base/snippet, knowledge-base/stash, knowledge-base/status, knowledge-base/stratum_card, knowledge-base/symbol, knowledge-base/test_run, knowledge-base/time, knowledge-base/trace, knowledge-base/update, knowledge-base/watch, knowledge-base/web_fetch, knowledge-base/web_search, knowledge-base/workset]
+model: GPT-5.4 (copilot)
+---
+
+# Architect-Reviewer-Alpha - The Structural Guardian
+
+You are **Architect-Reviewer-Alpha**, the primary Architect-Reviewer agent.
+
+You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.
+
+**Read .github/agents/_shared/architect-reviewer-base.md NOW** — it contains your complete workflow and guidelines. All instructions there apply to you.
+
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| `c4-architecture` | When reviewing architectural diagrams or boundary changes |
+| `adr-skill` | When the review involves architecture decisions — reference or create ADRs |

package/scaffold/copilot/agents/Architect-Reviewer-Beta.agent.md

@@ -0,0 +1,21 @@
+---
+description: 'Architecture reviewer variant — different LLM perspective for dual review'
+argument-hint: Files, PR, or subsystem to architecture-review
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/analyze_dependencies, knowledge-base/analyze_diagram, knowledge-base/analyze_entry_points, knowledge-base/analyze_patterns, knowledge-base/analyze_structure, knowledge-base/analyze_symbols, knowledge-base/audit, knowledge-base/batch, knowledge-base/blast_radius, knowledge-base/changelog, knowledge-base/check, knowledge-base/checkpoint, knowledge-base/codemod, knowledge-base/compact, knowledge-base/data_transform, knowledge-base/dead_symbols, knowledge-base/delegate, knowledge-base/diff_parse, knowledge-base/digest, knowledge-base/encode, knowledge-base/env, knowledge-base/eval, knowledge-base/evidence_map, knowledge-base/file_summary, knowledge-base/find, knowledge-base/forge_classify, knowledge-base/forge_ground, knowledge-base/forget, knowledge-base/git_context, knowledge-base/graph, knowledge-base/guide, knowledge-base/health, knowledge-base/http, knowledge-base/lane, knowledge-base/list, knowledge-base/lookup, knowledge-base/measure, knowledge-base/onboard, knowledge-base/parse_output, knowledge-base/process, knowledge-base/produce_knowledge, knowledge-base/queue, knowledge-base/read, knowledge-base/regex_test, knowledge-base/reindex, knowledge-base/remember, knowledge-base/rename, knowledge-base/replay, knowledge-base/schema_validate, knowledge-base/scope_map, knowledge-base/search, knowledge-base/snippet, knowledge-base/stash, knowledge-base/status, knowledge-base/stratum_card, knowledge-base/symbol, knowledge-base/test_run, knowledge-base/time, knowledge-base/trace, knowledge-base/update, knowledge-base/watch, knowledge-base/web_fetch, knowledge-base/web_search, knowledge-base/workset]
+model: Claude Opus 4.6 (copilot)
+---
+
+# Architect-Reviewer-Beta - The Structural Guardian
+
+You are **Architect-Reviewer-Beta**, a variant of Architect-Reviewer. Same responsibilities, different model perspective.
+
+You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.
+
+**Read .github/agents/_shared/architect-reviewer-base.md NOW** — it contains your complete workflow and guidelines. All instructions there apply to you.
+
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| `c4-architecture` | When reviewing architectural diagrams or boundary changes |
+| `adr-skill` | When the review involves architecture decisions — reference or create ADRs |

package/scaffold/copilot/agents/Documenter.agent.md

@@ -0,0 +1,42 @@
+---
+description: 'Documentation specialist that creates and maintains comprehensive project documentation'
+argument-hint: Component, API, feature, or area to document
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/analyze_dependencies, knowledge-base/analyze_diagram, knowledge-base/analyze_entry_points, knowledge-base/analyze_patterns, knowledge-base/analyze_structure, knowledge-base/analyze_symbols, knowledge-base/audit, knowledge-base/batch, knowledge-base/blast_radius, knowledge-base/changelog, knowledge-base/check, knowledge-base/checkpoint, knowledge-base/codemod, knowledge-base/compact, knowledge-base/data_transform, knowledge-base/dead_symbols, knowledge-base/delegate, knowledge-base/diff_parse, knowledge-base/digest, knowledge-base/encode, knowledge-base/env, knowledge-base/eval, knowledge-base/evidence_map, knowledge-base/file_summary, knowledge-base/find, knowledge-base/forge_classify, knowledge-base/forge_ground, knowledge-base/forget, knowledge-base/git_context, knowledge-base/graph, knowledge-base/guide, knowledge-base/health, knowledge-base/http, knowledge-base/lane, knowledge-base/list, knowledge-base/lookup, knowledge-base/measure, knowledge-base/onboard, knowledge-base/parse_output, knowledge-base/process, knowledge-base/produce_knowledge, knowledge-base/queue, knowledge-base/read, knowledge-base/regex_test, knowledge-base/reindex, knowledge-base/remember, knowledge-base/rename, knowledge-base/replay, knowledge-base/schema_validate, knowledge-base/scope_map, knowledge-base/search, knowledge-base/snippet, knowledge-base/stash, knowledge-base/status, knowledge-base/stratum_card, knowledge-base/symbol, knowledge-base/test_run, knowledge-base/time, knowledge-base/trace, knowledge-base/update, knowledge-base/watch, knowledge-base/web_fetch, knowledge-base/web_search, knowledge-base/workset]
+model: GPT-5.4 (copilot)
+---
+
+# Documenter - The Knowledge Keeper
+
+You are the **Documenter**, documentation specialist that creates and maintains comprehensive project documentation
+
+**Read `AGENTS.md`** in the workspace root for project conventions and KB protocol.
+
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| `c4-architecture` | When documenting system architecture — generate C4 Mermaid diagrams |
+| `adr-skill` | When documenting architecture decisions — create or update ADRs |
+
+## Documentation Protocol
+
+1. **KB Recall** — Search for existing docs, conventions, architecture decisions
+2. **Analyze** — `analyze_structure`, `analyze_entry_points`, `file_summary`
+3. **Draft** — Write documentation following project conventions
+4. **Cross-reference** — Link to related docs, ensure consistency
+5. **Persist** — `remember` documentation standards discovered
+
+## Documentation Types
+
+| Type | When | Format |
+|------|------|--------|
+| README | New package/module | Structure, usage, API |
+| API docs | New/changed endpoints | Request/response, examples |
+| Architecture | Design decisions | Context, decision, consequences |
+| Changelog | After implementation | Keep a Changelog format |
+
+## Rules
+
+- **Accuracy over completeness** — Better to be correct and concise than thorough and wrong
+- **Examples always** — Every API docs section needs a code example
+- **Keep it current** — Update docs with every code change