# Dial Admin Reference

> 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.

- Skill: `epam/dial-admin-reference` (Agent Skill)
- Install (CLI): `npx skillmds@latest add epam/dial-admin-reference`
- Raw SKILL.md: https://api.skillmd.com/api/skills/epam/dial-admin-reference/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: epam (https://skillmd.com/u/epam)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/epam/dial-admin-reference

---


# 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:

```bash
openspec list --specs                     # all capabilities with requirement counts
openspec show <capability>                # one spec
grep -rl "<term>" openspec/specs/         # when you don't know the capability name
```

`.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 a folder of sub-capabilities**, not one spec. `openspec/specs/analytics/spec.md` is a
short index — read its routing table, then open the single sub-capability that answers the question:
`analytics/query-builder` (authoring a query: Form, JSON, SQL, AI views), `analytics/query-viewer`
(running one and reading the result), `analytics/saved-queries`, `analytics/tables`,
`analytics/conversations-listing`, `analytics/conversation-trace-listing`,
`analytics/conversation-trace-detail`, `analytics/pipelines`, `analytics/evaluators`. Don't create a
top-level `analytics-*` folder.

## 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

1. **The consolidated spec** (`openspec/specs/`) is current intended behavior.
2. **An archived change** is historical rationale — accurate about *why*, possibly superseded about
   *what*. A later change may have replaced it.
3. **`docs/upgrade-plans/`** is generated from `docs/INFRA-CHANGELOG.md`; the changelog wins.
4. **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