# ADR-NNNN — <short imperative title> (/docs/maintain/_templates/adr)

- **Status:** Proposed
- **Date:** YYYY-MM-DD
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** —
- **Approved on:** —
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `content/docs/maintain/app-flow/<slug>.mdx` (when the UI changes, ADR-0008), `content/docs/maintain/prd/<slug>.mdx`,
  `content/docs/maintain/architecture/system.mdx`, … (the living docs this decision creates or changes — see ADR-0002)

## Context [#context]

What problem are we solving? What forces, constraints and facts about the current codebase
make this decision necessary *now*? State only what is true and verifiable.

## Decision [#decision]

The decision, stated plainly and in the present tense ("We use X", "Y lives in Z").
Include the concrete shape of the change: directories, file names, contracts, commands.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — `<name>` | | | Chosen / Rejected |
| B — `<name>` | | | Chosen / Rejected |

## Consequences [#consequences]

**Positive**

- …

**Negative / accepted trade-offs**

- …

## Content invariants [#content-invariants]

Which invariants in `AGENTS.md` §6 this touches, and how it keeps them. If it departs from
one, say so explicitly. That departure is part of what the owner approves.

## Security considerations [#security-considerations]

Mandatory — never omit this section (ADR-0005). For a change with no security surface,
"None — this change touches no data, no endpoint and no secret" is a valid answer; an omitted
section is indistinguishable from not having thought about it.

Where there is a surface, state: what content or data it handles and its classification,
whether anything private can reach a public surface, what authorization applies and where it is
enforced, what leaves the system (search provider, host, analytics), and what residual risk is
accepted. Link `content/docs/maintain/security/<slug>.mdx` when the feature warrants its own analysis.

## Implementation notes [#implementation-notes]

What actually changes in the repo once this is approved. Keep this list checkable — it is
the scope of the implementation that follows the approval.

- [ ] …
- [ ] Tests — the happy path **and** the obvious failure paths (ADR-0007). If some part cannot
      be unit-tested, say which, and say what was verified instead.
- [ ] `bun run lint`, `bun run types:check` and `bunx next build` pass.

## Docs to update on implementation [#docs-to-update-on-implementation]

Living design documents are snapshots of the system as it stands — edit them in place, never
as a log of what changed (ADR-0002). Delete anything in them that is no longer true.

- [ ] `content/docs/maintain/app-flow/<slug>.mdx` — if the UI changed
- [ ] `content/docs/maintain/prd/<slug>.mdx` — requirements + user stories
- [ ] `content/docs/maintain/erd/system.mdx` — if persisted data changed
- [ ] `content/docs/maintain/architecture/system.mdx` · `content/docs/maintain/dfd/` · `content/docs/maintain/state/` · `content/docs/maintain/sequence/` ·
      `content/docs/maintain/api/` · `content/docs/maintain/rbac/` — whichever the change requires (ADR-0002)
- [ ] `content/docs/maintain/security/` — `secrets.mdx` if a secret is introduced; `threat-model.mdx` if the
      attack surface changed; `<slug>.mdx` if the feature warrants its own analysis
- [ ] `AGENTS.md` — \<what changes, if the way we work changed>
- [ ] `README.md` — \<what changes, if the project overview changed>
- [ ] `content/docs/maintain/adr/index.mdx` — index row + status