acartine/map-repo

Style Guidelines

• Each README: 10-30 lines. Lead with purpose, then contents.
• Reference key files, types, and functions by name so agents can grep for them.
• No badges, no emojis, no boilerplate filler.
• ARCHITECTURE.md should let an agent understand the repo's purpose, structure, and data flow in under 60 seconds.
• Use tables for directory maps. Use code blocks for flow diagrams.
• Keep descriptions factual and current — don't document aspirational state.

ARCHITECTURE.md Template

# <Project> Architecture

<One-sentence purpose.>

## Data/Control Flow

<Short flow diagram or description.>

## Directory Map

| Path | Purpose |
|------|---------|
| [`path/`](path/README.md) | One-line description |

## Key Entry Points

- **<Role>**: `file.py` — `function()`

## Build System

<Package manager, key targets, how to run.>

Per-Directory README Template

# <directory name>

<One-sentence purpose.>

## Key Files

- **`file.py`** — what it does

## Key Types

- `TypeName` — what it represents

## Key Functions

- `function_name()` — what it does