---
summary: Optional sibling file in an entry's directory — plan, design notes, gotchas.
---
# Companion
A **companion** is an optional sibling file inside an entry's
directory, capturing content too structured to live in the body of
`index.md` — a plan, a design rationale, gotcha notes — without
turning the body into a journal.
## Shape
The set of recognised companions is closed. A reviewer skimming
an entry directory knows exactly what each recognised filename
signals.
The list:
- `plan.md` — a *living* implementation plan.
- `design-decision.md` — alternatives evaluated, the chosen one,
and the re-evaluation triggers. Mirrors a lightweight ADR but
scoped to the parent entry.
- `implementation-notes.md` — gotchas, surprising constraints,
third-party quirks discovered during the work.
Files outside the list pass through untouched. A typical
[issue](concept://issue) directory:
```text
docs/issues/017BF8X79SCCM-add-proptest-strategies/
index.md (mandatory — the entry itself)
plan.md (optional companion)
design-decision.md (optional companion)
implementation-notes.md (optional companion)
mockup.png (ignored by cartulary)
```
## Configuration
None. The companion list lives in the binary, not in
`cartulary.toml`.
## Validation
`cartu check` only looks at the directory layout — not at the
content of companion files (treated as opaque Markdown, rendered
as-is by `cartu site build`).
## Commands
Companions are plain Markdown — edit them with your editor of
choice. `cartu issue show <id>` lists the companions present in
an entry directory; `cartu site build` renders them on the
published site under the parent entry.