# Recipe: Add Page

This is a Post.Build.Ship reference recipe, not a standalone skill.

Use only when `post`, `build`, or `ship` is already active and the approved task is adding a page, route, screen, or cross-surface route.

This recipe supplements the approved outcome envelope. `post` owns product decisions, acceptance,
boundaries, risk, and QA intent; `build` owns adaptive implementation and proof; `ship` owns final
ownership, QA, drift, and commit coherence. Optional peer review is never introduced by this recipe.

## Intake Decisions

Collect or infer:

1. route path, for example `/about`
2. route key, for example `about`
3. page name and H1
4. public, auth-gated, or role/authorization-gated access
5. target surfaces: web, desktop, mobile, shared
6. shared component location or surface-specific implementation
7. navigation exposure: header, footer, mobile menu, sidebar, deep link
8. SEO or metadata requirements for web
9. screenshot or e2e coverage expectations
10. explicit non-goals

Ask only for missing product decisions. Do not ask about implementation mechanics when the repository pattern is discoverable.

## Public Page Checklist

For a public page:

1. add or reuse a shared page component when multiple surfaces need it
2. add the route key and path to the shared route map when the repository has one
3. add the path to the public route protection config
4. register the route in each target surface
5. add only approved navigation links
6. preserve existing auth, docs, profile, booking, Studio, and role-gated behavior
7. add tests for route key/path resolution, public-route status, protected-route invariants, navigation link routing, and route registration
8. add web screenshot or e2e coverage when the harness exists and the route is user-visible on web

## Auth-Gated And Role-Gated Checklist

For an authenticated or role-gated page:

1. add the route key and path
2. do not add the path to public routes unless the page is explicitly public
3. confirm anonymous redirect or blocking behavior
4. use the existing authorization provider or policy for role gating instead of duplicating checks
5. add tests for protected status, anonymous behavior, authorized access, and unauthorized denial
6. add e2e when a configured harness exists and the change affects user-visible routing or auth behavior

## Cross-Surface Registration

Apply only the surface entries that match the approved scope.

Web:

1. add the app route file
2. include route metadata or head only when supported by current router types
3. regenerate generated web route trees such as `routeTree.gen.ts` via the app generator or route plugin before web typecheck
4. do not hand-edit generated route trees unless generation is unavailable and the handoff explicitly allows it

Desktop:

1. add the enabled route key when the desktop navigation provider has an allow-list
2. edit hand-authored desktop route tree/source files directly
3. add route presence tests where the route tree is testable

Mobile:

1. add the file-based route directly, such as an Expo Router file route
2. update mobile route tests
3. update auth wrapper or route-protection tests only when route protection behavior needs documentation

Shared:

1. classify the page by every consuming surface before choosing its renderer, applying
   `react-native-web-to-dom.md`
2. mobile-owned UI remains React Native; UI rendered only by web or Electron is DOM-first
3. use a tested platform-selected implementation or required platform-owned renderer when browser
   and native share data or structure
4. export browser-only behavior through an isolated explicit subpath, not a mobile-facing barrel
5. retain existing RNW aliases and SSR CSS as transitional infrastructure while remaining routes
   still render RNW
6. avoid browser-only, Electron-only, storage, or API calls in mobile-facing shared code unless
   explicitly isolated and in scope

## QA Matrix

`build` owns QA selection and execution under `quality-assurance.md`.

Preflight and focused feedback:

1. run preflight only for genuine dependency, environment, or baseline uncertainty
2. use the cheapest safe targeted route-protection, navigation, or route-registration tests when
   they shorten the implementation loop
3. reuse passing results until a relevant proof input changes

Authoritative final QA:

1. regenerate route files and create required screenshots or other proof before final validation
2. select relevant `test:unit` commands for changed runnable apps or packages
3. select relevant `typecheck` commands for changed runnable apps or packages
4. run web e2e when web routing, screenshot coverage, auth, SSR, browser rendering, or user-visible
   navigation changes and a harness exists
5. rerun only the manifest portions invalidated by a relevant content or runtime-state change
6. do not run production release, EAS build, or desktop packaging unless explicitly in scope and
   allowed by the owning skill rules
7. never run `db:generate`, `db:migrate`, or `db:push`; apply
   `database-migration-lifecycle.md` when page work includes schema source

## Commit Unit Guidance

Page additions often form one narrative commit with their tests and generated route artifacts, but
Build and Ship may use any coherent partition that tells the implementation story.

## Build Launch Prompt Delta Example

Future page-addition packets may reference this recipe and list concrete deltas inside the compact
Post sections:

```md
Recipe: add-page

Deltas:

- Route path: `/about`
- Route key: `about`
- Access: public
- Surfaces: web, desktop, mobile
- Shared component: `HomepageAboutPage`
- Navigation: header after FAQ, footer before Book
- H1: Founder-led cross-platform app development for enterprise teams.
- Non-goals: no redirect, no auth behavior changes, no dependencies
```