# Documentation Standards

## Philosophy
Prefer self-documenting code and in-code comments over external documentation.
Write external docs only when the information cannot live closer to the code.

## What belongs where

| Content | Where |
|---------|-------|
| Why a function does something non-obvious | Inline comment at the relevant line |
| Contract, parameters, exceptions | Docstring on the function |
| Module purpose, dependencies, exports | File header comment |
| Architecture, data flow, system-level decisions | `docs/overview.md` |
| Setup, configuration, usage for humans | `README.md` |
| Agent/AI session rules | `AGENTS.md` |

## Style
- Brief and technical. No preambles, no summaries, no filler.
- No emojis.
- High-level overview only in external docs — implementation details belong in code.
- Present tense, imperative mood for instructions.

## Python docstrings
All public functions use Google style: one-line summary, then `Args:`, `Returns:`, `Raises:` sections if non-trivial. List every domain exception the function can raise directly or via propagation.

```python
def crop_save(src: Path, dst: Path, box: tuple[int, int, int, int]) -> None:
    """Crop src image to box and write to dst, overwriting if present.

    Args:
        src: Source image path.
        dst: Destination path; parent directory must exist.
        box: (x, y, w, h) in pixels.

    Raises:
        FileNotFoundError: If src does not exist.
    """
```

## JS file headers
Every JS file starts with a block comment stating: purpose, dependencies (Depends on:), exports (Provides:).

```js
/*
 * helpers.js
 * Pure utility functions with no dependencies on other application modules.
 *
 * Provides: esc(), toast(), isDesktop()
 */
```

## When NOT to document
- Do not add docstrings or comments to code you did not change.
- Do not document implementation details that are already clear from the code.
- Do not keep comments that describe what the code does when the code already says it clearly.
- Do not update `docs/overview.md` for implementation details — only for structural/architectural changes.