# Module README Spec

Standard for per-module `MODULE_README.md` files across the codebase.
Generated by `utils/code_context/generate_module_readme.py`.

---

## How It Works

Run the generator once and it creates the file. Run it again and it updates
only the auto-managed sections without touching anything else.

```bash
python utils/code_context/generate_module_readme.py <subdirectory> [options]

# Examples:
python utils/code_context/generate_module_readme.py ai/tools
python utils/code_context/generate_module_readme.py ai/tools \
    --call-graph-scope handle_tool_calls,executor,registry
```

---

## AUTO Section Convention

Auto-managed sections are wrapped in sentinel comments:

```
<!-- AUTO:section_id -->
...generated content (overwritten on each run)...
<!-- /AUTO:section_id -->
```

Anything outside these blocks is human-owned and never modified.

### Auto-managed sections

| Section ID | Heading | Content | Updated on run |
|---|---|---|---|
| `meta` | About This Document | Timestamp, module path, regenerate command | Always |
| `tree` | Directory Tree | Live directory tree (`tree_only` mode) | Always |
| `signatures` | API Signatures | Full signatures (`signatures` mode) | Always |
| `call_graph` | Call Graph | Function call graph (optional, scope-filtered) | When enabled |

### Human-owned sections

| Section | Behavior |
|---|---|
| `## Architecture` | Stub inserted once on first run, then yours forever |
| Anything else | Freely added between or after AUTO blocks — never touched |

---

## The Six Sections (in order in the file)

### 1. Document Header
Auto-generated H1 title + one-line intro. Tells the reader this is partially
auto-generated and everything outside AUTO blocks is safe to edit.

### 2. About This Document (`<!-- AUTO:meta -->`)
Timestamp, module path, and the exact command to re-run the generator.

### 3. Architecture (`## Architecture`)
Human-owned. Inserted as a stub on first run. Fill in:
- A layer table (file → role)
- The happy-path call flow chain

See `ai/tools/MODULE_README.md` for a worked example.

### 4. Directory Tree (`<!-- AUTO:tree -->`)
Live tree from `output_mode="tree_only"`. Always accurate.

### 5. API Signatures (`<!-- AUTO:signatures -->`)
Full signatures from `output_mode="signatures"`. ~5-10% token cost.
Includes Pydantic model field lists as compact comment lines.

### 6. Call Graph (`<!-- AUTO:call_graph -->`) — optional
Scope-filtered function call graph. Shows which functions call which,
including method calls and async context.

---

## What This System Does NOT Auto-Generate

These are intentionally left to humans:

- The Architecture section (call flow, layer map)
- Any module-level gotchas or constraints
- Known technical debt worth flagging
- Links to related modules or docs

If it can be auto-generated accurately, it is. If it requires judgment, it's yours.

---

## Anti-Patterns to Avoid

| Anti-pattern | Why |
|---|---|
| Paraphrasing what a function does | Goes stale; the signature already shows the contract |
| Editing inside AUTO blocks | Your changes will be overwritten on next run |
| Duplicating signatures in prose | `signatures` section already has them |
| Version history / changelog | That's what git is for |

---

## Generator Options

```
python utils/code_context/generate_module_readme.py <subdirectory> [options]

Options:
  --output PATH           Output path (default: <subdirectory>/MODULE_README.md)
  --mode MODE             signatures | tree_only | clean  (default: signatures)
  --call-graph-scope CSV  File stems to include in call graph
  --project-noise CSV     Extra names to suppress in call graph
  --no-call-graph         Skip call graph section
```
