# ADR-003 — GUI→API parity is a hard, checked rule

**Status:** accepted · **Date:** 2026-10-13 · **Deciders:** RG

*Ported from YoutubeManager (same decision, same enforcement).*

## Context

The product is consumed both by people (web GUI) and by automation (scripts and publishing
workflows hit `/api/v1`). When a GUI feature exists without an API twin, automation falls behind
and users script the GUI instead. A rule that says "add an API endpoint if API access is needed"
makes parity optional, and optional parity decays.

## Decision

- Parity is mandatory in the GUI → API direction (`API-PARITY.md` §1). The API may be a superset.
- A living `FEATURE-REGISTRY.md` maps every feature to its GUI routes, API endpoints, service
  function, doc section and status. It is parsed by `tools/check_rules.py --parity`.
- Every fragment declares `gui_routes`, `api_endpoints` and, if needed, `parity_exception`.
  A done fragment with GUI routes and neither of the other two fails validation.
- The only accepted exceptions are browser concepts (OAuth consent, session, navigation).
- Reviewers verify semantic parity with the table in `API-PARITY.md` §1.

## Consequences

- Adding a GUI feature costs an API endpoint and a doc section in the same change. That is the
  intended cost.
- The registry doubles as the "what exists now" inventory and as the map an AI agent reads before
  touching a feature.
- The initial build of this project was written to the registry: every GUI capability shipped
  with its API twin or a reasoned browser exception on day one.