# `docs/claude/` — AI-agent reference for this project

Per **DOC-07** in `mgf-common`'s [`DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md):
every project that wants AI agents to be productive ships a
`docs/claude/CLAUDE.md` in dense-lookup format — facts,
file:line citations, pre-approvals — NOT human prose.

## File layout

| File | Purpose |
|---|---|
| [`CLAUDE.md`](CLAUDE.md) | Project-specific AI-agent reference. Dense lookup: file map, cross-cutting patterns, build + release recipe, common pitfalls, recently-touched areas. |

This sibling does NOT ship a `claude_common.md` (the
cross-project rules live at the **operator's** machine-global
`~/.claude/` directory; siblings inherit them through the
operator's environment). The two-layer pattern from
[`mgf-common/docs/claude/`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/claude/)
applies to the cornerstone; siblings collapse to just
`CLAUDE.md`.

## When to update `CLAUDE.md`

After every code or config change that:

- Adds, removes, or corrects a fact useful in future
  conversations (gotchas, invariants, non-obvious design
  decisions, fixed bugs).
- Changes the file map or the public surface.
- Lands a new release.

The "Recently-touched areas" rolling log at the bottom of
`CLAUDE.md` is the canonical place for the version-bump
note + a one-line summary of what changed.

## What does NOT go in `CLAUDE.md`

- **Marketing.** "Our project is the best at X." Cut.
- **Tutorials.** Belongs in `docs/recipes/` or the README.
- **API reference.** Belongs in `PUBLIC_API.md` (the contract)
  or — for the long-form description — the
  [`docs/reference/`](../reference/) bucket if the sibling
  grows one.
- **Ephemeral details.** Current branch name, in-progress
  state, step-by-step task lists. Those belong in tasks or
  plans, not here.
