@ai-coders/context 0.3.1 → 0.4.0

package/README.md

@@ -19,14 +19,14 @@ A lightweight CLI that scaffolds living documentation and AI-agent playbooks for
 - 🤖 `agents/` folder containing playbooks for common engineering agents and a handy index
 - 🔁 Repeatable scaffolding that you can re-run as the project evolves
 - 🧭 Repository-aware templates that highlight top-level directories for quick orientation
-- 🧠 AI-ready front matter and `ai-task` markers so assistants know exactly what to refresh
+- 🧠 AI-ready front matter and `agent-update` markers so assistants know exactly what to refresh
 
 ## 📦 Installation
 
 Use `npx` to run the CLI without installing globally:
 
 ```bash
-npx @ai-coders/context init /path/to/repo
+npx @ai-coders/context
 ```
 
 Or add it to your dev dependencies:
@@ -38,6 +38,10 @@ npm install --save-dev @ai-coders/context
 ## 🚀 Quick Start
 
 ```bash
+# Launch the interactive wizard
+npx @ai-coders/context
+
+
 # Scaffold docs and agents into ./.context
 npx @ai-coders/context init ./my-repo
 
@@ -48,7 +52,7 @@ npx @ai-coders/context init ./my-repo docs
 npx @ai-coders/context init ./my-repo agents --output ./knowledge-base
 
 # Fill docs and agents with the repo context (preview the first 3 updates)
-npx @ai-coders/context fill ./my-repo --output ./.context --dry-run --limit 3
+npx @ai-coders/context fill ./my-repo --output ./.context --limit 3
 
 # Draft a collaboration plan seeded with agent and doc touchpoints
 npx @ai-coders/context plan release-readiness --output ./.context
@@ -79,19 +83,27 @@ Customize the Markdown files to reflect your project’s specifics and commit th
 
 Need help filling in the scaffold? Use [`prompts/update_scaffold_prompt.md`](./prompts/update_scaffold_prompt.md) as the canonical instruction set for any LLM or CLI agent. It walks through:
 
-- Gathering repository context and locating `ai-task`/`ai-slot` markers.
+- Gathering repository context and locating `agent-update`/`agent-fill` markers.
 - Updating documentation sections while satisfying the YAML front matter criteria.
 - Aligning agent playbooks with the refreshed docs and recording evidence for maintainers.
 
 Share that prompt verbatim with your assistant to keep updates consistent across teams.
 
-### Available Doc Keys & Agent Types
+### Available Doc Guides & Agent Types
 
-Pass these values to `--docs` / `--agents` (or pick them interactively):
+The scaffold includes the following guides and playbooks out of the box:
 
 - Docs: `project-overview`, `architecture`, `development-workflow`, `testing-strategy`, `glossary`, `data-flow`, `security`, `tooling`
 - Agents: `code-reviewer`, `bug-fixer`, `feature-developer`, `refactoring-specialist`, `test-writer`, `documentation-writer`, `performance-optimizer`, `security-auditor`, `backend-specialist`, `frontend-specialist`, `architect-specialist`
 
+### AI Marker Reference
+
+- `<!-- agent-update:start:section-id --> … <!-- agent-update:end -->` wrap the sections that AI assistants should rewrite with up-to-date project knowledge.
+- `<!-- agent-fill:slot-id --> … <!-- /agent-fill -->` highlight inline placeholders that must be replaced with concrete details before removing the wrapper.
+- `<!-- agent-readonly:context -->` flags guidance that should remain as-is; treat the adjacent content as instructions rather than editable prose.
+
+When contributing, focus edits inside `agent-update` regions or `agent-fill` placeholders and leave `agent-readonly` guidance untouched unless you have explicit maintainer approval.
+
 ## 🛠 Commands
 
 ### `init`
@@ -106,17 +118,12 @@ Arguments:
 
 Options:
   -o, --output <dir>      Output directory (default: ./.context)
-      --docs <keys...>    Doc keys to scaffold (e.g., project-overview, security)
-      --agents <keys...>  Agent types to scaffold (e.g., code-reviewer, feature-developer)
   --exclude <patterns...> Glob patterns to skip during the scan
   --include <patterns...> Glob patterns to explicitly include
   -v, --verbose           Print detailed progress information
   -h, --help              Display help for command
 ```
 
-### `scaffold`
-Alias for `init`. Use whichever verb fits your workflow.
-
 ### `fill`
 Use an LLM to refresh scaffolded docs and agent playbooks automatically.
 
@@ -126,18 +133,15 @@ Usage: ai-context fill <repo-path>
 Options:
   -o, --output <dir>      Scaffold directory containing docs/ and agents/ (default: ./.context)
   -k, --api-key <key>     API key for the selected LLM provider
-  -m, --model <model>     LLM model to use (default: google/gemini-2.5-flash-preview-05-20)
-  -p, --provider <name>   Provider (openrouter, openai, anthropic, gemini, grok)
+  -m, --model <model>     LLM model to use (default: x-ai/grok-4-fast)
+  -p, --provider <name>   Provider (openrouter only)
+      --base-url <url>    Custom base URL for OpenRouter
       --prompt <file>     Instruction prompt to follow (optional; uses bundled instructions when omitted)
