# CONTEXT.md format

## Structure

```md
# {Context name}

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

## Language

**Order**:
{One or two sentences describing the term.}
_Avoid_: Purchase, transaction

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

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

## Rules

- **Be opinionated.** Where several words exist for one concept, pick the best and list the rest
  under `_Avoid_`. A glossary that refuses to choose is a thesaurus, and settles nothing.
- **Keep definitions tight.** One or two sentences. Define what the term *is*, not what it does.
- **Only terms specific to this project.** General programming concepts (timeouts, error types,
  utility patterns) do not belong, however heavily the project uses them. Before adding a term, ask
  whether it is unique to this context or just general vocabulary. Only the former earns a place.
- **Group under subheadings** once natural clusters emerge. A flat list is fine while the terms
  belong to one cohesive area.

## Single vs multi-context repos

**Single context**, which is most repos: one `CONTEXT.md` at the root.

**Multiple contexts**: a `CONTEXT-MAP.md` at the root lists them, where they live, and how they
relate:

```md
# Context map

## Contexts

- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping

## Relationships

- **Ordering → Fulfillment**: Ordering emits `OrderPlaced`; Fulfillment consumes it to start picking
- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched`; Billing generates the invoice
- **Ordering ↔ Billing**: shared types for `CustomerId` and `Money`
```

Infer which structure applies:

- `CONTEXT-MAP.md` exists → read it to find the contexts
- Only a root `CONTEXT.md` → single context
- Neither → single context; create the root `CONTEXT.md` lazily when the first term resolves

Where several contexts exist, infer which one the current topic belongs to, and ask if it is unclear.