Page creation guide

Step-by-step: new route

1. Create the file under apps/cosmos/digital-services/src/pages/ using existing naming conventions (index.astro for directory index, nested folders for URL segments).
2. Wrap with Layout.astro unless you have a deliberate exception (e.g. minimal layout for a special case).
3. Set title and description so SEO components (SeoHead / layout contract) get explicit values for non-generic pages.
4. Reuse shared packages (@cosmos/ui-astro, @cosmos/theme, etc.) before adding new app-local components.
5. If the route must be protected (under /portal or /admin):
   • Confirm the path prefix is listed in PROTECTED_PATH_PREFIXES in wrangler.gateway.toml.
   • Confirm Wrangler routes include that host’s /portal* or /admin* patterns.
   • Do not rely on “hiding” the link—edge enforcement is what matters.
6. If the page calls a worker or third-party API from the browser, check public/_headers CSP: connect-src, form-action, and related directives must allow the origin.
7. Tests:
   • Add or update Jest tests for non-trivial page or script behavior (src/__tests__/).
   • Add or update Playwright specs for meaningful user-visible flows (e2e/).
8. Quality gates before merge (from repo root):
   • yarn workspace cosmos-digital-services lint
   • yarn workspace cosmos-digital-services test:unit
   • Relevant yarn workspace cosmos-digital-services test:e2e (or full test if you own the whole change).

Done definition

• Route renders with correct layout and metadata.
• No CSP/console errors for intended network calls.
• Protected routes actually redirect when unauthenticated (worker + Access in target env).
• Tests or explicit rationale if exempt (rare for user-facing pages).
• If commands, env, or worker routes changed: update Configuration reference, Environment variables, or Deployment guide as appropriate.