AGENTS.md — Server-rendered marketing site

Content pages that load fast on a slow phone: rendered on the server, almost no JavaScript, and strict performance gates.

Setup and commands

• dev: pnpm dev
• e2e: pnpm test:e2e
• lint: pnpm lint && pnpm check
• test: pnpm test
• build: pnpm build
• install: pnpm install

Project structure

• src/pages/ — One file per route
• src/layouts/ — Page shells: marketing, article, docs
• src/components/ — Design-skill components as server components
• src/content/ — Markdown content collections with typed frontmatter
• src/styles/tokens.css — CSS variables from the design skill, light and dark
• public/ — Static assets, fonts and _headers

Code style

• Files: kebab-case
• Tests: tests/<template>.spec.ts
• Branches: type/short-description
• Components: PascalCase.astro

Code

• Prefer small, pure functions and explicit types at module boundaries. (Easier to test, review and change.)

Components

• Components read design tokens; no raw hex values, pixel sizes or font names in component code. (One token change restyles the product.)

Data

• Analytics events are object_action in snake_case and come from the experience skill’s measures. (Names stay consistent across teams and tools.)
• Every page sets a unique title, description and canonical URL from frontmatter. (Search and sharing previews stay correct.)

Errors

• Every async action has loading, empty, error and success states, matching the experience skill. (Unhandled states are where users get stuck.)

Security

• Secrets never live in the repository; read them from the environment or a secret store. (A leaked key outlives the commit that removed it.)
• Validate every input on the server, even when the client already did. (Clients can be bypassed.)
• Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. (Cheap protection against the most common attacks.)

Performance

• Ship zero JavaScript by default; every island needs a reason in the pull request. (Content pages are judged on first load.)
• Self-host fonts with font-display: swap and preload the one used above the fold. (Avoids invisible text and layout shift.)

Accessibility

• Use native elements first; add ARIA only when no native element fits. (Native controls bring keyboard and screen-reader support for free.)
• One h1 per page; headings never skip a level. (Screen-reader users navigate by headings.)

Design and journeys

When a Celestial design skill is in use, write its tokens as CSS custom properties in src/styles/tokens.css, and build its components in src/components with the same names and variants. Components read tokens only — no raw colours, sizes or font names.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events object_action from its measures.

Testing and checks (must pass before a pull request)

Pull requests

• Branching: Trunk-based; content edits can merge with one review from the content owner.

Review checklist

• Correctness: does it do what the issue asks, including edge cases?
• Readability: could a new teammate change it safely?
• Architecture: is it in the right place, with the right boundaries?
• Security: inputs, secrets, permissions, dependencies
• Performance: budgets, queries, bundle size
• Tests fail when the code is broken (flip a condition and re-run)
• Check the preview on a phone before approving
• Content changes reviewed for voice against the design skill

Definition of done

• Acceptance criteria met and demoed on the preview link
• Tests added for new behaviour and every state
• Accessibility and performance gates green
• Analytics events named from the experience skill
• Docs or changelog updated when behaviour changes

Release

• Small pull requests (aim for under 400 changed lines)
• CI green before review
• Squash-merge to main; main is always deployable
• Every release has a written rollback path
• Merge deploys; scheduled content publishes by date in frontmatter

Incidents

• Redeploy the previous build; content rollbacks via git revert

Generated from the Celestial engineering skill “Server-rendered marketing site” (engineering core v1.0, checked 2026-10-25).