| name | dial-admin-reference |
| description | Find the one authoritative source for a question about this repo — a capability spec, an archived change's rationale, or an ops doc. Use before answering "what is this supposed to do", "why was it built this way", or any question about env vars, theming, the navigation menu, or a version upgrade. |
Finding the authoritative source
A router. Pick the row, open that source, stop. Two questions decide where to look:
- What is this supposed to do? → a capability spec. 116 of them, ~15,500 lines. This is the
behavioral source of truth.
- Why is it like this? → the archived change that introduced it.
proposal.md carries the
problem and the alternatives considered; design.md carries the tradeoff that was accepted.
Everything else is a much smaller tail. docs/ is ~380 lines and covers only ops-facing concerns.
Capability specs — what the system does
openspec/specs/<capability>/spec.md, each ## Purpose then ### Requirement: /
#### Scenario: blocks. The scenarios are the acceptance criteria, so a spec answers "is this
behavior intended?" without reading the implementation.
To find the right capability:
openspec list --specs
openspec show <capability>
grep -rl "<term>" openspec/specs/
.claude/reference/areas.md maps routes and component folders to areas, which is usually the
fastest way from a file you're editing to the capability that governs it.
Analytics is one master spec — openspec/specs/analytics/spec.md. Don't look for, or create,
per-feature analytics specs.
Change history — why it is that way
| Question | Read |
|---|
| What work is in flight right now? | openspec/changes/<name>/ (4 active) |
| Why was this built this way? What else was considered? | openspec/changes/archive/<date>-<name>/proposal.md |
| What tradeoff was accepted, and what was explicitly ruled out? | openspec/changes/archive/<date>-<name>/design.md |
163 archived changes. When a design decision looks arbitrary, it is usually recorded here — check
before re-litigating it.
Ops and product docs
| Question | Read |
|---|
| What changed for deployment in a version? Was an env var added, renamed, removed? | docs/INFRA-CHANGELOG.md |
| What is required to move to a released version, in priority order? | docs/upgrade-plans/<version>.md |
| What is the navigation menu's structure — groups, titles, icons, route links? | docs/MENU-DOCUMENTATION.md |
What does the Preview tag mean and when is it applied? | docs/PREVIEW_TAG.md |
| How are colors, fonts, and images customized without rebuilding the image? | docs/THEME-CUSTOMIZATION.md |
Stack, commands, conventions
openspec/config.yaml — tech stack, path alias, commands, provider stack, entity pattern, grid and
i18n conventions. AGENTS.md for how agents work here. Coding rules live in .claude/rules/ and
load themselves for matching files.
Precedence when sources disagree
- The consolidated spec (
openspec/specs/) is current intended behavior.
- An archived change is historical rationale — accurate about why, possibly superseded about
what. A later change may have replaced it.
docs/upgrade-plans/ is generated from docs/INFRA-CHANGELOG.md; the changelog wins.- Code wins over all of them for what actually happens today. A spec that disagrees with
shipped behavior is a finding worth raising, not a fact to repeat.
Confirm env var names against the code that reads them, not prose — a changelog entry can lag a
rename.
Writing back
When a change alters behavior one of these sources describes, update it in the same change:
- Behavior change → the capability's delta spec, folded into
openspec/specs/<capability>/spec.md
- New or renamed env var →
docs/INFRA-CHANGELOG.md
- Menu change →
docs/MENU-DOCUMENTATION.md and .claude/reference/areas.md, which mirrors the
menu and is what tooling reads