-      --docs <keys...>    Doc keys to update (default: all)
-      --agents <keys...>  Agent types to update (default: all)
-      --dry-run           Preview changes without writing files
-      --all               Process every Markdown file even if no TODO markers remain
       --limit <number>    Maximum number of files to update in one run
   -h, --help              Display help for command
 ```
 
-Under the hood, the command loads the prompt above, scans for `ai-task` or `ai-slot` markers, and asks the LLM to produce the fully updated Markdown. Combine it with `--dry-run` to review responses before committing.
+Under the hood, the command loads the prompt above, iterates over every Markdown file in `.context/docs` and `.context/agents`, and asks the LLM to produce the fully updated content.
 
 ### `plan`
 Create a collaboration plan that links documentation guides and agent playbooks, or fill an existing plan with LLM assistance.
@@ -149,15 +153,13 @@ Options:
   -o, --output <dir>      Scaffold directory containing docs/ and agents/ (default: ./.context)
       --title <title>     Custom title for the plan document
       --summary <text>    Seed the plan with a short summary or goal statement
-      --agents <types...> Agent playbooks to highlight (default: all)
-      --docs <keys...>    Documentation guides to reference (default: all)
   -f, --force             Overwrite the plan if it already exists (scaffold mode)
       --fill              Use an LLM to fill or update the plan instead of scaffolding
   -r, --repo <path>       Repository root to summarize for additional context (fill mode)
   -k, --api-key <key>     API key for the selected LLM provider (fill mode)
-  -m, --model <model>     LLM model to use (default: x-ai/grok-4-fast:free)
-  -p, --provider <name>   Provider (openrouter, openai, anthropic, gemini, grok)
-      --base-url <url>    Custom base URL for provider APIs
+  -m, --model <model>     LLM model to use (default: x-ai/grok-4-fast)
+  -p, --provider <name>   Provider (openrouter only)
+      --base-url <url>    Custom base URL for OpenRouter
       --prompt <file>     Instruction prompt to follow (optional; uses bundled instructions when omitted)
       --dry-run           Preview changes without writing files
       --include <patterns...>  Glob patterns to include during repository analysis

package/dist/generators/agents/agentConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentConfig.d.ts","sourceRoot":"","sources":["../../../src/generators/agents/agentConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CAsE9D,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CA8D5D,CAAC"}
+{"version":3,"file":"agentConfig.d.ts","sourceRoot":"","sources":["../../../src/generators/agents/agentConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CA2F9D,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CAmF5D,CAAC"}

package/dist/generators/agents/agentConfig.js

@@ -70,6 +70,27 @@ exports.AGENT_RESPONSIBILITIES = {
         'Evaluate and recommend technology choices',
         'Plan system scalability and maintainability',
         'Create architectural documentation and diagrams'
+    ],
+    'devops-specialist': [
+        'Design and maintain CI/CD pipelines',
+        'Implement infrastructure as code',
+        'Configure monitoring and alerting systems',
+        'Manage container orchestration and deployments',
+        'Optimize cloud resources and cost efficiency'
+    ],
+    'database-specialist': [
+        'Design and optimize database schemas',
+        'Create and manage database migrations',
+        'Optimize query performance and indexing',
+        'Ensure data integrity and consistency',
+        'Implement backup and recovery strategies'
+    ],
+    'mobile-specialist': [
+        'Develop native and cross-platform mobile applications',
+        'Optimize mobile app performance and battery usage',
+        'Implement mobile-specific UI/UX patterns',
+        'Handle app store deployment and updates',
+        'Integrate push notifications and offline capabilities'
     ]
 };
 exports.AGENT_BEST_PRACTICES = {
@@ -133,6 +154,27 @@ exports.AGENT_BEST_PRACTICES = {
         'Document architectural decisions and rationale',
         'Promote code reusability and modularity',
         'Stay updated on industry trends and technologies'
+    ],
+    'devops-specialist': [
+        'Automate everything that can be automated',
+        'Implement infrastructure as code for reproducibility',
+        'Monitor system health proactively',
+        'Design for failure and implement proper fallbacks',
+        'Keep security and compliance in every deployment'
+    ],
+    'database-specialist': [
+        'Always benchmark queries before and after optimization',
+        'Plan migrations with rollback strategies',
+        'Use appropriate indexing strategies for workloads',
+        'Maintain data consistency across transactions',
+        'Document schema changes and their business impact'
+    ],
+    'mobile-specialist': [
+        'Test on real devices, not just simulators',
+        'Optimize for battery life and data usage',
+        'Follow platform-specific design guidelines',
+        'Implement proper offline-first strategies',
+        'Plan for app store review requirements early'
     ]
 };
 //# sourceMappingURL=agentConfig.js.map

package/dist/generators/agents/agentConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentConfig.js","sourceRoot":"","sources":["../../../src/generators/agents/agentConfig.ts"],"names":[],"mappings":";;;AAEa,QAAA,sBAAsB,GAAgC;IACjE,eAAe,EAAE;QACf,4DAA4D;QAC5D,6CAA6C;QAC7C,yCAAyC;QACzC,+CAA+C;KAChD;IACD,WAAW,EAAE;QACX,wCAAwC;QACxC,gCAAgC;QAChC,oDAAoD;QACpD,yCAAyC;KAC1C;IACD,mBAAmB,EAAE;QACnB,oDAAoD;QACpD,8CAA8C;QAC9C,2CAA2C;QAC3C,iDAAiD;KAClD;IACD,wBAAwB,EAAE;QACxB,oDAAoD;QACpD,+CAA+C;QAC/C,yCAAyC;QACzC,uCAAuC;KACxC;IACD,aAAa,EAAE;QACb,gDAAgD;QAChD,+CAA+C;QAC/C,oCAAoC;QACpC,oCAAoC;KACrC;IACD,sBAAsB,EAAE;QACtB,2CAA2C;QAC3C,+CAA+C;QAC/C,0CAA0C;QAC1C,uCAAuC;KACxC;IACD,uBAAuB,EAAE;QACvB,kCAAkC;QAClC,wCAAwC;QACxC,8BAA8B;QAC9B,oCAAoC;KACrC;IACD,kBAAkB,EAAE;QAClB,mCAAmC;QACnC,mCAAmC;QACnC,yCAAyC;QACzC,+CAA+C;KAChD;IACD,oBAAoB,EAAE;QACpB,+CAA+C;QAC/C,4CAA4C;QAC5C,2CAA2C;QAC3C,4CAA4C;QAC5C,sCAAsC;KACvC;IACD,qBAAqB,EAAE;QACrB,sCAAsC;QACtC,mDAAmD;QACnD,mDAAmD;QACnD,wCAAwC;QACxC,oCAAoC;KACrC;IACD,sBAAsB,EAAE;QACtB,iDAAiD;QACjD,+CAA+C;QAC/C,2CAA2C;QAC3C,6CAA6C;QAC7C,iDAAiD;KAClD;CACF,CAAC;AAEW,QAAA,oBAAoB,GAAgC;IAC/D,eAAe,EAAE;QACf,0CAA0C;QAC1C,wCAAwC;QACxC,0CAA0C;KAC3C;IACD,WAAW,EAAE;QACX,iCAAiC;QACjC,mCAAmC;QACnC,uCAAuC;KACxC;IACD,mBAAmB,EAAE;QACnB,0CAA0C;QAC1C,wCAAwC;QACxC,sCAAsC;KACvC;IACD,wBAAwB,EAAE;QACxB,iCAAiC;QACjC,uCAAuC;QACvC,yCAAyC;KAC1C;IACD,aAAa,EAAE;QACb,6CAA6C;QAC7C,qCAAqC;QACrC,4BAA4B;KAC7B;IACD,sBAAsB,EAAE;QACtB,yCAAyC;QACzC,oCAAoC;QACpC,4BAA4B;KAC7B;IACD,uBAAuB,EAAE;QACvB,2BAA2B;QAC3B,6BAA6B;QAC7B,4CAA4C;KAC7C;IACD,kBAAkB,EAAE;QAClB,gCAAgC;QAChC,wCAAwC;QACxC,2CAA2C;KAC5C;IACD,oBAAoB,EAAE;QACpB,wDAAwD;QACxD,6CAA6C;QAC7C,wDAAwD;QACxD,qDAAqD;QACrD,oDAAoD;KACrD;IACD,qBAAqB,EAAE;QACrB,6CAA6C;QAC7C,gDAAgD;QAChD,wCAAwC;QACxC,8CAA8C;QAC9C,wCAAwC;KACzC;IACD,sBAAsB,EAAE;QACtB,oDAAoD;QACpD,mDAAmD;QACnD,gDAAgD;QAChD,yCAAyC;QACzC,kDAAkD;KACnD;CACF,CAAC"}
+{"version":3,"file":"agentConfig.js","sourceRoot":"","sources":["../../../src/generators/agents/agentConfig.ts"],"names":[],"mappings":"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"}

package/dist/generators/agents/agentGenerator.d.ts

@@ -5,6 +5,5 @@ export declare class AgentGenerator {
     generateAgentPrompts(repoStructure: RepoStructure, outputDir: string, selectedAgentTypes?: string[], verbose?: boolean): Promise<number>;
     private resolveAgentSelection;
     private buildContext;
-    private formatDirectoryList;
 }
 //# sourceMappingURL=agentGenerator.d.ts.map

package/dist/generators/agents/agentGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentGenerator.d.ts","sourceRoot":"","sources":["../../../src/generators/agents/agentGenerator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAe5C,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,cAAc,CA8C7B;gBAEU,GAAG,WAAW,EAAE,OAAO,EAAE;IAG/B,oBAAoB,CACxB,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,EACjB,kBAAkB,CAAC,EAAE,MAAM,EAAE,EAC7B,OAAO,GAAE,OAAe,GACvB,OAAO,CAAC,MAAM,CAAC;IAuBlB,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,mBAAmB;CAO5B"}
+{"version":3,"file":"agentGenerator.d.ts","sourceRoot":"","sources":["../../../src/generators/agents/agentGenerator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAgB5C,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAW7B;gBAEU,GAAG,WAAW,EAAE,OAAO,EAAE;IAG/B,oBAAoB,CACxB,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,EACjB,kBAAkB,CAAC,EAAE,MAAM,EAAE,EAC7B,OAAO,GAAE,OAAe,GACvB,OAAO,CAAC,MAAM,CAAC;IAuBlB,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,YAAY;CAerB"}

package/dist/generators/agents/agentGenerator.js

@@ -38,54 +38,20 @@ const path = __importStar(require("path"));
 const shared_1 = require("../shared");
 const agentTypes_1 = require("./agentTypes");
 const templates_1 = require("./templates");
+const guideRegistry_1 = require("../documentation/guideRegistry");
 class AgentGenerator {
     constructor(..._legacyArgs) {
         this.docTouchpoints = [
             {
                 title: 'Documentation Index',
                 path: '../docs/README.md',
-                marker: 'ai-task:docs-index'
+                marker: 'agent-update:docs-index'
             },
-            {
-                title: 'Project Overview',
-                path: '../docs/project-overview.md',
-                marker: 'ai-task:project-overview'
-            },
-            {
-                title: 'Architecture Notes',
-                path: '../docs/architecture.md',
-                marker: 'ai-task:architecture-notes'
-            },
-            {
-                title: 'Development Workflow',
-                path: '../docs/development-workflow.md',
-                marker: 'ai-task:development-workflow'
-            },
-            {
-                title: 'Testing Strategy',
-                path: '../docs/testing-strategy.md',
-                marker: 'ai-task:testing-strategy'
-            },
-            {
-                title: 'Glossary & Domain Concepts',
-                path: '../docs/glossary.md',
-                marker: 'ai-task:glossary'
-            },
-            {
-                title: 'Data Flow & Integrations',
-                path: '../docs/data-flow.md',
-                marker: 'ai-task:data-flow'
-            },
-            {
-                title: 'Security & Compliance Notes',
-                path: '../docs/security.md',
-                marker: 'ai-task:security'
-            },
-            {
-                title: 'Tooling & Productivity Guide',
-                path: '../docs/tooling.md',
-                marker: 'ai-task:tooling'
-            }
+            ...guideRegistry_1.DOCUMENT_GUIDES.map(guide => ({
+                title: guide.title,
+                path: `../docs/${guide.file}`,
+                marker: guide.marker
+            }))
         ];
     }
     async generateAgentPrompts(repoStructure, outputDir, selectedAgentTypes, verbose = false) {
@@ -126,12 +92,6 @@ class AgentGenerator {
             topLevelDirectories: Array.from(directorySet).sort()
         };
     }
-    formatDirectoryList(topLevelDirectories) {
-        if (topLevelDirectories.length === 0) {
-            return '';
-        }
-        return topLevelDirectories.map(dir => `- \`${dir}/\` — Note why this directory matters for the agent.`).join('\n');
-    }
 }
 exports.AgentGenerator = AgentGenerator;
 //# sourceMappingURL=agentGenerator.js.map

