Add a screen

Every file a new Bridge OS screen touches, in the order you'll touch them.

1. Pick the template. From the screen's job (Picking a template). Note it; you'll add the screen to its app page at the end.
2. Create the route. A server page.tsx under src/app/(shell)/<area>/ that renders a client _components/<name>-content.tsx, as every Bridge OS page does. Outside the shell only if signed-out visitors must see it.
3. Set the width. Import the tier from src/lib/layout/widths.ts (LAYOUT_STANDARD, LAYOUT_WIDE, LAYOUT_FORM). Add no padding: the shell gives it.
4. Decide who can see it. Signed-in only is the default. A public or optional-sign-in page goes in src/proxy.ts; its signed-out view shows what you'd get.
5. Write the header. A 24px title, a one-line subtitle, at most one primary action. A sub-page gets a "← Back" link above it.
6. Load each region on its own. Each card or table: DataState inside its frame, with a measured skeleton. The shell's loading.tsx only covers moving between pages.
7. Put tabs in the address. Tabs read and write ?tab= (docs/DEEP-LINKS.md); the default tab has no parameter.
8. Add it to the navigation, if it's a main area. Both the top bar (top-nav.tsx) and the phone bar (mobile-bottom-nav.tsx). Most screens are reached from a page instead.
9. Update the docs in the same change. CLAUDE.md for new rules, components.md if you touched a shared component, docs/HANDOFF.md for what's in flight (Bridge OS's AGENTS.md).
10. Walk the screen recipe. The checks on Build a screen, then add the screen to the Bridge OS app page (content/product/screens.ts).

See also: Picking a template, the screen recipe.

• Bridge OS route survey (2026-11-02): page.tsx → *-content.tsx, widths.ts, proxy.ts, top-nav and mobile-bottom-nav.
• Bridge OS AGENTS.md (docs maintenance), docs/DEEP-LINKS.md.