@agent-smith/feat-agents 0.0.1 → 0.0.2

package/dist/skills/update-codebase-summary/SKILL.md

@@ -1,20 +1,21 @@
 ---
 name: update-codebase-summary
-description: use when asked to create or update the codebase summary documentation
+description: use when asked to create or update the codebase summary documentation for a module or package
 ---
 
-This skill describes the workflow to create or update a codebase documentation file (`[project-path].agents/documentation/codebase-summary.md`).
+This skill describes the workflow to create or update a codebase summary file (`.agents/documentation/codebase-summary.md`) for any module, package, or repository.
 
 ## Workflow
 
-1. **Explore the project** — Walk the directory tree, identify package/module boundaries, read manifest files (e.g., `package.json`), locate entry points, and understand inter-module dependencies.
+1. **Explore the module** — Walk the directory tree, identify entry points, read manifest files (e.g., `package.json`, `setup.py`, `Cargo.toml`), locate key source files, and understand dependencies.
 
-2. **Check for existing file** — Look for `[project-path].agents/documentation/codebase-summary.md` in the project directory. If it exists, update it. If not, create it.
+2. **Check for existing file** — Look for `.agents/documentation/codebase-summary.md` in the module directory. If it exists, update it. If not, create it.
 
 3. **Write the file** using exactly these 7 sections in this order:
 
 ### Section Format
 
+```markdown
 # <module-name>
 
 ## Summary
@@ -40,5 +41,12 @@ One sentence: what the module does and why it exists.
 
 ## Related
 - See `<related-module>` — how they work together
+```
 
-Keep the file as short and condensed as possible
+## Rules
+
+- **Preserve format**: The 7-section structure is standardized — do not change it
+- **Information-dense**: Keep the file short and condensed
+- **No project description**: That belongs in `project-overview.md`
+- **No architecture patterns duplicated from project-nav.md**
+- **Language-agnostic**: Adapt to the project's language and ecosystem

package/dist/skills/update-project-nav/SKILL.md

