Ask Workflow

Complete reference for the codedocs:ask command - question routing, doc-first resolution strategy, source code fallback, and citation format.

Pre-flight Check

Before answering any question:

1. Look for .codedocs.json in the expected output directory (default: docs/)
2. If missing, respond: "No codedocs found. Run codedocs:generate first to create documentation, then ask your question again."
3. If found, read the manifest to understand what's documented and when it was last updated.

Question Routing

Route the user's question to the most relevant doc file(s):

Architecture / overview questions

Signals: "how does this project work", "what's the architecture", "tech stack", "what does this repo do", "system overview", "getting started"

Route to: OVERVIEW.md

Module-specific questions

Signals: mentions a specific directory, file, feature area, function name, class name, or module name that maps to an entry in the manifest's module list

Route to: modules/<module-name>.md

Disambiguation: If the question mentions something that could map to multiple modules, check the manifest's source path mappings. If still ambiguous, read the OVERVIEW.md module map to determine the best match. If truly ambiguous, read both module docs.

Cross-cutting / pattern questions

Signals: "how does error handling work", "testing strategy", "logging", "auth flow", "configuration", "database access patterns" - anything that spans modules

Route to: patterns/<pattern-name>.md

Dependency / relationship questions

Signals: "what depends on X", "what does X import", "how are modules connected", "dependency graph"

Route to: Start with OVERVIEW.md module map, then read relevant module docs for their Dependencies and Dependents sections.

Broad / unclear questions

Signals: Vague questions like "explain the code" or "how does everything work together"

Route to: OVERVIEW.md first. If the user needs more depth, suggest specific modules to drill into.

Doc-First Resolution Strategy

This is the core principle of codedocs:ask. Follow this resolution order strictly:

Level 1: Docs only (preferred)

Read the routed doc file(s). If the answer is fully contained in the docs:

• Answer the question
• Cite the doc file: "Source: docs/modules/auth.md"
• Done

Level 2: Docs + light inference

If the docs contain most of the answer but require minor inference (connecting two documented facts, applying a documented pattern to a specific case):

• Answer with the inference clearly stated
• Cite the doc files used
• Done

Level 3: Docs insufficient, source code needed

If the docs don't contain enough detail to answer the question:

