# CONTEXT.md — Shared Project Language

`CONTEXT.md` is a **glossary and nothing else**. It exists so that the user, the
code, and future agents use the same words for the same concepts. It is totally
devoid of implementation details, decisions, plans, or work logs.

A single `CONTEXT.md` lives at the repo root. If a `CONTEXT-MAP.md` exists at the
root, the repo has multiple contexts — read it to find which `CONTEXT.md` the
current topic belongs to.

Create the file lazily — only when the first term is actually worth recording.

## Structure

```markdown
# {Context Name}

{One or two sentences: what this context is and why it exists.}

## Language

**Order**:
A customer's request to purchase one or more items.
_Avoid_: Purchase, transaction

**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request

**Customer**:
A person or organisation that places orders.
_Avoid_: Client, buyer, account
```

## Rules

- **Be opinionated.** When several words mean the same thing, pick the best one
  and list the rest under `_Avoid_`.
- **Keep definitions tight.** One or two sentences. Define what it *is*, not what
  it *does*.
- **Only project-specific terms.** General programming concepts (timeouts, retry,
  cache) don't belong, even if the project uses them heavily. Ask: is this unique
  to this project's domain, or generic? Only the former belongs.
- **Group under subheadings** when natural clusters emerge; a flat list is fine
  otherwise.

## What does NOT go in CONTEXT.md

- implementation details
- specs, decisions, or rejected alternatives → spec / ADR
- operational procedures → runbook
- validation rules for the current work → spec
- work logs, temporary notes, speculative ideas