Screens registry guide (`.agents/screens/`)

Screens registry guide (.agents/screens/)

.agents/screens/ is the canonical ASCII map of every rendered screen and
route. Agents (QA, dogfood, navigation, planning) rely on it instead of
loading each page, so it must stay accurate at every commit. Stale ASCII is
worse than none — it misleads the next agent into acting on a UI that no
longer exists.

The registry has two layers:

• screen-INDEX.txt — master list: user flows, screen list (name / route /
  source file), layout shells, component roots, retired routes, API-only
  routes, styling, analytics, known gaps. Bump its generated: line on edit.
• screen-<flow>-<n>.txt — one per screen. Frontmatter
  (screen / name / route / file), an ASCII diagram in a fenced block,
  a ## Elements table (Element / State / Description), and a
  ## Behavior section. Flow buckets: discovery, create, studio,
  auth, admin.

scripts/check-screen-staleness.ts (wired into mise run validate and
.github/workflows/security.yml) automates three checks: freshness
(generated: date in screen-INDEX.txt is ≤30 days old), coverage (every
route in routeTree.gen.ts’s FileRoutesByFullPath interface is referenced
in the INDEX), and a known stale-copy pattern (Sign in -> /brand-kit). It
cannot check ASCII/Elements/Behavior fidelity — that’s on the agent making
the change.

When you MUST update the screens

Update the affected screen-<flow>-<n>.txt (ASCII + Elements + Behavior) AND
screen-INDEX.txt when a change alters anything a user or agent would see or
hit. That includes:

• visible layout, copy, elements, states, or interactions on any screen
• a route’s path, auth gate, redirect target, or post-action destination
• adding, removing, or repurposing a screen or route
• a layout shell or shared chrome component (Header, Footer, StudioChrome,
  layout shells) that changes multiple screens at once

When you do NOT need to update

• pure backend / API-only route changes with no rendered UI (the INDEX lists
  these under “API-only routes”)
• refactors with zero visual or routing change
• dependency bumps, build config, tests

New screen

1. Add screen-<flow>-<n>.txt (next free number in that flow) with frontmatter,
   an ASCII diagram matching the rendered page, an Elements table, and Behavior.
2. Add a row to screen-INDEX.txt’s “screen list” with name / route / source file.
3. If it introduces a new flow bucket, add it under “user flows”.

Removed or repurposed route

1. Move its screen-INDEX.txt row from “screen list” to “retired routes”,
   noting the redirect target or a DELETED marker, matching the existing
   format.
2. Delete the screen-<flow>-<n>.txt file unless the screen is still reachable.

Fidelity rules

• The ASCII diagram must match the actual rendered screen at the current commit.
  Re-read the component source; never copy an old diagram.
• Use callout arrows (←) for non-obvious regions, as the existing files do.
• Keep the Elements table State values precise (required, conditional,
  action, ambient, static) — agents reason about affordances from these.
• If a change can’t be fully captured in ASCII, update the Elements/Behavior
  prose and add an entry under “known gaps” in screen-INDEX.txt.

Pre-finish check

If you touched anything under apps/web/src/routes/ or a shared chrome
component, ask: did the rendered screen change? If yes, the matching
screen-*.txt and screen-INDEX.txt must change in the same commit.