1. Identify which source files would have the answer (use the module doc's Internal Structure section to locate them)
2. Read the minimum source files needed
3. Answer the question
4. Add a staleness flag: "Note: this answer required reading source code beyond what's in the docs. The following files contain details not yet captured: <file list>. Consider running codedocs:update --scope <module-path> to capture this."

Level 4: Question outside documented scope

If the question is about code that isn't documented at all (no matching module in the manifest):

1. Check if the code exists in the repo
2. If yes, answer from source and flag: "This code is not yet documented by codedocs. Run codedocs:generate or codedocs:update to add it."
3. If no, tell the user the code doesn't exist in this repo

Staleness Awareness

When answering, check the manifest's last_updated timestamp and git SHA for the relevant module:

• If the documented SHA matches the current HEAD for that module's files, the docs are fresh - answer with confidence
• If files have changed since the documented SHA, warn: "Note: the docs for this module were generated at commit <sha> but the code has changed since. The answer may be outdated. Run codedocs:update --scope <path> to refresh."

To check staleness without a full git operation, compare the manifest SHA against git log -1 --format=%H -- <module-path>.

Citation Format

Always cite sources in answers:

From docs:

Source: `docs/modules/auth.md`

From multiple docs:

Sources: `docs/OVERVIEW.md`, `docs/modules/auth.md`

From source code (fallback):

Source: `src/auth/middleware.ts` (not in docs - consider updating)

From both:

Sources: `docs/modules/auth.md`, `src/auth/middleware.ts:42` (detail not in docs)

Multi-Turn Q&A

When the user asks follow-up questions in the same session:

• Keep track of which doc files are already loaded in context
• Don't re-read files already loaded unless the question requires a fresh look
• If the conversation is getting deep into a single module, suggest: "For more detail on this module, I can read the source code directly. Want me to?"

Coverage Strategy

Reference for measuring, improving, and maintaining documentation coverage - how to ensure a large or complex repo is comprehensively documented, not just partially skimmed.

Why coverage matters

Documentation that covers 40% of a codebase is often worse than no documentation: it gives a false sense of completeness and fails the most common question ("where is this?"). Codedocs targets meaningful coverage, not perfection - the goal is that any developer or AI agent can navigate to the right place without reading raw source code.

Running codedocs:status

Command: codedocs:status

Read .codedocs.json and produce a coverage report:

Codedocs Status
===============
Project: <name>
Generated: <date>
Last updated: <date> (commit <sha>)
Updates applied: <N>

Coverage: <N>% (<documented>/<total> source files)

Documented modules (<count>):
  - <module-name> (<path>) - <N> files - last updated <date>
  - ...

Undocumented areas (<count> directories, <N> files):
  - <path> - <N> files [suggestion: add as module or fold into <nearest-module>]
  - ...

Stale modules (<count>):
  - <module-name> - documented at <sha>, code changed since
  - ...

Patterns: <count> documented
  - <pattern-name> - last updated <date>

Recommendation: <action based on coverage and staleness>

Coverage targets

For very large repos (1000+ files), prioritize coverage by importance:

1. Domain modules (business logic) - aim for 90%+ coverage
2. API/interface layers - aim for 85%+ coverage
3. Infrastructure/platform code - aim for 60%+ coverage
4. Utility libraries - aim for 50%+ coverage (often self-explanatory)
5. Generated code - exclude from coverage calculation

How to improve coverage

When below target after initial generate

1. Run the gap analysis - List all directories in the census not covered by any module doc. Sort by file count (highest first).

2. Batch small undocumented directories - Directories with 1-2 files that are clearly related to a larger documented module should be mentioned in that module's doc rather than getting their own doc.

3. Create module docs for significant gaps - For uncovered directories with 3+ files, create new module docs. Use the standard module doc template.

4. Use --exhaustive flag - codedocs:generate --exhaustive lowers the minimum file threshold to 1 and documents every directory with at least one source file. Useful for repos with many small-but-important modules. Output will be larger but more complete.

5. Group orphan files - Source files not in any directory (directly in src/ or repo root) get documented in a special modules/root.md module.

When a module doc is too long (50+ lines of Internal Structure)

Split the module into sub-modules:

1. Identify the distinct sub-directories or groupings within the module
2. Create modules/<parent>/ directory
3. Move the parent doc to modules/<parent>.md (keep it as an index)
4. Create modules/<parent>/<child>.md for each sub-module
5. Update INDEX.md to point files to their sub-module doc
6. Update .codedocs.json to add sub_modules entries

When coverage is high but docs are shallow

Coverage percentage measures file coverage, not depth. Signs of shallow docs:

• Module docs with empty "Implementation Notes" everywhere
• Pattern docs with only one example
• Dependency/Dependent tables with 0-1 entries
• No "Getting Started" section in OVERVIEW.md

For shallow docs, re-read the source files for each module and enrich:

• Add real function/method names to Public API
• Add actual file paths to Internal Structure
• Fill in concrete dependency relationships
• Add working code examples to pattern docs

Prioritization framework for large repos

When a repo is too large to document exhaustively in one session, use this priority order:

Tier 1: Always document first (core understanding)

• Entry points (main files, route definitions, CLI commands)
• Modules that are imported by 3+ other modules (high fan-in = central)
• Modules that import 5+ other modules (high fan-out = integration points)
• Authentication, authorization, and security modules
• Public API surface (what external callers use)

Tier 2: Document second (operational understanding)

• Database and persistence layer
• Background jobs and async processing
• Configuration and feature flags
• Error handling and logging infrastructure
• Core domain/business logic modules

Tier 3: Document when time allows (implementation details)

• Internal utilities and helpers
• Test infrastructure and fixtures
• Build tooling and scripts
• Third-party integration adapters
• UI components (when not the primary focus)

Tier 4: Mention but don't deep-dive

• Generated code (proto files, ORM migrations, GraphQL schemas)
• Vendor/dependency overrides
• One-off scripts

Maintaining coverage over time

After new features are added

Run codedocs:update --diff after each significant feature. This:

• Detects new directories not yet in the manifest
• Flags stale modules whose files changed
• Suggests new module docs for new feature directories

Set a reminder to run codedocs:status at the start of each sprint to catch coverage drift before it accumulates.

Coverage budget

Define a coverage budget in .codedocs.json:

"config": {
  "coverage_budget": {
    "minimum_percentage": 70,
    "alert_on_drift": 5
  }
}

With a budget set, codedocs:update will warn if coverage drops below minimum_percentage or if a single update causes coverage to drop by more than alert_on_drift percentage points (e.g., a module was deleted but its doc wasn't cleaned up).

Staleness budget

A module doc is "stale" when the git SHA recorded in the manifest no longer matches the latest commit on that module's source path. In codedocs:status, modules stale for more than 30 days are flagged as high priority for update.

Coverage anti-patterns

Generate Workflow

Complete reference for the codedocs:generate command - discovery heuristics, module boundary detection, tech stack identification, sub-module splitting, coverage verification, and output templates.

Discovery Phase

Step 1: Tech stack identification

Scan the repo root (and target path) for manifest files. Each file reveals language, framework, and dependency information:

For monorepos, check for workspace definitions:

• package.json with workspaces field
• Cargo.toml with [workspace] section
• go.work file
• pnpm-workspace.yaml
• lerna.json
• nx.json
• turbo.json

Record: primary language, framework (if detectable from dependencies), build tool, and test framework.

Step 2: Entry point detection

Entry points are the starting locations for understanding code flow. Detect them by checking (in priority order):

1. Explicit main files - main.ts, main.go, main.rs, __main__.py, Main.java, Program.cs
2. Index/entry exports - index.ts, index.js, lib.rs, __init__.py, mod.rs
3. Framework entry points - app.ts (Express/Fastify), pages/ or app/ (Next.js), src/App.tsx (React), manage.py (Django), config/routes.rb (Rails)
4. CLI entry points - bin/ directory, scripts in package.json, [tool.poetry.scripts] in pyproject.toml
5. Config-defined entries - main or module field in package.json, [lib] in Cargo.toml

Step 3: Full recursive directory census

Before detecting module boundaries, build a complete census of the repo. Walk the entire directory tree (excluding ignore paths) and record every directory with its file count. This census drives both module detection and coverage verification.

Census format:
  <path> | <source file count> | <depth>
  src/                    | 3   | 1
  src/auth/               | 8   | 2
  src/auth/strategies/    | 4   | 3
  src/api/                | 22  | 2
  src/api/routes/         | 11  | 3
  src/api/middleware/     | 6   | 3
  ...

What to count as source files: .ts, .js, .py, .go, .rs, .java, .kt, .rb, .ex, .exs, .cs, .cpp, .c, .swift, .php. Exclude lock files, config files (.json, .yaml, .toml unless they define code), test files (unless include_test_files: true), and generated files.

Step 4: Multi-level module boundary detection

Modules are the primary unit of documentation. Apply these heuristics in layers, from coarsest to finest, collecting all candidates before deduplicating.

Layer 1: Monorepo packages (highest priority)

Each workspace package is its own top-level module. For each package:

• Record the package root as a module boundary
• Recurse into the package to find sub-modules (apply Layer 2-4 within it)

Layer 2: Top-level structural directories

Inside each package (or the repo root if not a monorepo), scan the first two levels of directories for structural modules:

Explicit source roots: src/, lib/, app/, pkg/, cmd/

• Every direct child directory of these roots with 2+ source files is a module candidate

Framework convention directories (these are themselves modules):

• Express/Fastify/Hapi: routes/, controllers/, middleware/, services/, models/
• Next.js: app/ (or pages/), components/, lib/, server/
• Django/Flask: views/, models/, serializers/, urls/
• Rails: app/models/, app/controllers/, app/services/
• Spring: controller/, service/, repository/, config/
• Go: every directory containing .go files is a package (and a module candidate)
• Rust: every directory containing mod.rs or lib.rs

Domain/feature directories - Any directory 1-3 levels deep whose name suggests a domain concept: auth, billing, users, products, orders, notifications, search, analytics, admin, api, core, shared, common, utils, helpers, hooks, store, context, types

Layer 3: Deep scanning for large modules

For every module candidate from Layer 2 that has 15+ source files OR contains subdirectories with 3+ files each, recursively scan inside it to find sub-modules. Apply this rule:

If a module contains a subdirectory with 3+ source files and a distinct purpose (different name from parent, has its own index/exports), that subdirectory becomes a sub-module documented in modules/<parent>/<child>.md.

Examples of when to split:

• src/api/ with 22 files splits into api/routes, api/middleware, api/validators
• src/components/ with 30 files splits into components/ui, components/forms, components/layout
• src/utils/ with 18 files splits into utils/string, utils/date, utils/http

Examples of when NOT to split:

• src/auth/ with 8 files - document as one module even with 2-3 subdirs
• src/config/ with 5 files - too small to warrant sub-modules
• Single-level flat directories with no internal structure

Layer 4: Minimum-threshold cleanup

After collecting all candidates:

• Keep modules with 2+ source files (lower than the manifest default to avoid gaps)
• Merge candidates that are clearly the same logical module (e.g., types/ with 1 file that only re-exports from models/ - fold into models)
• Flag directories with 1 source file as "minor files" - mention in the parent module doc rather than creating a separate module doc

Step 5: Cross-cutting pattern detection (expanded)

Patterns are concerns that span multiple modules. Scan for all of these:

Structural patterns:

• Error handling - Shared error types, error middleware, Result/Either patterns, custom exception classes, error codes/enums
• Logging/observability - Logger setup, structured logging, metrics export, tracing instrumentation, correlation IDs
• Configuration - Config loading order, environment variable handling, feature flags, secrets management
• Authentication/authorization - Auth middleware, JWT/session handling, guards, decorators, permission checks, RBAC

Data patterns:

• Database access - ORM setup, migration patterns, repository/DAO patterns, connection management, query builders
• Caching - Cache clients, cache key conventions, TTL patterns, cache invalidation strategies
• Event/message handling - Queue clients, event emitters, pub/sub patterns, event schemas
• External API clients - HTTP client wrappers, retry logic, circuit breakers, service clients

Code quality patterns:

• Testing - Test directory structure, test utilities, fixtures, factories, mocking patterns, test configuration, test helpers
• Validation - Input validation libraries, schema validation, DTO patterns, sanitization
• Type system - Shared type definitions, interfaces, enums, generics patterns
• Dependency injection - DI containers, service registration, provider patterns

Operational patterns:

• API conventions - Request/response schemas, pagination patterns, versioning, error response format, serialization
• Background jobs - Job queue setup, worker definitions, scheduled tasks, job retry patterns
• File/storage handling - File upload patterns, storage clients, CDN integration
• Internationalization - i18n library setup, translation file structure, locale handling

Only create a pattern doc if the pattern appears in 2+ modules. Single-module patterns belong in the module doc.

Step 6: Coverage verification

After collecting all module candidates and patterns, run a coverage check before presenting the plan. This ensures the documentation plan covers the codebase adequately.

Calculate coverage:

covered_files = sum of source files in all module candidates
total_files = total source files from the census (Step 3)
coverage = covered_files / total_files * 100

Coverage targets by repo size:

If coverage is below target:

1. Identify uncovered directories (those in the census but not in any module candidate)
2. For each uncovered directory with 2+ source files, add it as a module candidate
3. For single files not in any module, group them into a misc module or fold them into the nearest parent module
4. Re-run coverage calculation
5. Report the final coverage percentage in the discovery plan

Always report in the discovery plan:

Coverage: <N>% (<covered> of <total> source files documented)

Step 7: Present the plan

Before writing any documentation, present the discovery results to the user:

Codedocs Discovery Plan
========================
Repository: <name>
Tech stack: <language> + <framework> (<build tool>)
Entry points: <list>

Modules to document (<count>):
  Top-level modules:
  - <module-name> (<path>) - <one-line summary> (<N> files)
  - ...

  Sub-modules:
  - <parent>/<child> (<path>) - <one-line summary> (<N> files)
  - ...

Patterns detected (<count>):
  - <pattern-name> - <where it appears>
  - ...

Coverage: <N>% (<covered> of <total> source files)
Estimated output: <N> files in <output-dir>/
  - 1 OVERVIEW.md
  - 1 INDEX.md
  - <N> module docs
  - <N> pattern docs
  - 1 .codedocs.json

Proceed? [Y/n]

Wait for user approval. They may want to add, remove, rename, or merge modules. If coverage is below target, proactively call out which directories are uncovered and ask if they should be included.

Step 8: Generate GETTING_STARTED.md

After writing module and pattern docs, generate GETTING_STARTED.md by extracting and expanding all runnable commands from the repo. This is the authoritative local development guide.

How to discover commands:

1. package.json scripts - List every script with a one-line description of what it does. Group them by purpose (dev, test, build, lint, etc.).
2. Makefile targets - List every non-phony target with its recipe and purpose.
3. Taskfile.yml / justfile - Same as Makefile.
4. Framework CLI conventions - Detect from the stack:
   • Next.js/Vite/CRA: dev, build, start, lint, test
   • Django: manage.py runserver, migrate, makemigrations, shell
   • Rails: rails server, rails console, rails db:migrate, rspec
   • Go: go run ./..., go test ./..., go build
   • Rust: cargo run, cargo test, cargo build, cargo clippy
   • Python: look for pyproject.toml scripts, tox.ini, pytest.ini
5. Docker / docker-compose - List docker compose up, down, and any named services that a developer would interact with.
6. CI config - Read .github/workflows/, .gitlab-ci.yml, or similar. The CI steps reveal the canonical commands the project actually uses in production. Extract the test, build, and lint commands from there.
7. README - If the repo has a README with setup/usage sections, extract commands from code blocks.
8. Environment files - Check for .env.example, .env.sample, or documented env vars in README. List required variables and their purpose.

GETTING_STARTED.md template:

# Getting Started

Everything you need to run, test, and develop <Project Name> locally.

## Prerequisites

<List of required tools and minimum versions. Only include what's actually
needed - don't list things like "a computer" or "internet access".>

| Tool | Version | Install |
|---|---|---|
| Node.js | >= 20 | https://nodejs.org |
| pnpm | >= 9 | `npm install -g pnpm` |
| Docker | >= 24 | https://docker.com |
| <etc.> | | |

## Installation

```bash
# Clone the repo
git clone <repo-url>
cd <repo-name>

# Install dependencies
<install command - e.g. pnpm install, pip install -e ".[dev]", cargo build>

Environment Setup

# Copy the example env file
cp .env.example .env

# Edit .env and fill in the required values:
# DATABASE_URL  - PostgreSQL connection string
# JWT_SECRET    - Random secret for signing tokens (min 32 chars)
# <etc.>        - <purpose>

# Start required services via Docker
docker compose up -d

<dev command - e.g. pnpm dev, python manage.py runserver, cargo run>

<migration command - e.g. pnpm db:migrate, python manage.py migrate>

# Run all tests
<test command>

# Run a specific test file
<test command for single file>

# Run tests in watch mode
<watch command if available>

# Run with coverage
<coverage command if available>

# Build for production
<build command>

# Preview the production build locally (if applicable)
<preview command>

# Lint
<lint command>

# Format
<format command>

# Type check (if applicable)
<typecheck command>

# Apply pending migrations
<migrate command>

# Create a new migration
<create migration command>

# Reset the database (destructive)
<reset command>

# Open a database shell / GUI
<db shell command>

# Seed with development data
<seed command if available>

# <step 1 - e.g. create the route file>
# <step 2 - e.g. register it in the router>
# <step 3 - e.g. run tests>

# Run tests matching a pattern
<command>

# Run tests for a specific module
<command>

<debug command if available>

# Reproduce CI checks locally
<lint command>
<typecheck command>
<test command>
<build command>

---

### Step 9: Generate INDEX.md


After writing all module docs, generate `INDEX.md` as a lookup table mapping
every significant source file to its module doc. This is primarily for AI agent
navigation.

```markdown
# File Index

Quick lookup: find which module documents any file in this repo.

| File | Module | Doc |
|---|---|---|
| `src/auth/middleware.ts` | auth | `modules/auth.md` |
| `src/auth/strategies/jwt.ts` | auth/strategies | `modules/auth/strategies.md` |
| `src/api/routes/users.ts` | api/routes | `modules/api/routes.md` |
| ... | ... | ... |

# <Project Name>

<2-3 sentence summary of what the project does, who it's for, and the core
problem it solves.>

## Tech Stack

| Layer | Technology |
|---|---|
| Language | <e.g. TypeScript> |
| Framework | <e.g. Next.js 14> |
| Database | <e.g. PostgreSQL via Prisma> |
| Testing | <e.g. Vitest + Playwright> |
| Build | <e.g. Turbopack> |

## Project Structure

<Directory tree of the repo showing only meaningful directories and key files.
Collapse noisy subtrees (node_modules, dist, .git) entirely. Annotate every
entry with a short inline comment explaining its role. Aim for 30-60 lines -
enough to understand the layout at a glance without scrolling forever.>

Rules for generating the tree:
- Show every directory that has a module doc
- Show key root-level config files (package.json, Dockerfile, Makefile, etc.)
- Show entry point files explicitly (main.ts, manage.py, etc.)
- Collapse deeply nested subtrees into a single annotated line
- Omit: node_modules, dist, build, .git, coverage, lock files, generated files
- Use `# comment` inline annotations on every line - this is what makes the
  tree useful vs just running `tree` in the terminal

## Architecture

<2-4 paragraphs describing the high-level architecture. Include:
- System boundaries (what's in this repo vs external services)
- Request/data flow (how a request enters, gets processed, and returns)
- Key architectural decisions and their rationale>

## Entry Points

| Entry point | Purpose |
|---|---|
| `<path>` | <what it starts/serves> |

## Module Map

| Module | Path | Description | Files |
|---|---|---|---|
| <name> | `<path>` | <one-line purpose> | <N> |

> Sub-modules are listed under their parent. See `INDEX.md` for file-level lookup.

## Cross-cutting Patterns

| Pattern | Doc | Modules affected |
|---|---|---|
| <name> | `patterns/<name>.md` | <module list> |

## Key Concepts

<Glossary of domain-specific terms used throughout the codebase. Only include
terms that would confuse someone unfamiliar with the project.>

## Getting Started

<Minimal steps to clone, install, and run the project locally. Pull from
existing README if available.>

## Documentation Coverage

Generated by codedocs. Coverage: <N>% (<covered>/<total> source files).
Last updated: <timestamp> at commit `<sha>`.

# <Module Name>

<1-2 sentence summary of the module's purpose and responsibility.>

## Sub-modules

> Only include this section if the module has sub-modules.

| Sub-module | Doc | Description |
|---|---|---|
| <name> | `modules/<parent>/<child>.md` | <purpose> |

## Public API

<List of exported functions, classes, types, or endpoints with brief
descriptions. This is what other modules consume.>

## Internal Structure

<How the module is organized internally. Key files and their roles.
Only list files that are important for understanding - skip trivial
utility files.>

| File | Purpose |
|---|---|
| `<relative-path>` | <what it does> |

## Dependencies

| Depends on | Why |
|---|---|
| <module/package> | <what it uses from it> |

## Dependents

| Used by | How |
|---|---|
| <module> | <what it imports/uses> |

## Implementation Notes

<Key design decisions, non-obvious behavior, performance considerations,
or known limitations specific to this module. Skip this section if there
is nothing noteworthy.>

# <Pattern Name>

<1-2 sentence description of the pattern and why the codebase uses it.>

## Where It Appears

<List of modules that implement or interact with this pattern.>

## Convention

<The rules to follow when working with this pattern. Be specific -
code style, naming conventions, file placement, etc.>

## Examples

<2-3 concrete examples from the codebase showing the pattern in use.
Reference actual file paths.>

## Adding to This Pattern

<What a developer should do when adding new code that touches this pattern.
E.g., "When adding a new route, register it in X and add error handling
using Y.">

Output Structure

Complete specification for the codedocs output directory, file formats, and the .codedocs.json manifest schema.

Directory Layout

<output-dir>/                    # Default: docs/ at repo root
  OVERVIEW.md                    # Architecture, tech stack, project structure tree, module map
  GETTING_STARTED.md             # Dev environment setup, all runnable commands, workflows
  INDEX.md                       # File-to-module lookup table for AI agent navigation
  .codedocs.json                 # Manifest: tracked modules, SHAs, config, coverage stats
  modules/                       # One file per code module (flat for simple modules)
    <module-name>.md             # e.g. auth.md, api.md, database.md
    <module-name>/               # Directory for modules with sub-modules
      <sub-module>.md            # e.g. api/routes.md, api/middleware.md
  patterns/                      # One file per cross-cutting concern
    <pattern-name>.md            # e.g. error-handling.md, testing.md

When to use flat files vs sub-module directories

Use a flat file (modules/auth.md) when:

• The module has fewer than 15 source files
• The module has no meaningfully distinct internal directories
• All of the module's behavior can be described in one focused document

Use a sub-module directory (modules/api/routes.md, modules/api/middleware.md) when:

• The module has 15+ source files with distinct internal groupings
• Sub-directories have 3+ files each with a clearly different purpose
• The module doc would otherwise need 4+ "Internal Structure" subsections

A parent module with sub-modules still gets its own <module-name>.md as an index that describes the module's overall purpose and lists sub-modules. The sub-module files contain the detailed content.

Naming conventions

• Module files: kebab-case matching the directory or package name. src/auth/ becomes modules/auth.md. packages/user-service/ becomes modules/user-service.md.
• Sub-module files: kebab-case inside a directory named after the parent. src/api/routes/ becomes modules/api/routes.md.
• Pattern files: kebab-case describing the concern. patterns/error-handling.md, patterns/testing-strategy.md, patterns/logging-conventions.md.
• No deeper nesting: Sub-module directories are the deepest level allowed. modules/<parent>/<child>.md is the maximum depth. Do not create modules/<parent>/<child>/<grandchild>.md.

Output directory configuration

The output directory defaults to docs/ at the repo root. Override with the --output flag:

codedocs:generate --output documentation/
codedocs:generate path/to/subpackage --output path/to/subpackage/docs/

The output directory is recorded in the manifest so that codedocs:ask and codedocs:update can find it automatically.

.codedocs.json Manifest Schema

{
  "version": "1.1",
  "project_name": "<repo or directory name>",
  "output_dir": "docs/",
  "generated_at": "2026-03-18T10:30:00Z",
  "last_updated": "2026-03-18T14:45:00Z",
  "last_global_sha": "abc1234def5678...",
  "update_count": 0,
  "output_files": {
    "overview": "OVERVIEW.md",
    "getting_started": "GETTING_STARTED.md",
    "index": "INDEX.md"
  },
  "tech_stack": {
    "primary_language": "TypeScript",
    "framework": "Next.js 14",
    "build_tool": "Turbopack",
    "test_framework": "Vitest",
    "package_manager": "pnpm"
  },
  "coverage": {
    "total_source_files": 187,
    "documented_source_files": 154,
    "percentage": 82
  },
  "modules": [
    {
      "name": "auth",
      "source_path": "src/auth/",
      "doc_path": "modules/auth.md",
      "description": "Authentication and authorization middleware",
      "last_sha": "abc1234...",
      "last_updated": "2026-03-18T10:30:00Z",
      "file_count": 8,
      "primary_language": "TypeScript",
      "sub_modules": []
    },
    {
      "name": "api",
      "source_path": "src/api/",
      "doc_path": "modules/api.md",
      "description": "REST API route handlers and middleware",
      "last_sha": "def5678...",
      "last_updated": "2026-03-18T10:30:00Z",
      "file_count": 22,
      "primary_language": "TypeScript",
      "sub_modules": [
        {
          "name": "api/routes",
          "source_path": "src/api/routes/",
          "doc_path": "modules/api/routes.md",
          "description": "Route definitions for all API endpoints",
          "last_sha": "def5678...",
          "last_updated": "2026-03-18T10:30:00Z",
          "file_count": 11
        },
        {
          "name": "api/middleware",
          "source_path": "src/api/middleware/",
          "doc_path": "modules/api/middleware.md",
          "description": "Request/response middleware chain",
          "last_sha": "def5678...",
          "last_updated": "2026-03-18T10:30:00Z",
          "file_count": 6
        }
      ]
    }
  ],
  "patterns": [
    {
      "name": "error-handling",
      "doc_path": "patterns/error-handling.md",
      "description": "Shared error types and error middleware",
      "appears_in": ["auth", "api", "database"]
    }
  ],
  "config": {
    "ignore_paths": ["node_modules", "dist", "build", ".git", "coverage"],
    "min_module_files": 2,
    "include_test_files": false,
    "max_sub_module_depth": 1
  }
}

Field descriptions

File Format Guidelines

All doc files

• Use standard GitHub-flavored Markdown
• Start with a level-1 heading (# Title)
• Use level-2 headings (## Section) for major sections
• Use tables for structured data (dependencies, exports, config)
• Use code blocks with language annotation for code references
• Reference file paths relative to the repo root
• Keep each file self-contained - don't require reading other files to understand the basics (cross-references are fine for deep dives)

OVERVIEW.md specifics

• Must be readable in under 5 minutes by a human
• Must contain enough context for an AI agent to route questions to the right module doc
• Module Map table is the routing index - every documented module must appear here (sub-modules nested under their parent)
• Cross-cutting Patterns table is the secondary routing index
• Project Structure tree must be annotated - every line has an inline comment
• Getting Started section is a brief pointer: "See GETTING_STARTED.md for the full development guide"
• Always include a Documentation Coverage line at the bottom

GETTING_STARTED.md specifics

• The authoritative guide for running and developing the repo locally
• Must be fully self-contained: a developer with a clean machine should be able to follow it top-to-bottom without consulting any other file
• All commands must be copy-pasteable and verified against actual scripts in the repo (package.json scripts, Makefile targets, Cargo commands, etc.)
• Organized into sections: Prerequisites, Installation, Environment, Dev server, Testing, Building, Linting/formatting, and Common workflows
• If the repo has a README with setup instructions, extract and expand them - don't just repeat them verbatim; add context and fill gaps
• Common workflows section covers the day-to-day developer actions: how to add a feature, run a subset of tests, apply a migration, etc.

INDEX.md specifics

• One row per source file that belongs to a documented module
• Sorted alphabetically by file path
• Columns: File, Module, Doc (link to module doc)
• Primary purpose is AI agent navigation: given a file name, find the doc
• Does not include undocumented files (they're not linked to any doc)
• Updated during codedocs:update when files are added or moved

Module doc specifics

• Public API section is the most important - this is what consumers need
• Internal Structure table should cover every significant file (not trivial helpers)
• Dependencies and Dependents sections enable understanding the module in context without reading the full codebase
• Implementation Notes is optional - only include if there are genuinely non-obvious design decisions
• Parent module docs (those with sub-modules) should have a Sub-modules table immediately after the opening summary

Pattern doc specifics

• Convention section must be prescriptive, not descriptive - tell the reader what to do, not just what exists
• Examples must reference actual file paths in the repo
• Where It Appears must list specific modules, not vague references
• Adding to This Pattern section helps developers extend the pattern correctly

Default Ignore Paths

These paths are always excluded from discovery unless explicitly overridden:

node_modules/
dist/
build/
.git/
coverage/
.next/
.nuxt/
__pycache__/
*.pyc
target/          # Rust, Java
vendor/          # Go, PHP, Ruby
.cache/
.turbo/
.vercel/
.output/
out/
.expo/
.svelte-kit/
generated/
gen/
*.generated.*
*.pb.go          # Protobuf generated
*_pb2.py         # Protobuf generated

Test directories (__tests__/, test/, tests/, spec/) are excluded by default but can be included with config.include_test_files: true in the manifest. When included, test files count toward coverage but are documented under the patterns/testing-strategy.md pattern doc rather than as modules.

Update Workflow

Complete reference for the codedocs:update command - diff detection, manifest-driven scoping, new module detection, and OVERVIEW.md synchronization.

Pre-flight Check

1. Look for .codedocs.json in the output directory
2. If missing, respond: "No existing codedocs found. Run codedocs:generate first. codedocs:update only works with existing documentation."
3. If found, read the full manifest to understand the current documentation state

Mode 1: Targeted Scope Update

Command: codedocs:update --scope path/to/module

Step-by-step workflow

1. Validate scope - Confirm the specified path exists in the repo. Check if it maps to an existing module in the manifest.

2. Re-discover the scoped path - Run the discovery phase (from generate-workflow.md) limited to the specified directory. This produces an updated snapshot of:

   • File list and primary language
   • Exports (public API surface)
   • Imports from other modules
   • Internal structure

3. Diff against existing module doc - Compare the new discovery against the current content in modules/<module>.md. Identify:

   • New exports not in the current doc
   • Removed exports still listed in the current doc
   • Changed dependencies (new imports or dropped imports)
   • New files that might deserve mention in Internal Structure
   • Changed file structure (renamed, moved, or deleted files)

4. Rewrite the module doc - Update only the sections that changed. Keep unchanged sections intact to preserve any manual edits or notes the user may have added.

5. Check OVERVIEW.md impact - If any of these changed, update OVERVIEW.md:

   • Module's one-line description in the Module Map table
   • Module's dependencies (affects architecture understanding)
   • Module was renamed or moved

6. Check pattern impact - If the module's changes affect a documented pattern (e.g., a new error type, a changed auth flow), flag it: "The changes in <module> may affect the pattern doc patterns/<pattern>.md. Review and update if needed."

7. Update manifest - Set the module's last_sha to the current commit SHA and last_updated to the current timestamp.

Handling new paths

If the --scope path doesn't match any existing module in the manifest:

• Treat it as a new module
• Run the full module doc generation workflow
• Add it to the manifest
• Add it to OVERVIEW.md's Module Map
• Prompt: "This path wasn't previously documented. I've added it as a new module: <name>. Verify the module name and description are correct."

Mode 2: Git Diff Update

Command: codedocs:update --diff [base..head]

Determining the diff range

• If base..head is provided, use it directly
• If only --diff is provided (no range), determine the range automatically:
  1. Read last_global_sha from the manifest
  2. Use last_global_sha..HEAD as the range
  3. If last_global_sha is missing, fall back to HEAD~10..HEAD and warn: "No baseline SHA in manifest. Diffing last 10 commits. For accurate results, run a full codedocs:generate to establish a baseline."

Step-by-step workflow

1. Get changed files - Run:

   git diff --name-only <base>..<head>

   Collect the list of changed file paths.

2. Filter to source files - Remove non-source files that don't affect documentation: images, lock files, CI configs, editor configs, etc. Keep: source code files, manifest files (package.json, etc.), config files that affect architecture.

3. Map files to modules - For each changed file, find its parent module using the manifest's source_path mappings. Build a set of affected modules.

4. Categorize changes:

   • Modified modules - Modules with changed source files
   • New module candidates - Changed files in directories not mapped to any existing module
   • Deleted modules - Modules whose entire source directory was removed
   • Config changes - Changes to root-level config that might affect OVERVIEW.md (package.json dependencies, build config, etc.)

5. Process modified modules - For each affected module, run the targeted scope update workflow (Mode 1, steps 2-7).

6. Handle new module candidates - For directories with changed files that don't belong to any documented module:

   • If the directory has 3+ source files, suggest it as a new module
   • If fewer, suggest adding the files to the nearest existing module's doc
   • Prompt the user for confirmation before adding

7. Handle deleted modules - If a documented module's source directory no longer exists:

   • Remove the module doc from modules/
   • Remove the entry from the manifest
   • Remove the row from OVERVIEW.md's Module Map
   • Warn: "Module <name> was removed (source directory deleted). Its documentation has been cleaned up."

8. Update OVERVIEW.md - Sync any changes to the Module Map, Tech Stack (if dependencies changed), or Architecture section (if major structural changes detected).

9. Update manifest - Bump last_global_sha to <head>. Update per-module SHAs for all modified modules.

Summary output

After processing, print a summary:

Codedocs Update Summary
========================
Diff range: <base>..<head> (<N> commits)
Files changed: <N>
Modules updated: <list>
New modules added: <list or "none">
Modules removed: <list or "none">
Pattern docs flagged: <list or "none">

Updated files:
  - docs/modules/<name>.md (modified)
  - docs/OVERVIEW.md (module map updated)
  - docs/.codedocs.json (manifest updated)

OVERVIEW.md Sync Rules

OVERVIEW.md should be updated during any update operation if:

1. Module Map changed - Module added, removed, renamed, or description changed
2. Tech Stack changed - New dependency added to manifest file that changes the tech stack table (e.g., new database, new framework)
3. Entry points changed - New CLI command, new route file, new main entry
4. Architecture changed - Major structural refactor detected (multiple modules affected, new inter-module dependencies)

For minor changes (single module internal update, no API changes), skip OVERVIEW.md to avoid unnecessary churn.

Manifest Update Rules

After every update operation:

1. Set last_global_sha to the current HEAD (or the head from the diff range)
2. For each updated module, set last_sha to the latest commit touching that module's source path
3. Set last_updated to the current ISO 8601 timestamp
4. If modules were added or removed, update the modules array accordingly
5. Increment update_count by 1 (tracks how many times docs have been updated)