CLAUDE.md — operating instructions for Claude Code

Read this first

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.
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].
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.
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

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

5.6 KiB Raw Blame History