@@ -11,8 +11,8 @@ This skill describes the workflow to update the project navigation map file (`.a
 
 2. **Detect changes** — Walk the directory tree, identify what has changed since the last update:
    - New/removed repos or packages
-   - New/modified plugins
-   - UI component changes
+   - New/modified modules or components
+   - UI/frontend changes (if applicable)
    - New documentation files
    - Architecture changes (new patterns, dependencies)
 
@@ -21,9 +21,9 @@ This skill describes the workflow to update the project navigation map file (`.a
 ### Section Update Rules
 
 #### 1. Project Overview
-- Update the repos table if repos are added/removed/renamed
+- Update the repos/modules table if components are added/removed/renamed
 - Update the purpose descriptions if functionality changes
-- Keep the 4-column table format: `| Repo | Path | Purpose |`
+- Keep the table format: `| Repo | Path | Purpose |`
 
 #### 2. Architecture Principles
 - Add new principles when architectural patterns emerge
@@ -36,35 +36,35 @@ This skill describes the workflow to update the project navigation map file (`.a
 - Update the prose explanation below the graph
 - Keep the visual format consistent (boxes, arrows, labels)
 
-#### 4. Runtime Packages
-- Add new packages with: Purpose, Key files, Key types/classes
+#### 4. Packages/Modules
+- Add new packages/modules with: Purpose, Key files, Key types/classes
 - Update existing packages if API changes
 - Remove deprecated packages
-- Format: `### @agent-smith/<name> — <short description>` followed by bullet points
+- Format: `### <module-name> — <short description>` followed by bullet points
 
-#### 5. Server
-- Update route table with new/changed routes
+#### 5. Server/API (if applicable)
+- Update route/endpoint tables with new/changed routes
 - Add new handler files
-- Update patterns if confirmation/async flow changes
+- Update patterns if async flow changes
 
-#### 6. Plugins
-- Add new plugins to the table
-- Update plugin categories if reorganized
+#### 6. Plugins/Extensions (if applicable)
+- Add new plugins/extensions to the table
+- Update categories if reorganized
 - Keep format: `| Plugin | Category | Purpose | Key File(s) |`
 
-#### 7. UI
+#### 7. UI/Frontend (if applicable)
 - Update component/service tables
 - Add new themes, apps, or extensions
-- Note any architectural changes (Vue version, PrimeVue updates)
+- Note any architectural changes (framework version updates)
 
-#### 8. Apps
-- Document new apps added to the dashboard
+#### 8. Apps/Extensions (if applicable)
+- Document new apps added to the project
 - Update existing app descriptions if functionality changes
 
 #### 9. Code Snippets
 - Add new patterns for new APIs or features
 - Update existing snippets if API signatures change
-- Keep language-appropriate examples (YAML, JS, TS)
+- Keep language-appropriate examples
 
 #### 10. Navigation Quick Reference
 - Add new task→path mappings
@@ -86,7 +86,7 @@ This skill describes the workflow to update the project navigation map file (`.a
    - Per-module technical details (entry points, key files, dependencies) live in `codebase-summary.md`
    - No redundancy between files
 
-5. **Write the updated file** — Preserve the header note: `> **Purpose**: Single-reference map for AI coding agents...`
+5. **Write the updated file** — Preserve the header note: `> **Purpose**: Single-reference map for AI coding agents to understand, navigate, and modify the <Project Name> codebase.`
 
 ## Rules
 
@@ -95,3 +95,4 @@ This skill describes the workflow to update the project navigation map file (`.a
 - **Preserve format**: Do not change section structure or table formats
 - **Canonical source**: `project-nav.md` is the single source of truth for project overview, architecture, and navigation
 - **Language-agnostic**: Adapt to the project's language and ecosystem
+- **Include only applicable sections**: Server, Plugins, UI, and Apps sections are optional — include only if the project has them

package/dist/tasks/update-project-doc/goals.md

@@ -0,0 +1,27 @@
+# Goals and Success Criteria: update-project-doc
+
+## Primary Goal
+Create or update AI agent navigation documentation for a project. Generate standardized doc files that help AI agents understand, navigate, and work within the codebase.
+
+## Success Criteria
+- [ ] AGENTS.md created at project root with mission, conventions, quick start, and doc links
+- [ ] AGENTS.md created in each repo (multi-repo projects) with localized context
+- [ ] decision-tree.md created at project root with task-to-doc mapping
+- [ ] project-overview.md created at project root (~1 page overview)
+- [ ] codebase-summary.md created for every repo/module with 7-section format
+- [ ] project-nav.md created at project root with comprehensive navigation map
+- [ ] All files cross-reference each other correctly
+- [ ] No duplicated content across files — each piece of info lives in exactly one file
+
+## Files Modified
+- `AGENTS.md` — Project root index with mission, conventions, quick start
+- `<repo>/AGENTS.md` — Per-repo index with localized context (multi-repo only)
+- `.agents/documentation/decision-tree.md` — Quick guide for agents to find the right doc
+- `.agents/documentation/project-overview.md` — Concise project overview (~1 page)
+- `.agents/documentation/codebase-summary.md` — Technical summary per repo/module
+- `.agents/documentation/project-nav.md` — Comprehensive navigation map
+
+## Exclusions
+- Does not create package-level documentation for docsite (use `document-package` skill)
+- Does not regenerate the documentation map script (use `update-doc-map` skill)
+- Not for adding new features or modifying code

package/dist/tasks/update-project-doc/notes.md

@@ -0,0 +1,35 @@
+# Notes: update-project-doc
+
+## Context
+This task was created from the `create-project-docs` skill. It standardizes the process of creating AI agent navigation documentation for any project.
+
+## Source Skill
+- Original skill: `/workspace/agent-smith-plugins/agents/dist/skills/create-project-docs/SKILL.md`
+
+## Key Rules to Remember
+- **No redundancy**: Each piece of information lives in exactly one file
+- **codebase-summary.md core format**: 7 sections (Summary, Dependencies, Used By, Entry Point, Key Files, Architecture, Related) — do not change order or rename
+- **Information-dense**: Keep files short. Use tables, bullets, one-line descriptions
+- **project-nav.md is canonical**: Single source of truth for project overview, architecture, snippets, quick references
+- **decision-tree.md first**: Always the first file agents should read to find the right doc
+- **Language-agnostic**: Adapt examples and conventions to the project's language
+
+## Multi-Repo vs Single-Repo
+- **Single-repo projects**: All 5 files (AGENTS.md, decision-tree.md, project-overview.md, project-nav.md, codebase-summary.md) live at the project root
+- **Multi-repo projects**: 
+  - Workspace root: AGENTS.md, decision-tree.md, project-overview.md, project-nav.md
+  - Each repo: its own AGENTS.md (localized context) and codebase-summary.md
+  - Per-repo AGENTS.md structure: Mission, Structure (key dirs), Conventions (repo-specific), Quick Start, Documentation (links to local docs + root AGENTS.md)
+
+## Related Skills (to load during execution)
+| Skill | When to Use |
+|-------|-------------|
+| `smart-explore` | Phase 1 — explore project with exclusion patterns to avoid reading noise (node_modules, etc.) |
+| `update-codebase-summary` | Phase 5 — create/update each module's codebase-summary.md |
+| `update-project-nav` | Phase 6 — create/update project-nav.md |
+
+## Optional Sections (include only when they add value)
+- decision-tree.md: "I need to work on a specific package" for monorepos
+- project-overview.md: "Runtime Packages" table for monorepos
+- codebase-summary.md: "Documentation" section — project root only
+- project-nav.md: Server, Plugins, UI, Apps sections

package/dist/tasks/update-project-doc/plan.md

@@ -0,0 +1,212 @@
+# Task Plan: update-project-doc
+
+## Phase 1: Explore the Project
+**Goal:** Understand the project structure, identify repos/packages, entry points, dependencies, and key conventions.
+
+### Step 1.0: Load smart-explore Skill
+- **File:** N/A
+- **Action:** Load the `smart-explore` skill to get standardized exploration workflow with exclusion patterns
+- **Verify:** Skill loaded successfully
+
+### Step 1.05: Check Recent Changes
+- **For each repository in the project**, cd into its directory and run git commands (each repo has its own `.git`):
+  - `cd /path/to/repo && git log --oneline -10` to see recent commits
+  - `git diff HEAD~10` to identify code changes in that repo
+- Repeat for every repo (e.g., `agent-smith`, `agent-smith-plugins`, `agent-smith-ui`, etc.)
+- Focus exploration on modified files identified in the diffs
+- **Verify:**
+  - [ ] Git commands run in each repo directory separately
+  - [ ] Recent commits reviewed for all repos
+  - [ ] Changed files cataloged per repo
+  - [ ] New/modified types, interfaces, or features identified
+
+### Step 1.1: Walk Directory Tree (with exclusions)
+- **File:** N/A (exploration)
+- **Action:** Follow the `smart-explore` skill: detect project type, read `.gitignore`, walk directory tree with default exclusions (node_modules, .git, dist, build, vendor, __pycache__, etc.)
+- **Verify:** List of all repos/packages with their paths and purposes documented; no noise directories in results
+
+### Step 1.2: Read Manifest Files
+- **File:** N/A (exploration)
+- **Action:** For each repo/package discovered, read its manifest file (package.json, pyproject.toml, Cargo.toml, etc.) to understand dependencies and structure
+- **Verify:** All packages identified with their manifest files read
+
+### Step 1.3: Identify Conventions
+- **File:** N/A (exploration)
+- **Action:** Identify key conventions and patterns used by the project (tool formats, file structures, state management, coordinator patterns, etc.)
+- **Verify:** 3-5 key conventions identified and documented for reference
+
+---
+
+## Phase 2: Create AGENTS.md (Project Root)
+**Goal:** Create the root index file with mission, conventions, quick start, and doc links.
+
+### Step 2.1: Write AGENTS.md Structure
+- **File:** `AGENTS.md` at project root
+- **Action:** Create AGENTS.md with exact structure:
+  - `# <Project Name>` header
+  - `## Mission` — One-line mission statement
+  - `## Repositories` — Table with repo name, path, purpose
+  - `## Conventions (for AI Agents)` — 3-5 key patterns
+  - `## Quick Start for AI Agents` — Always: decision-tree → project-overview → project-nav → codebase-summary
+  - `## Documentation` — List all doc files with descriptions
+- **Verify:** File exists at project root with all required sections; mission is one concise sentence; conventions list 3-5 patterns
+
+### Step 2.2: Validate AGENTS.md
+- **File:** `AGENTS.md`
+- **Action:** Review that all repos are listed, conventions are clear for AI agents, quick start references decision-tree.md first
+- **Verify:** All sections present and complete; cross-references point to correct files
+
+---
+
+## Phase 3: Create Per-Repo AGENTS.md (Multi-Repo Projects Only)
+**Goal:** Create an AGENTS.md file in each repository so agents navigating directly to a repo have localized context.
+
+### Step 3.1: Write Per-Repo AGENTS.md
+- **File:** `<repo>/AGENTS.md` for each repo (skip for single-repo projects)
+- **Action:** For each repo, create AGENTS.md with structure:
+  - `# <Repo Name>` header
+  - `## Mission` — One-line mission statement for this specific repo
+  - `## Structure` — Table of key directories and their purposes
+  - `## Conventions` — Repo-specific conventions (subset of or additions to root conventions)
+  - `## Quick Start` — Steps: read codebase-summary.md → explore key files → run/build
+  - `## Documentation` — Links to this repo's docs: `.agents/documentation/codebase-summary.md`, and link back to root `../../AGENTS.md` for project-wide context
+- **Verify:** Each repo has its own AGENTS.md; all sections present; links to root AGENTS.md exist
+
+### Step 3.2: Validate Per-Repo AGENTS.md
+- **File:** All `<repo>/AGENTS.md` files
+- **Action:** Ensure each file is self-contained for agents working in that repo; cross-references to root docs are correct; no duplicated content from root AGENTS.md
+- **Verify:** All repos covered; content is repo-specific; links valid
+
+---
+
+## Phase 4: Create decision-tree.md (Project Root Only)
+**Goal:** Create a quick guide helping agents find the right documentation based on their task.
+
+### Step 4.1: Write decision-tree.md
+- **File:** `.agents/documentation/decision-tree.md` at project root
+- **Action:** Create with structure:
+  - `# Documentation Decision Tree` header with intro note
+  - `## I need to understand the project` — Links to overview, nav, summary
+  - `## I need to work on a specific repo/package` — Per-repo paths
+  - Optional: `## I need to work on a specific package` for monorepos
+  - `## I need detailed documentation` — Topic-to-path mapping
+  - `## Common Tasks (Quick Reference)` — Table of tasks → paths
+  - `## Conventions` — Brief reference linking to AGENTS.md
+- **Verify:** File exists with all sections; ends with link to AGENTS.md for full conventions
+
+### Step 4.2: Validate decision-tree.md
+- **File:** `.agents/documentation/decision-tree.md`
+- **Action:** Ensure all doc files are referenced; Common Tasks table is populated; references AGENTS.md at end
+- **Verify:** All paths correct; no broken references
+
+---
+
+## Phase 5: Create project-overview.md (Project Root Only)
+**Goal:** Create a concise ~1 page overview of the project.
+
+### Step 5.1: Write project-overview.md
+- **File:** `.agents/documentation/project-overview.md` at project root
+- **Action:** Create with structure:
+  - Header with `> Role:` note and `> See also:` references to decision-tree.md and project-nav.md
+  - `## What is <Project Name>?` — One paragraph description
+  - `## Core Capabilities` — Bullet list of capabilities
+  - `## Repository Structure` — Table of repos
+  - Optional: `## Runtime Packages` for monorepos
+  - `## Key Architecture Patterns` — Bullet list
+  - `## Quick Reference: Common Tasks` — Task-to-path table
+  - `## Code Snippets` — Typical usage examples
+  - `## Documentation Links` — Resource table
+- **Verify:** File is ~1 page; all sections present; header notes reference decision-tree.md and project-nav.md
+
+### Step 5.2: Validate project-overview.md
+- **File:** `.agents/documentation/project-overview.md`
+- **Action:** Ensure content is concise; code snippets show typical usage; no duplicated content from other files
+- **Verify:** File fits ~1 page; cross-references correct; no redundancy with project-nav.md
+
+---
+
+## Phase 6: Create codebase-summary.md (Every Repo/Module)
+**Goal:** Create standardized technical summaries for each repo/module using the `update-codebase-summary` skill.
+
+### Step 6.1: Load update-codebase-summary Skill
+- **File:** N/A
+- **Action:** Load the `update-codebase-summary` skill to get the standardized 7-section format
+- **Verify:** Skill loaded successfully
+
+### Step 6.2: Create codebase-summary.md for Each Repo
+- **File:** `<repo>/.agents/documentation/codebase-summary.md` for each repo/module
+- **Action:** For each repo/module, create codebase-summary.md with 7 core sections:
+  1. Summary
+  2. Dependencies
+  3. Used By
+  4. Entry Point
+  5. Key Files
+  6. Architecture
+  7. Related
+- **Note:** Include optional "Documentation" section ONLY in the project root codebase-summary.md — omit from per-repo summaries
+- **Verify:** Each repo has a codebase-summary.md with all 7 sections; no Documentation section in per-repo files
+
+### Step 6.3: Validate All codebase-summary.md Files
+- **File:** All `.agents/documentation/codebase-summary.md` files
+- **Action:** Verify each file follows the standardized format; Related section points to correct modules
+- **Verify:** All repos covered; sections in correct order; no renamed sections
+
+---
+
+## Phase 7: Create project-nav.md (Project Root Only)
+**Goal:** Create comprehensive navigation map using the `update-project-nav` skill.
+
+### Step 7.1: Load update-project-nav Skill
+- **File:** N/A
+- **Action:** Load the `update-project-nav` skill to get required and optional sections
+- **Verify:** Skill loaded successfully
+
+### Step 7.2: Create project-nav.md
+- **File:** `.agents/documentation/project-nav.md` at project root
+- **Action:** Create with required sections:
+  - Header note: `> Purpose: Single-reference map for AI coding agents...`
+  - `## Project Overview`
+  - `## Architecture Principles`
+  - `## Dependency Graph`
+  - `## Packages/Modules`
+  - `## Code Snippets`
+  - `## Navigation Quick Reference`
+  - `## Documentation Links`
+  - `## Key Conventions & Patterns`
+  - Optional sections (Server, Plugins, UI, Apps) — include only if applicable; number sequentially skipping omitted ones
+- **Verify:** File exists with all required sections; header note present; sections numbered correctly
+
+### Step 7.3: Validate project-nav.md
+- **File:** `.agents/documentation/project-nav.md`
+- **Action:** Ensure it's the canonical source for overview, architecture, snippets, quick references; no external cross-references needed
+- **Verify:** All sections complete; optional sections included only when they add value
+
+---
+
+## Phase 8: Cross-Reference and Verify
+**Goal:** Ensure all files cross-reference correctly and no content is duplicated.
+
+### Step 8.1: Verify Cross-References
+- **File:** All doc files
+- **Action:** Check cross-references:
+  - Root `AGENTS.md` → links to decision-tree.md, project-overview.md, project-nav.md, codebase-summary.md, and per-repo AGENTS.md files
+  - Per-repo `AGENTS.md` → links to local codebase-summary.md; links back to root `../../AGENTS.md` for project-wide context
+  - `decision-tree.md` → references all doc files; ends with link to root AGENTS.md
+  - `project-overview.md` → header notes reference decision-tree.md and project-nav.md
+  - `codebase-summary.md` → Related section points to related modules
+  - `project-nav.md` → no external cross-references needed
+- **Verify:** All cross-references exist and point to correct files
+
+### Step 8.2: Check for Duplicated Content
+- **File:** All doc files
+- **Action:** Ensure no redundancy:
+  - Project description, architecture patterns, snippets, quick-reference tables → ONLY in project-nav.md and project-overview.md
+  - Per-module technical details → ONLY in codebase-summary.md
+  - Conventions summary → ONLY in AGENTS.md; decision-tree.md references it
+  - Per-repo context → ONLY in per-repo AGENTS.md files
+- **Verify:** No duplicated content across files
+
+### Step 8.3: Final Review
+- **File:** All doc files
+- **Action:** Confirm all success criteria from goals.md are met
+- **Verify:** All checkboxes in goals.md can be marked complete

package/dist/tasks/update-project-doc/state.md

@@ -0,0 +1,42 @@
+# Task State: update-project-doc
+
+## Status: planned
+
+## Phases
+- [ ] Phase 1: Explore the Project
+  - [ ] Step 1.0: Load smart-explore Skill
+  - [ ] Step 1.1: Walk Directory Tree (with exclusions)
+  - [ ] Step 1.2: Read Manifest Files
+  - [ ] Step 1.3: Identify Conventions
+- [ ] Phase 2: Create AGENTS.md (Project Root)
+  - [ ] Step 2.1: Write AGENTS.md Structure
+  - [ ] Step 2.2: Validate AGENTS.md
+- [ ] Phase 3: Create Per-Repo AGENTS.md (Multi-Repo Projects Only)
+  - [ ] Step 3.1: Write Per-Repo AGENTS.md
+  - [ ] Step 3.2: Validate Per-Repo AGENTS.md
+- [ ] Phase 4: Create decision-tree.md (Project Root Only)
+  - [ ] Step 4.1: Write decision-tree.md
+  - [ ] Step 4.2: Validate decision-tree.md
+- [ ] Phase 5: Create project-overview.md (Project Root Only)
+  - [ ] Step 5.1: Write project-overview.md
+  - [ ] Step 5.2: Validate project-overview.md
+- [ ] Phase 6: Create codebase-summary.md (Every Repo/Module)
+  - [ ] Step 6.1: Load update-codebase-summary Skill
+  - [ ] Step 6.2: Create codebase-summary.md for Each Repo
+  - [ ] Step 6.3: Validate All codebase-summary.md Files
+- [ ] Phase 7: Create project-nav.md (Project Root Only)
+  - [ ] Step 7.1: Load update-project-nav Skill
+  - [ ] Step 7.2: Create project-nav.md
+  - [ ] Step 7.3: Validate project-nav.md
+- [ ] Phase 8: Cross-Reference and Verify
+  - [ ] Step 8.1: Verify Cross-References
+  - [ ] Step 8.2: Check for Duplicated Content
+  - [ ] Step 8.3: Final Review
+
+## Notes
+- Read `notes.md` for additional context, rules, and related skills
+- Next: Phase 1, Step 1.1
+- This task creates documentation to help AI agents navigate a codebase
+- Execute phases in order — each phase depends on the previous one
+- Load `update-codebase-summary` skill during Phase 5
+- Load `update-project-nav` skill during Phase 6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-smith/feat-agents",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "AI agents for Agent Smith",
   "repository": "https://github.com/lynxai-team/agent-smith-plugins",
   "type": "module",

package/dist/skills/update-doc-map/SKILL.md

@@ -1,8 +0,0 @@
----
-name: update-doc-map
-description: read this only when instructed to update the documentation map
----
-
-Run the `agent-smith-plugins/agents/dist/skills/update-doc-map/scripts/generate-doc-map.mjs` Nodejs script.
-
-Report only the end result: if the script has run ok or not.

package/dist/skills/update-doc-map/scripts/generate-doc-map.mjs

@@ -1,197 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * generate-doc-map.mjs
- * 
- * Scans the project for all documentation files and generates a doc-map.md
- * file that helps AI agents navigate the codebase documentation.
- */
-
-import { readdir, stat, writeFile } from 'node:fs/promises';
-import { join, relative, dirname, basename } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-// The script is in .agents/, so the project root is one level up
-// Accept PROJECT_ROOT from command line argument or environment variable, otherwise calculate
-const PROJECT_ROOT = process.argv[2] || process.env.PROJECT_ROOT || join(__dirname, '../../../../..');
-
-// Packages that have their own .agents/documentation
-const PACKAGES = [
-  'core', 'agent', 'cli', 'wscli', 'types', 'smem', 'tmem', 'server'
-];
-
-/**
- * Recursively find all markdown files in a directory
- */
-async function findMarkdownFiles(dir, baseDir) {
-  const files = [];
-  try {
-    const entries = await readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        // Skip node_modules and other non-doc directories
-        if (!['node_modules', '.git', 'dist', 'build', '__pycache__'].includes(entry.name)) {
-          files.push(...await findMarkdownFiles(fullPath, baseDir));
-        }
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
-        const relPath = relative(baseDir, fullPath);
-        files.push({ path: fullPath, relative: relPath });
-      }
-    }
-  } catch (err) {
-    // Skip directories we can't read
-  }
-  return files;
-}
-
-/**
- * Extract a human-readable title from the filename
- */
-function extractTitle(fileRelative) {
-  const parts = fileRelative.split('/');
-  const filename = basename(fileRelative, '.md');
-
-  // Try to get a better name from the path segments
-  if (parts.length > 1) {
-    return parts.slice(0, -1).join('/') + '/' + filename;
-  }
-  return filename;
-}
-
-/**
- * Format a file path for display and linking using full workspace-relative path
- */
-function formatLink(fileRelative, basePath) {
-  // Return full path from workspace root with .md extension preserved
-  return `${basePath}/${fileRelative}`;
-}
-
-/**
- * Generate the documentation map markdown content
- */
-async function generateDocMap() {
-  const docSections = [];
-
-  // Scan public documentation (docsite/public/doc)
-  const publicDocPath = join(PROJECT_ROOT, 'docsite/public/doc');
-  try {
-    await stat(publicDocPath);
-    const files = await findMarkdownFiles(publicDocPath, publicDocPath);
-
-    if (files.length > 0) {
-      // Group by top-level category
-      const grouped = {};
-      for (const file of files) {
-        const parts = file.relative.split('/');
-        const category = parts[0] || 'root';
-        if (!grouped[category]) grouped[category] = [];
-        grouped[category].push(file);
-      }
-
-      docSections.push({
-        title: '📚 Public Documentation',
-        description: 'Main project documentation hosted in the docsite.',
-        files: grouped,
-        basePath: 'docsite/public/doc'
-      });
-    }
-  } catch (err) {
-    // Skip if directory doesn't exist
-  }
-
-  // Scan root .agents/documentation
-  const rootAgentsPath = join(PROJECT_ROOT, '.agents/documentation');
-  try {
-    await stat(rootAgentsPath);
-    const files = await findMarkdownFiles(rootAgentsPath, rootAgentsPath);
-
-    if (files.length > 0) {
-      docSections.push({
-        title: '🤖 Root Agent Documentation',
-        description: 'Documentation for the agent system itself.',
-        files: { '': files },
-        basePath: '.agents'
-      });
-    }
-  } catch (err) {
-    // Skip if directory doesn't exist
-  }
-
-  // Scan each package's .agents/documentation
-  for (const pkg of PACKAGES) {
-    const pkgAgentsPath = join(PROJECT_ROOT, `packages/${pkg}/.agents/documentation`);
-    try {
-      await stat(pkgAgentsPath);
-      const files = await findMarkdownFiles(pkgAgentsPath, pkgAgentsPath);
-
-      if (files.length > 0) {
-        docSections.push({
-          title: `📦 Package: @agent-smith/${pkg}`,
-          description: `Documentation for the ${pkg} package.`,
-          files: { '': files },
-          basePath: `packages/${pkg}/.agents`
-        });
-      }
-    } catch (err) {
-      // Skip if directory doesn't exist or has no docs
-    }
-  }
-
-  // Generate the markdown content - compact format for AI agents
-  const lines = [
-    '# 🗺️ Documentation Map',
-    '',
-  ];
-
-  // Detailed sections only (no summary table, no horizontal rules)
-  for (const section of docSections) {
-    lines.push(`## ${section.title}`);
-    lines.push('');
-
-    for (const [category, files] of Object.entries(section.files)) {
-      if (files.length === 0) continue;
-
-      if (category) {
-        lines.push(`### ${category}`);
-        lines.push('');
-      }
-
-      // Sort files: files starting with numbers come first, then alphabetical
-      const sortedFiles = [...files].sort((a, b) => {
-        const aName = basename(a.relative, '.md');
-        const bName = basename(b.relative, '.md');
-        return aName.localeCompare(bName, undefined, { numeric: true });
-      });
-
-      for (const file of sortedFiles) {
-        const fullPath = formatLink(file.relative, section.basePath);
-        const workspacePath = `agent-smith/${fullPath}`;
-        lines.push(`- [\`${workspacePath}\`](${workspacePath})`);
-      }
-
-      lines.push('');
-    }
-  }
-
-  return lines.join('\n');
-}
-
-// Main execution
-async function main() {
-  console.log('🔍 Scanning for documentation files...');
-
-  const content = await generateDocMap();
-  const outputPath = join(PROJECT_ROOT, '.agents/documentation/documentation-map.md');
-
-  // Write the file
-  await writeFile(outputPath, content, 'utf-8');
-
-  console.log(`✅ Documentation map generated: ${outputPath}`);
-}
-
-main().catch(err => {
-  console.error('❌ Error generating doc-map:', err);
-  process.exit(1);
-});