package/dist/generators/agents/agentGenerator.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentGenerator.js","sourceRoot":"","sources":["../../../src/generators/agents/agentGenerator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentGenerator.js","sourceRoot":"","sources":["../../../src/generators/agents/agentGenerator.ts"],"names":[],"mappings":"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"}

package/dist/generators/agents/agentTypes.d.ts

@@ -1,4 +1,4 @@
-export declare const AGENT_TYPES: readonly ["code-reviewer", "bug-fixer", "feature-developer", "refactoring-specialist", "test-writer", "documentation-writer", "performance-optimizer", "security-auditor", "backend-specialist", "frontend-specialist", "architect-specialist"];
+export declare const AGENT_TYPES: readonly ["code-reviewer", "bug-fixer", "feature-developer", "refactoring-specialist", "test-writer", "documentation-writer", "performance-optimizer", "security-auditor", "backend-specialist", "frontend-specialist", "architect-specialist", "devops-specialist", "database-specialist", "mobile-specialist"];
 export type AgentType = typeof AGENT_TYPES[number];
 export declare const IMPORTANT_FILES: string[];
 //# sourceMappingURL=agentTypes.d.ts.map

package/dist/generators/agents/agentTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../../src/generators/agents/agentTypes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,iPAYd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,eAAe,UAI3B,CAAC"}
+{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../../src/generators/agents/agentTypes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,kTAed,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,eAAe,UAI3B,CAAC"}

package/dist/generators/agents/agentTypes.js

@@ -12,7 +12,10 @@ exports.AGENT_TYPES = [
     'security-auditor',
     'backend-specialist',
     'frontend-specialist',
-    'architect-specialist'
+    'architect-specialist',
+    'devops-specialist',
+    'database-specialist',
+    'mobile-specialist'
 ];
 exports.IMPORTANT_FILES = [
     'package.json', 'tsconfig.json', 'webpack.config.js',

package/dist/generators/agents/agentTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentTypes.js","sourceRoot":"","sources":["../../../src/generators/agents/agentTypes.ts"],"names":[],"mappings":";;;AAAa,QAAA,WAAW,GAAG;IACzB,eAAe;IACf,WAAW;IACX,mBAAmB;IACnB,wBAAwB;IACxB,aAAa;IACb,sBAAsB;IACtB,uBAAuB;IACvB,kBAAkB;IAClB,oBAAoB;IACpB,qBAAqB;IACrB,sBAAsB;CACd,CAAC;AAIE,QAAA,eAAe,GAAG;IAC7B,cAAc,EAAE,eAAe,EAAE,mBAAmB;IACpD,gBAAgB,EAAE,oBAAoB,EAAE,WAAW;IACnD,YAAY,EAAE,YAAY,EAAE,oBAAoB;CACjD,CAAC"}
+{"version":3,"file":"agentTypes.js","sourceRoot":"","sources":["../../../src/generators/agents/agentTypes.ts"],"names":[],"mappings":";;;AAAa,QAAA,WAAW,GAAG;IACzB,eAAe;IACf,WAAW;IACX,mBAAmB;IACnB,wBAAwB;IACxB,aAAa;IACb,sBAAsB;IACtB,uBAAuB;IACvB,kBAAkB;IAClB,oBAAoB;IACpB,qBAAqB;IACrB,sBAAsB;IACtB,mBAAmB;IACnB,qBAAqB;IACrB,mBAAmB;CACX,CAAC;AAIE,QAAA,eAAe,GAAG;IAC7B,cAAc,EAAE,eAAe,EAAE,mBAAmB;IACpD,gBAAgB,EAAE,oBAAoB,EAAE,WAAW;IACnD,YAAY,EAAE,YAAY,EAAE,oBAAoB;CACjD,CAAC"}

package/dist/generators/agents/templates/indexTemplate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/agents/templates/indexTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG1C,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAwBzE"}
+{"version":3,"file":"indexTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/agents/templates/indexTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG1C,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAyBzE"}

package/dist/generators/agents/templates/indexTemplate.js

@@ -23,7 +23,8 @@ ${agentEntries}
 
 ## Related Resources
 - [Documentation Index](../docs/README.md)
-- [Contributor Guidelines](../AGENTS.md)
+- [Agent Knowledge Base](../../AGENTS.md)
+- [Contributor Guidelines](../../CONTRIBUTING.md)
 `;
 }
 function formatTitle(agentType) {

package/dist/generators/agents/templates/indexTemplate.js.map

@@ -1 +1 @@
-{"version":3,"file":"indexTemplate.js","sourceRoot":"","sources":["../../../../src/generators/agents/templates/indexTemplate.ts"],"names":[],"mappings":";;AAGA,4CAwBC;AA1BD,gDAAwD;AAExD,SAAgB,gBAAgB,CAAC,UAAgC;IAC/D,MAAM,YAAY,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QACzC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,qBAAqB,GAAG,oCAAsB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,iCAAiC,CAAC;QACrG,OAAO,MAAM,KAAK,OAAO,IAAI,UAAU,qBAAqB,EAAE,CAAC;IACjE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO;;;;;EAKP,YAAY;;;;;;;;;;;CAWb,CAAC;AACF,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,OAAO,SAAS;SACb,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"indexTemplate.js","sourceRoot":"","sources":["../../../../src/generators/agents/templates/indexTemplate.ts"],"names":[],"mappings":";;AAGA,4CAyBC;AA3BD,gDAAwD;AAExD,SAAgB,gBAAgB,CAAC,UAAgC;IAC/D,MAAM,YAAY,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QACzC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,qBAAqB,GAAG,oCAAsB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,iCAAiC,CAAC;QACrG,OAAO,MAAM,KAAK,OAAO,IAAI,UAAU,qBAAqB,EAAE,CAAC;IACjE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO;;;;;EAKP,YAAY;;;;;;;;;;;;CAYb,CAAC;AACF,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,OAAO,SAAS;SACb,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/generators/agents/templates/playbookTemplate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playbookTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/agents/templates/playbookTemplate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,EACpB,mBAAmB,EAAE,MAAM,EAAE,EAC7B,WAAW,EAAE,aAAa,EAAE,GAC3B,MAAM,CA8CR"}
+{"version":3,"file":"playbookTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/agents/templates/playbookTemplate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,EACpB,mBAAmB,EAAE,MAAM,EAAE,EAC7B,WAAW,EAAE,aAAa,EAAE,GAC3B,MAAM,CAkFR"}

package/dist/generators/agents/templates/playbookTemplate.js

@@ -8,10 +8,12 @@ function renderAgentPlaybook(agentType, topLevelDirectories, touchpoints) {
     const responsibilities = agentConfig_1.AGENT_RESPONSIBILITIES[agentType] || ['Clarify this agent\'s responsibilities.'];
     const bestPractices = agentConfig_1.AGENT_BEST_PRACTICES[agentType] || ['Document preferred workflows.'];
     const directoryList = (0, directoryTemplateHelpers_1.formatDirectoryList)(topLevelDirectories);
+    const markerId = `agent-${agentType}`;
     const touchpointList = touchpoints
         .map(tp => `- [${tp.title}](${tp.path}) — ${tp.marker}`)
         .join('\n');
-    return `# ${title} Agent Playbook
+    return `<!-- agent-update:start:${markerId} -->
+# ${title} Agent Playbook
 
 ## Mission
 Describe how the ${title.toLowerCase()} agent supports the team and when to engage it.
@@ -25,7 +27,8 @@ ${formatList(bestPractices)}
 ## Key Project Resources
 - Documentation index: [docs/README.md](../docs/README.md)
 - Agent handbook: [agents/README.md](./README.md)
-- Contributor guide: [AGENTS.md](../AGENTS.md)
+- Agent knowledge base: [AGENTS.md](../../AGENTS.md)
+- Contributor guide: [CONTRIBUTING.md](../../CONTRIBUTING.md)
 
 ## Repository Starting Points
 ${directoryList || '- Add directory highlights relevant to this agent.'}
@@ -33,12 +36,43 @@ ${directoryList || '- Add directory highlights relevant to this agent.'}
 ## Documentation Touchpoints
 ${touchpointList}
 
+<!-- agent-readonly:guidance -->
 ## Collaboration Checklist
 1. Confirm assumptions with issue reporters or maintainers.
 2. Review open pull requests affecting this area.
-3. Update the relevant doc section listed above and remove any resolved \`ai-slot\` placeholders.
+3. Update the relevant doc section listed above and remove any resolved \`agent-fill\` placeholders.
 4. Capture learnings back in [docs/README.md](../docs/README.md) or the appropriate task marker.
 
+## Success Metrics
+Track effectiveness of this agent's contributions:
+- **Code Quality:** Reduced bug count, improved test coverage, decreased technical debt
+- **Velocity:** Time to complete typical tasks, deployment frequency
+- **Documentation:** Coverage of features, accuracy of guides, usage by team
+- **Collaboration:** PR review turnaround time, feedback quality, knowledge sharing
+
+**Target Metrics:**
+- TODO: Define measurable goals specific to this agent (e.g., "Reduce bug resolution time by 30%")
+- TODO: Track trends over time to identify improvement areas
+
+## Troubleshooting Common Issues
+Document frequent problems this agent encounters and their solutions:
+
+### Issue: [Common Problem]
+**Symptoms:** Describe what indicates this problem
+**Root Cause:** Why this happens
+**Resolution:** Step-by-step fix
+**Prevention:** How to avoid in the future
+
+**Example:**
+### Issue: Build Failures Due to Outdated Dependencies
+**Symptoms:** Tests fail with module resolution errors
+**Root Cause:** Package versions incompatible with codebase
+**Resolution:**
+1. Review package.json for version ranges
+2. Run \`npm update\` to get compatible versions
+3. Test locally before committing
+**Prevention:** Keep dependencies updated regularly, use lockfiles
+
 ## Hand-off Notes
 Summarize outcomes, remaining risks, and suggested follow-up actions after the agent completes its work.
 
@@ -46,6 +80,8 @@ Summarize outcomes, remaining risks, and suggested follow-up actions after the a
 - Reference commits, issues, or ADRs used to justify updates.
 - Command output or logs that informed recommendations.
 - Follow-up items for maintainers or future agent runs.
+- Performance metrics and benchmarks where applicable.
+<!-- agent-update:end -->
 `;
 }
 function formatTitle(agentType) {

package/dist/generators/agents/templates/playbookTemplate.js.map

@@ -1 +1 @@
-{"version":3,"file":"playbookTemplate.js","sourceRoot":"","sources":["../../../../src/generators/agents/templates/playbookTemplate.ts"],"names":[],"mappings":";;AAKA,kDAkDC;AAvDD,gDAA8E;AAE9E,oFAA4E;AAG5E,SAAgB,mBAAmB,CACjC,SAAoB,EACpB,mBAA6B,EAC7B,WAA4B;IAE5B,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,gBAAgB,GAAG,oCAAsB,CAAC,SAAS,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IAC1G,MAAM,aAAa,GAAG,kCAAoB,CAAC,SAAS,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;IAC3F,MAAM,aAAa,GAAG,IAAA,8CAAmB,EAAC,mBAAmB,CAAC,CAAC;IAE/D,MAAM,cAAc,GAAG,WAAW;SAC/B,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC;SACvD,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO,KAAK,KAAK;;;mBAGA,KAAK,CAAC,WAAW,EAAE;;;EAGpC,UAAU,CAAC,gBAAgB,CAAC;;;EAG5B,UAAU,CAAC,aAAa,CAAC;;;;;;;;EAQzB,aAAa,IAAI,oDAAoD;;;EAGrE,cAAc;;;;;;;;;;;;;;;CAef,CAAC;AACF,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,OAAO,SAAS;SACb,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,KAAe;IACjC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,6BAA6B,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"playbookTemplate.js","sourceRoot":"","sources":["../../../../src/generators/agents/templates/playbookTemplate.ts"],"names":[],"mappings":";;AAKA,kDAsFC;AA3FD,gDAA8E;AAE9E,oFAA4E;AAG5E,SAAgB,mBAAmB,CACjC,SAAoB,EACpB,mBAA6B,EAC7B,WAA4B;IAE5B,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,gBAAgB,GAAG,oCAAsB,CAAC,SAAS,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IAC1G,MAAM,aAAa,GAAG,kCAAoB,CAAC,SAAS,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;IAC3F,MAAM,aAAa,GAAG,IAAA,8CAAmB,EAAC,mBAAmB,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,SAAS,SAAS,EAAE,CAAC;IAEtC,MAAM,cAAc,GAAG,WAAW;SAC/B,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC;SACvD,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO,2BAA2B,QAAQ;IACxC,KAAK;;;mBAGU,KAAK,CAAC,WAAW,EAAE;;;EAGpC,UAAU,CAAC,gBAAgB,CAAC;;;EAG5B,UAAU,CAAC,aAAa,CAAC;;;;;;;;;EASzB,aAAa,IAAI,oDAAoD;;;EAGrE,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDf,CAAC;AACF,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB;IACpC,OAAO,SAAS;SACb,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,KAAe;IACjC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,6BAA6B,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC"}

package/dist/generators/documentation/documentationGenerator.d.ts

@@ -3,11 +3,13 @@ interface DocumentationGenerationConfig {
     selectedDocs?: string[];
 }
 export declare class DocumentationGenerator {
-    private readonly guides;
     constructor(..._legacyArgs: unknown[]);
     generateDocumentation(repoStructure: RepoStructure, outputDir: string, config?: DocumentationGenerationConfig, verbose?: boolean): Promise<number>;
     private buildContext;
+    private deriveTopLevelDirectories;
     private getDocSections;
+    private updateAgentGuideReferences;
+    private createDefaultAgentGuide;
 }
 export {};
 //# sourceMappingURL=documentationGenerator.d.ts.map

package/dist/generators/documentation/documentationGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documentationGenerator.d.ts","sourceRoot":"","sources":["../../../src/generators/documentation/documentationGenerator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAsB5C,UAAU,6BAA6B;IACrC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAE3C,GAAG,WAAW,EAAE,OAAO,EAAE;IAE/B,qBAAqB,CACzB,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,6BAAkC,EAC1C,OAAO,GAAE,OAAe,GACvB,OAAO,CAAC,MAAM,CAAC;IAmBlB,OAAO,CAAC,YAAY;IA+BpB,OAAO,CAAC,cAAc;CAiCvB"}
+{"version":3,"file":"documentationGenerator.d.ts","sourceRoot":"","sources":["../../../src/generators/documentation/documentationGenerator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAsB5C,UAAU,6BAA6B;IACrC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,qBAAa,sBAAsB;gBACrB,GAAG,WAAW,EAAE,OAAO,EAAE;IAE/B,qBAAqB,CACzB,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,6BAAkC,EAC1C,OAAO,GAAE,OAAe,GACvB,OAAO,CAAC,MAAM,CAAC;IAqBlB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,yBAAyB;IAWjC,OAAO,CAAC,cAAc;YAkCR,0BAA0B;IAgCxC,OAAO,CAAC,uBAAuB;CA0ChC"}

package/dist/generators/documentation/documentationGenerator.js

@@ -35,13 +35,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DocumentationGenerator = void 0;
 const path = __importStar(require("path"));
+const fs = __importStar(require("fs-extra"));
 const shared_1 = require("../shared");
 const templates_1 = require("./templates");
 const guideRegistry_1 = require("./guideRegistry");
 class DocumentationGenerator {
-    constructor(..._legacyArgs) {
-        this.guides = guideRegistry_1.DOCUMENT_GUIDES;
-    }
+    constructor(..._legacyArgs) { }
     async generateDocumentation(repoStructure, outputDir, config = {}, verbose = false) {
         const docsDir = path.join(outputDir, 'docs');
         await shared_1.GeneratorUtils.ensureDirectoryAndLog(docsDir, verbose, 'Generating documentation scaffold in');
@@ -55,21 +54,20 @@ class DocumentationGenerator {
             await shared_1.GeneratorUtils.writeFileWithLogging(targetPath, content, verbose, `Created ${section.fileName}`);
             created += 1;
         }
+        await this.updateAgentGuideReferences(repoStructure, verbose);
         return created;
     }
     buildContext(repoStructure, guides) {
-        const directorySet = new Set();
-        repoStructure.directories.forEach(dir => {
-            const [firstSegment] = dir.relativePath.split(/[\\/]/).filter(Boolean);
-            if (firstSegment) {
-                directorySet.add(firstSegment);
-            }
-        });
-        const topLevelDirectories = Array.from(directorySet).sort();
-        const directoryStats = topLevelDirectories.map(name => ({
-            name,
-            fileCount: repoStructure.files.filter(file => file.relativePath.startsWith(`${name}/`)).length
-        }));
+        const topLevelStats = repoStructure.topLevelDirectoryStats ?? [];
+        const topLevelDirectories = topLevelStats.length
+            ? topLevelStats.map(stat => stat.name)
+            : this.deriveTopLevelDirectories(repoStructure);
+        const directoryStats = topLevelStats.length
+            ? topLevelStats.map(stat => ({ name: stat.name, fileCount: stat.fileCount }))
+            : topLevelDirectories.map(name => ({
+                name,
+                fileCount: repoStructure.files.filter(file => file.relativePath.startsWith(`${name}/`)).length
+            }));
         const primaryLanguages = shared_1.GeneratorUtils.getTopFileExtensions(repoStructure, 5)
             .filter(([ext]) => !!ext)
             .map(([extension, count]) => ({ extension, count }));
@@ -81,6 +79,16 @@ class DocumentationGenerator {
             guides
         };
     }
+    deriveTopLevelDirectories(repoStructure) {
+        const directorySet = new Set();
+        repoStructure.directories.forEach(dir => {
+            const [firstSegment] = dir.relativePath.split(/[\\/]/).filter(Boolean);
+            if (firstSegment) {
+                directorySet.add(firstSegment);
+            }
+        });
+        return Array.from(directorySet).sort();
+    }
     getDocSections(guides) {
         const sections = [
             {
@@ -110,6 +118,71 @@ class DocumentationGenerator {
         });
         return sections;
     }
+    async updateAgentGuideReferences(repoStructure, verbose) {
+        const repoRoot = repoStructure.rootPath;
+        const agentGuidePath = path.join(repoRoot, 'AGENTS.md');
+        try {
+            const exists = await fs.pathExists(agentGuidePath);
+            if (!exists) {
+                const template = this.createDefaultAgentGuide(repoStructure);
+                await fs.writeFile(agentGuidePath, template, 'utf-8');
+                shared_1.GeneratorUtils.logProgress('Created AGENTS.md using the agents.md example starter.', verbose);
+                return;
+            }
+            const content = await fs.readFile(agentGuidePath, 'utf-8');
+            const docsReference = '.context/docs/README.md';
+            const agentsReference = '.context/agents/README.md';
+            if (content.includes(docsReference) && content.includes(agentsReference)) {
+                return;
+            }
+            const referencesBlock = `\n## AI Context References\n- Documentation index: \`${docsReference}\`\n- Agent playbooks: \`${agentsReference}\`\n`;
+            const updatedContent = `${content.trimEnd()}${referencesBlock}\n`;
+            await fs.writeFile(agentGuidePath, updatedContent, 'utf-8');
+            shared_1.GeneratorUtils.logProgress('Linked AGENTS.md to generated docs and agent indexes.', verbose);
+        }
+        catch (error) {
+            shared_1.GeneratorUtils.logError('Failed to update AGENTS.md with documentation references', error, verbose);
+        }
+    }
+    createDefaultAgentGuide(repoStructure) {
+        const directories = (repoStructure.topLevelDirectoryStats?.length
+            ? repoStructure.topLevelDirectoryStats.map(stat => stat.name)
+            : this.deriveTopLevelDirectories(repoStructure)).filter(Boolean);
+        const directorySection = directories.length
+            ? directories
+                .slice(0, 8)
+                .map(dir => `- \`${dir}/\` — explain what lives here and when agents should edit it.`)
+                .join('\n')
+            : '- Document the major directories so agents know where to work.';
+        return `# AGENTS.md
+
+## Dev environment tips
+- Install dependencies with \`npm install\` before running scaffolds.
+- Use \`npm run dev\` for the interactive TypeScript session that powers local experimentation.
+- Run \`npm run build\` to refresh the CommonJS bundle in \`dist/\` before shipping changes.
+- Store generated artefacts in \`.context/\` so reruns stay deterministic.
+
+## Testing instructions
+- Execute \`npm run test\` to run the Jest suite.
+- Append \`-- --watch\` while iterating on a failing spec.
+- Trigger \`npm run build && npm run test\` before opening a PR to mimic CI.
+- Add or update tests alongside any generator or CLI changes.
+
+## PR instructions
+- Follow Conventional Commits (for example, \`feat(scaffolding): add doc links\`).
+- Cross-link new scaffolds in \`docs/README.md\` and \`agents/README.md\` so future agents can find them.
+- Attach sample CLI output or generated markdown when behaviour shifts.
+- Confirm the built artefacts in \`dist/\` match the new source changes.
+
+## Repository map
+${directorySection}
+
+## AI Context References
+- Documentation index: \`.context/docs/README.md\`
+- Agent playbooks: \`.context/agents/README.md\`
+- Contributor guide: \`CONTRIBUTING.md\`
+`;
+    }
 }
 exports.DocumentationGenerator = DocumentationGenerator;
 //# sourceMappingURL=documentationGenerator.js.map