# 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 This is Pouya's public marketing surface, and the site it replaces carried fabricated credentials. **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.** (§4 does not verify licensure either way — so do not describe him as "licensed", or as a "legal professional", anywhere, this file included. State the reason for the rule, not a credential the register cannot vouch for.) 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): ` 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. ## How work is executed here Pouya is the architect. He makes the decisions and hands you the task. **You implement, then you adversarially review your own work before calling it done.** This is the standing agreement — it applies to every substantial change without being restated in the prompt. **Run `/build ` for any substantive change.** It encodes the loop: 1. **Plan** — read `AGENTS.md` (including §12 Standing Reminders, and surface anything live), read the governing specs, name the decisions the task touches, and **stop and ask on any conflict**. A blocked build is a correct build. 2. **Implement** — following the conventions below. 3. **Adversarial review** — invoke `adversarial-reviewer` on the diff. **D20: `claims-auditor` does NOT run per step.** It runs once, at cutover, over the whole finished site. 4. **Resolve** — fix each finding or decline it with a stated reason. Re-review material fixes. 5. **Verify** — run the checks. Never report a check as passing that you did not run. 6. **Record** — append the `AGENTS.md` Change Log entry. `/review` runs phase 3 alone. `/wrap` runs phase 6 at session end. **Agent definitions load at session start.** An edit to `.claude/agents/*.md` does not reach the session you made it in — the brief in force is the one that was on disk when the session began. After committing a change to one, **restart before relying on it, and say in the report which version actually ran.** Found 2026-08-30: the gloss lens was added to `claims-auditor` and the agent then reconstructed it from the `AGENTS.md` Change Log rather than having it in its brief, which is luck, not process. **Think deeply before acting.** Extended thinking is on by default for this project (`.claude/settings.json`), and `/build` and `/review` request it explicitly. The planning and review phases are where it earns its cost — a defect reasoned out before implementation is far cheaper than one found after. ### Why the review is adversarial, and what would break it Two rules make the difference between a review and a rubber stamp: **Do not brief the reviewers on why your work is correct.** Give them the diff and the specs, nothing else. Your rationale anchors them, and an anchored reviewer produces agreement rather than review. They must form an independent view from the artefact — that independence *is* the mechanism. **The reviewers are instructed to treat uncertainty as a defect.** They will sometimes be wrong, and that is the intended trade. Explaining why a finding is mistaken costs minutes; a missed defect on this project's public marketing pages costs considerably more — the site this replaces carried fabricated credentials, and that is the standard being corrected. Do not read a finding as an accusation, and do not argue a reviewer down — either fix it, or record the reason you declined it so a later reader can see the judgement was made rather than missed. **Two reviewers, because they catch different things — but they no longer run at the same time.** `adversarial-reviewer` reads the code. `claims-auditor` reads the copy against the §4 register and knows nothing about whether the code is elegant. A generic reviewer consistently under-weights the professional-conduct check, which is the highest-stakes failure mode on this project — so it keeps its own pass rather than being folded into the code review. **D20, 2026-08-30 — the claims pass moved to cutover.** Per step it is `adversarial-reviewer` alone. `claims-auditor` runs **once, over the whole finished site**, as a blocking item on `docs/06`'s cutover checklist. Pouya's reasoning, and it is a calibration and not an erosion: nothing has shipped, so every claims finding so far has been about a page no visitor can reach — the risk is deferred to cutover anyway, and one pass over twenty finished pages catches **more** than nine passes over drafts, because it sees the site as a reader does. The `/med-arb/` ADRIC gloss is the proof: no individual claim was false, the defect was **adjacency**, and adjacency does not exist until the pages sit next to each other. The code reviewer stays per step because what it catches **compounds** — an accessibility or crawlability defect propagates into the next page built on it, and a claims defect does not; it sits there until someone reads it. **What it costs is recorded in `AGENTS.md` D20, not summarised away here.** Read it before proposing any further relaxation: `claims-auditor` has caught defects that would have been serious on a live page, and D20 accepts that such a defect may now live in an unpublished draft for weeks. Two things carry that risk in the meantime — **`npm run check:claims`, which is unchanged and runs on every build and both deploy paths**, and **Pouya reading the copy as it is built**. Neither is optional, and neither is a substitute for the cutover pass. ## 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 check:claims # §4 Forbidden, enforced on dist/ — run it after a build npm run check:intake # the form's field table vs the Lambda's — they are two on purpose npm run og:proof # every og:image resolves; every card headline IS its page's

npm run lighthouse # the performance budget. LOCAL ONLY — needs Chrome, not in CI npm run bio:pdf # re-renders the committed one-page PDF from /bio/. LOCAL ONLY npm run lint # eslint + prettier check npm run format # prettier — rewrite files in place npm run deploy # build + deploy from this machine (see docs/06) ``` **Four of those are gates and two of them cannot run in CI.** `check`, `check:claims`, `check:intake` and `og:proof` are pure Node and run anywhere. `lighthouse` and `bio:pdf` drive an installed browser, and the Gitea runner has none — so they are keyboard gates plus blocking items on `docs/06`'s cutover checklist, and **they are deliberately not wired into `npm run build` or either deploy path.** Do not describe either as gating a deploy: a check described as running where it cannot is the defect `AGENTS.md` Q22 turned out to be. **`og:proof` and `check:intake` exist because two facts in this repo are deliberately duplicated**, and a duplicated fact needs a mechanism rather than a comment. `og:proof` compares each generated OG card's headline against its page's own `

