# CLAUDE.md — operating instructions for Claude Code

## Read this first

1. **`AGENTS.md` is the source of truth for this project.** Read it in full
   before your first edit in any session. It carries the locked decisions, the
   credential register, the open questions, and the full history.
2. **You are required to maintain `AGENTS.md`** under the constitution written at
   the top of it. Update *Current Truth* in place; append to the *Change Log*,
   newest first; never edit a past entry; never delete history. Record decisions
   and plans, not only executed work. Stamp facts `[verified YYYY-MM-DD]` or
   `[assumed]`.
3. Update it **at the end of every working session**, not only when something
   ships. A session that produced a decision and no code still produces a Change
   Log entry.
4. **Read `AGENTS.md` §12 Standing Reminders at the start of every substantial
   session and surface anything live to Pouya.** These are decisions he parked
   deliberately, not settled matters — R1 in particular is his explicit
   instruction to keep raising the licensure wording. A parked decision that
   stops being raised has quietly become permanent, which is the failure mode
   §12 exists to prevent.

## The one rule that matters more than the code

Pouya is a licensed legal professional. **No factual claim about him, his
credentials, his experience, or his practice may appear on a public page unless
it is in the Verified table in `AGENTS.md` §4.**

If a page needs a fact you do not have:

- Do not infer it from context.
- Do not soften it into something defensible ("extensive experience", "years of").
- Do not carry it over from the old site — the old site contained a fictitious
  founder, invented matter values, and a fabricated testimonial.
- **Leave `TODO(pouya): <the exact question>` in the source, and add the question
  to `AGENTS.md` §9.** A build that fails on an unanswered question is a correct
  build.

Read the Forbidden table in §4 before writing any statistic, number, or
superlative.

## Commands

```bash
npm install
npm run dev        # local dev server
npm run build      # static build to ./dist
npm run preview    # serve ./dist locally
npm run check      # astro check — type and template errors
npm run lint       # eslint + prettier check
```

## Where things live

```
AGENTS.md              living project record — read first, maintain always
docs/                  the specs you build from
  01-architecture.md   sitemap, URL map, per-page content outline
  02-design-system.md  tokens, type scale, motion, contrast constraints
  03-content-spec.md   voice, copy rules, per-page copy deck
  04-seo-spec.md       metadata, structured data, sitemap, crawlability
  05-backend-spec.md   intake form, Lambda/DynamoDB/SES, booking, PIPEDA
  06-deployment.md     S3/CloudFront, GitHub Actions OIDC, cutover checklist
src/
  styles/tokens.css    design tokens — the single source of colour and scale
  styles/global.css    reset, base type, utilities
  layouts/             page shells
  components/          UI components
  pages/               routes (file-based)
  content/             content collections; Insights MDX lives here
  data/site.ts         site-wide constants, nav, contact details
public/                static assets served as-is
```

## Conventions

**Framework.** Astro, `output: 'static'`. Never introduce a server runtime
without a Change Log entry recording why.

**JavaScript.** Default to zero. Reach for an Astro island only when a feature
genuinely cannot be CSS or progressive HTML. If you add a `client:*` directive,
say why in the Change Log. A `<details>` element beats a JS accordion.

**Styling.** Plain CSS with custom properties. No Tailwind, no CSS-in-JS, no
utility framework. Every colour, space, and font size comes from a token in
`tokens.css` — no raw hex values and no magic numbers in component styles.

**Accessibility is a build requirement, not a polish pass.** Semantic landmarks,
one `<h1>` per page, heading levels never skipped, visible focus states, all
interactive elements reachable by keyboard, `prefers-reduced-motion` honoured on
every animation. Gold `#c9a876` never sits on cream — it fails contrast at
2.10:1. See `docs/02-design-system.md`.

**Images.** Astro `<Image>` with explicit width and height. AVIF/WebP with
fallback. Never base64-inline an image into HTML — the old site did this with
~1 MB of logo PNGs.

**Fonts.** Self-hosted, subset, `font-display: swap`, preloaded. No Google Fonts
request at runtime — it costs a round trip and adds a third-party call to a
page that collects legal inquiries.

**Every page ships with:** a unique `<title>` and meta description, a canonical
URL, Open Graph and Twitter card tags, and appropriate JSON-LD. See
`docs/04-seo-spec.md`. A page without these is not finished.

**Commits.** Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`).
One logical change per commit. Never commit secrets, `.env` files, or AWS
credentials — deploys use OIDC role assumption.

**Performance budget.** Lighthouse ≥ 95 on all four categories, on mobile, for
every page. Under 100 KB of JS on any route. LCP under 2.0 s on a simulated
Slow 4G connection. Treat a budget breach as a failing build.

## What "done" means for a page

- [ ] Copy written from `docs/03-content-spec.md`, every claim traceable to `AGENTS.md` §4
- [ ] No `TODO(pouya)` left unlogged in §9
- [ ] Unique title, meta description, canonical, OG/Twitter tags, JSON-LD
- [ ] Semantic HTML; keyboard navigable; reduced-motion honoured
- [ ] Lighthouse ≥ 95 mobile, all four categories
- [ ] Renders correctly with JavaScript disabled
- [ ] `AGENTS.md` Change Log entry appended