` — **text baked into a JPEG cannot be grepped by `check:claims`**, so that comparison is the only thing keeping card copy inside the claim register. `check:intake` compares the form's field table against the Lambda's, which are independent because a server that validates against a list the client shipped it is not validating. ## 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, Gitea Actions, IAM, cutover checklist src/ content.config.ts content collections — Content Layer API, NOT content/config.ts 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/insights/ Insights MDX only; the config sits above, not in here data/site.ts site-wide constants, nav, contact details public/ static assets served as-is ``` ## Conventions **Framework.** Astro **7.x**, `output: 'static'` (D1 as amended). Never introduce a server runtime without a Change Log entry recording why. The major is pinned deliberately — check `npm view astro version` before changing it. **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 `
` 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 `

` 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`. **Anything a spec makes a claim about must be reachable from the repository.** If the artefact lives only in Drive, in a console, or on someone's laptop, no reviewer can compare the claim against it and the claim is **unverifiable by construction** — not merely unverified. Commit the artefact, or commit a faithful extract with its provenance and the command that produced it. This has cost twice. `AGENTS.md` Q24 was the AWS hosting guide, the only record of how the infrastructure was hand-built, living outside the repo. Q32 was the infinity mark: it was traced from the old site's *loading placeholder*, the source comment said so in as many words — and **two adversarial review passes still could not catch that the shape was wrong**, because the real artwork was not in the repo to compare against. Stating a doubt is not enough when the thing that would resolve it is unreachable. Tracked as R14. **A command that did not run is not evidence of absence.** Check that a tool exists before trusting its silence, and read exit status, not just stdout. This project ran `timeout 60 ls "$DRIVE"` four times, got empty output each time, and reported the brand assets unreachable — `timeout` is not installed on macOS, so the command had never executed and the directory was fully readable all along. Empty output from a command that failed to start looks exactly like empty output from a command that found nothing. Same family as *a sweep is a command, not a claim*: the claim must rest on output you actually read, from a command that actually ran. **And never suppress stderr in a verification script.** *Pouya's convention, 2026-08-28, from verifying the deploy credential (`AGENTS.md` Q22).* This is the rule above from the other direction, and it is the more dangerous direction: **`2>/dev/null` converts "it failed" into "it found nothing", and those are opposite results.** His first pass at eight `simulate-principal-policy` checks returned empty for all eight; the suppression was hiding an `InvalidInput` error, and the empty output was then explained with a guess — *"probably lacks the permission"* — which is the answer the check was supposed to produce, arrived at without the check running. The actual cause was a **zsh parameter-expansion bug**: `$ACCT:user/` parses `:u` as a history modifier and yields `327082975128ser/`. Braces fixed it. So: no `2>/dev/null` in anything whose output you intend to believe, read the exit status, and when a result is empty **remove the suppression and look before proposing a cause.** A guessed explanation for an empty result is worse than no result, because it closes the question. **And never TRUNCATE the output of a check you intend to believe.** *Added 2026-08-29, from build step 5.* This is the stderr rule's twin and it is easier to commit, because the command runs and the pipe looks harmless. `npm run check` prints its verdict as three lines — `- N errors`, `- N warnings`, `- N hints` — followed by a blank line. **`npm run check 2>&1 | tail -3` therefore returns warnings, hints and the blank line, and silently drops the errors line.** It was run four times that way and reported as passing each time; `astro check` was exiting **1 with 10 type errors**, and both deploy paths run it before the build, so nothing could have shipped. `adversarial-reviewer` found it. The fix is not a bigger `tail`. **Read the exit status** — `cmd; echo "exit=$?"` or `cmd || echo FAILED` — because it is the one signal a pipe cannot silently reshape. `head`, `tail`, `grep -c` and `| grep -i error` all have the same failure mode: they turn a verdict you did not read into a verdict you assert. Same family as *a sweep is a command, not a claim*, and note the asymmetry that makes it dangerous — the truncation only ever hides the bad news, because the error line comes first. *Corroborated the same day, twice, in the same session and both in zsh:* `grep -rn $EX 'Mediator-Arbitrator'` printed an option error and no matches — which reads as clean — because zsh does not word-split unquoted variables; and a digest-comparison loop using `set -- $pair` printed **`DIFFER` on all five rows**, which reads as "the source changed under me", because the loop body received one argument and the comparison never ran. Prefer `git grep`, quote or array-expand anything you pass as flags, and re-check any result whose shape is "uniformly bad". **And re-check "uniformly GOOD" too — that is the dangerous half.** *Added 2026-08-30; sharpened on Pouya's instruction 2026-08-31, as "the sharpest instrument finding yet".* The same `set -- $pair` loop recurred while confirming nine restored files matched a saved copy, and this time it printed **`same` on all nine**: `shasum` was handed both filenames as one argument, errored, and left both variables empty, so `"" = ""` passed. **The distinguishing property, and it is the whole rule: a broken verification that fails loudly is safe; one that passes uniformly is not.** `DIFFER` on every row announces itself — it is alarming, so it starts an investigation, and the investigation finds the broken loop. A uniform pass is **the result you were hoping for, so it ends the check** instead of starting one. The two failures come from the identical bug and only one of them is survivable. So a comparison must **assert that both things it compares exist** before comparing them — that is the assertion the shell loop skipped, and it is what turns this class of bug back into the loud kind. Note the same hole in `git grep`: it silently misses untracked files, so a clean sweep across new work means nothing until the files are staged. **A parent cannot style a child component's root element.** Astro does not pass a parent's scope attribute down, so `