Pouya LajevardiandClaude Opus 5
9f2d2eeb04
Build and deploy / build-and-deploy (push) Failing after 4s
D19 caps the loop at two rounds, and this is what the second round is for. BLOCKING. Round 1 made NO_RETAINER_NOTICE a requireEnv and added it to no document, while the fix's own comment claimed docs/06 named it. The deployment list said five variables for a handler that needs six, so an operator following the cutover checklist would have deployed a function that throws at cold start on every invocation — 5xx from API Gateway, every inquiry lost from the moment /api/* was wired, loud in CloudWatch and silent to Pouya. docs/05 and docs/06 now name all six, and the comment that asserted the documentation existed is corrected rather than deleted. The intake route check added in round 1 could not fail: curl -w already prints 000 on a failed transfer, so `|| echo 000` double-appended and the failure arm was unreachable, and the pass arm accepted anything that was not literally 404 — including the 403 CloudFront returns when the /api/* behaviour is missing, which is the one distinction the check exists to draw. It now sends the correct Origin and asserts a positive: 303 to /contact/could-not-send/, which the handler returns before any DynamoDB write or email. Probed on refused/501/403/303; the old version passed the first three. Fixed in both deploy paths. Removing priceRange left three statements saying it was present or pending, one of them the stated reason /fees/ emits no Offer node. Deleting overtimeStartsAfterSessionHours left AGENTS.md §9 naming it and left Q59 recorded as open. The Google-as-processor fix was applied to the privacy policy's "Where it is stored" and not to "Who can see it", which still read "Nobody else has access". And the variable removal was justified with a path-scoped git grep — which also cannot see untracked files. The unscoped sweep found docs/06's variable table, the OIDC example, and .env.example still carrying them; .env.example also restates the execute-api hostname, falsifying a live claim in intake.ts that has been corrected. That file is not edited here: this environment denies read access to it, and nothing may edit a file it cannot read. It is in the batched list. Also: og:image:alt was the page title rather than the card's headline on 20 pages; og-card.ts documented the wrong path and invocation for the contact sheet; deploy-local.sh still said Q22's deploy credential "does NOT yet exist"; and the round-1 fix comments were trimmed per D19, though the ratio held at 0.44. Round 2 also confirmed the round-1 fixes by measurement: all 56 .btn instances across 22 pages, the consent checkbox's computed accessible name, the radio labels hit-tested at 44px, and og:proof exercised against synthetic article pages in a sandbox. Verified: check/build/check:claims/og:proof/check:intake/lint/bio:pdf all exit 0 on a clean build; 22 pages; Lighthouse 99-100 / 100 / 100 / 100, CLS 0.000. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Md3GndFqWPzK78xAoebsg5
254 lines
18 KiB
Markdown
254 lines
18 KiB
Markdown
# 04 — Discoverability
|
||
|
||
The problem this project exists to fix. `AGENTS.md` §2 has the measurements.
|
||
|
||
> **Those measurements are under review — `AGENTS.md` Q34.** They were taken on
|
||
> 2026-08-25; a re-fetch on 2026-08-26 returned a bundler harness whose real
|
||
> `<head>` sits JSON-escaped inside a `<script>` and whose application lives in
|
||
> nine UUID-named files that were not fetched. Some of §2 reproduced exactly
|
||
> (the 2.2 MB single file, the placeholder `<title>`); some could not be
|
||
> reproduced from the served HTML at all. **Cite §2, and cite Q34 with it. Do
|
||
> not put any of these figures in public copy until Q34 closes.**
|
||
|
||
---
|
||
|
||
## The baseline being replaced
|
||
|
||
| | Now `[verified 2026-08-25]` | Target |
|
||
|---|---|---|
|
||
| Content in server HTML | `SML Company · DISPUTE RESOLUTION · Unpacking...` | Every word |
|
||
| Indexable pages | 1 | 17 + articles (19 fixed URLs, less the two `/legal/*` pages, which are `noindex` and excluded from the sitemap) |
|
||
| `<title>` | `SML Company · Dispute Resolution` — pre-rebrand placeholder | Unique per page |
|
||
| Meta description | none | Unique per page |
|
||
| `<meta viewport>` | **absent** | Present |
|
||
| Canonical URL | none | Every page |
|
||
| OG / Twitter tags | none | Every page |
|
||
| Structured data | none | Person, ProfessionalService, Article, FAQ, Breadcrumb |
|
||
| `robots.txt` | 403 | Served |
|
||
| Sitemap | none | Generated at build |
|
||
| Favicon | none | Full set |
|
||
|
||
Astro's static output solves most of this by existing. The rest is the spec below.
|
||
|
||
## Why static output matters more than usual here
|
||
|
||
Google can sometimes render client-side JavaScript. Bing largely does not.
|
||
LinkedIn's preview crawler does not. Slack's unfurler does not. **And the
|
||
crawlers behind AI assistants — increasingly how counsel and in-house teams
|
||
find a neutral — generally do not.**
|
||
|
||
A site that requires three CDN round trips and an in-browser Babel compile before
|
||
producing a sentence is invisible to all of them. That is the whole argument for
|
||
D1.
|
||
|
||
---
|
||
|
||
## Metadata
|
||
|
||
Every page passes through one `SEO` component. A page without it is not finished.
|
||
|
||
```
|
||
title 50–60 chars, unique. Pattern: "<Page> · Pouya Lajevardi".
|
||
`/` composes its own from the constants — `SITE.name` +
|
||
`SITE.tagline` — rather than a literal, so the masthead and
|
||
the title cannot drift. This spec carried the literal with an
|
||
ampersand after the composition shipped with interpuncts;
|
||
cite the constants, do not restate them (AGENTS.md §7 rule).
|
||
ARTICLES ARE THE EXCEPTION: no " · Pouya Lajevardi" suffix.
|
||
The suffix is 18 chars, so a headline that already reads
|
||
50–60 renders at 68–78 — over this ceiling. Measured against
|
||
the five launch headlines in 03-content-spec.md, the suffix
|
||
rule fails 5 of 5; without it, 4 of 5 pass. An article's
|
||
headline IS its <title>; `seoTitle` in the frontmatter
|
||
overrides it when a headline that reads well is out of range.
|
||
src/content.config.ts enforces this and names the offending
|
||
string and its length in the build error.
|
||
description 140–160 chars, unique, written for a human, not stuffed
|
||
canonical absolute, https, trailing slash
|
||
og:title/description/image/url/type/site_name/locale (en_CA)
|
||
twitter:card summary_large_image
|
||
robots index,follow — except /legal/* which is noindex,follow
|
||
```
|
||
|
||
**OG images:** 1200 × 630. Never a screenshot.
|
||
|
||
**RULED 2026-08-27 (`AGENTS.md` Q40, R15) — TWO kinds of card, not one, and the
|
||
generator is deferred to build step 7.** This spec said "one template" for all
|
||
nineteen pages. Pouya split it:
|
||
|
||
> "A portrait is the **right** OG image for `/` and `/about/` — a face is the
|
||
> strongest social preview for a personal brand. It is the **wrong** one for
|
||
> nineteen pages, where a typed card carrying the page title would do the work.
|
||
>
|
||
> But do not build the generator now and do not leave 'portrait everywhere' as
|
||
> an untracked interim. **Ship it at step 7 alongside Insights, which needs
|
||
> per-article cards anyway — one build, one dependency, one review.**"
|
||
|
||
So:
|
||
|
||
| Pages | Card |
|
||
|---|---|
|
||
| `/` and `/about/` | The **portrait** crop, `src/assets/og-portrait.jpg`. Not an interim — the decided answer. Resolved from `PORTRAIT_PAGES` in `src/data/og-cards.ts`, not from a per-page prop |
|
||
| Every other page | **Generated at build by `src/pages/og/[...slug].jpg.ts`** from `satori` + `sharp`, in the site's own type and palette: display headline on cream, infinity mark, designation line |
|
||
| Each article | Per-article card from the same endpoint — the reason the two jobs were one build |
|
||
|
||
✅ **BUILT — step 7b, 2026-08-31. R15 IS DISCHARGED.** `satori@0.33.4` was chosen
|
||
over `astro-og-canvas@0.13.0` (both 0 vulnerabilities, verified that day): `sharp`
|
||
is already a dependency to rasterise satori's SVG, so it adds one library rather
|
||
than a CanvasKit wasm blob, and it renders with this site's own fonts and tokens
|
||
rather than approximating them.
|
||
|
||
**Four things about the implementation are load-bearing and are not style
|
||
choices.** Each is recorded because a later reader would otherwise "tidy" it:
|
||
|
||
1. **Colours are parsed out of `src/styles/tokens.css` at build time**, not
|
||
copied into the generator. `CLAUDE.md` requires every colour to come from a
|
||
token; the alternative was a duplicated hex table, which is the SES-DKIM shape.
|
||
A missing token throws rather than falling back.
|
||
2. **The fonts are `@fontsource`'s static `.woff` cuts, not `public/fonts/`.**
|
||
satori parses TTF/OTF/WOFF and not WOFF2, and decompressing the site's own
|
||
subset **variable** Geist to TTF *throws* inside satori's `opentype.js` fork —
|
||
Fontsource's subsetting drops the `name` records the `fvar` table points at.
|
||
Same typeface, same upstream version, same weight; build-time only.
|
||
3. **Every card's headline is its page's own `<h1>`, character for character, and
|
||
`npm run og:proof` enforces it** against the built HTML. This is a compliance
|
||
mechanism, not a convenience: **text baked into a JPEG cannot be grepped by
|
||
`npm run check:claims`**, which under D20 is the only per-step claims control
|
||
there is. A card must not carry a claim its page does not already make in
|
||
auditable HTML. The same check confirms every page's `og:image` resolves to a
|
||
file that exists — a 404 preview is invisible from inside the repo.
|
||
4. **A page with no card entry is a BUILD ERROR, not a fallback to the portrait.**
|
||
R15's failure mode was never the wrong image; it was the wrong image shipping
|
||
*invisibly* and reading as intentional. A silent fallback recreates it exactly.
|
||
|
||
## Structured data
|
||
|
||
JSON-LD only. Validate against Google's Rich Results Test before cutover.
|
||
|
||
| Type | Where | Notes |
|
||
|---|---|---|
|
||
| `Person` | `/about/`, referenced site-wide | **Emitted:** `name`, `url`, `jobTitle`, `description`, `alumniOf` (Bond University), `knowsLanguage` (en, fa), `hasCredential` (**Q.Med, Q.Arb** — both, since 2026-08-29), `sameAs` (LinkedIn), `email`, `image`. **Emitted on `/about/` only:** `memberOf` — the four §4 memberships as `Organization` nodes (Q53, ruled 2026-08-28). `/` shows no memberships, so its Person node omits it: structured data represents the page it sits on. **Withheld:** `worksFor` — Q49(b) declined the row 2026-08-28 and Pouya confirmed the reading 2026-08-29, so it is settled rather than pending; `provider → Person → worksFor` would assert a same-entity claim §4 does not row. *(This enumeration listed `worksFor` as emitted while the same cell said it was withheld, and omitted `url` and `email`, which are — wrong in both directions. The enumeration is the part an implementer copies. Found by `adversarial-reviewer`.)* **CHANGED 2026-08-28 — Q47.** This row read *"`jobTitle` = 'Director of Firm Operations'; omit `worksFor`"*, which put the boutique title on a node whose `url` is this ADR practice's `/about/` — so a consumer could attach it to this entity. Pouya's ruling reframes the field: `jobTitle` describes **this practice**, not the boutique role, which D16 keeps unnamed. The visible role line is unchanged and still reads "Director of Firm Operations at a Toronto litigation and ADR boutique". **THE VALUE IS `PRACTICE_JOB_TITLE` IN `src/data/site.ts` AND THIS ROW DOES NOT RESTATE IT** — §7's rule, applied to a string with a live revert trigger on it: this row carried the literal text for one pass, and `adversarial-reviewer` noted it would go stale the moment the constant moved. Cite, do not copy. **`worksFor` IS WITHHELD** — set for one pass under Q47, then reverted: `ProfessionalService.provider` is this Person, so `provider → Person → worksFor` asserts the same-entity claim `schema.ts` explicitly declines, and §4 says "alongside the practice" where the ruling says "operates through". **`memberOf` is emitted** — see the sentence above; Q53 closed 2026-08-28. *(This cell asserted `memberOf` was both emitted and withheld for one pass, which is the defect it already records itself being caught for on `worksFor`, in the opposite direction. The enumeration is the part an implementer copies.)* See `src/data/schema.ts` |
|
||
| `ProfessionalService` | Home | `areaServed` Toronto/Ontario, `serviceType` **Mediation / Commercial arbitration / Mediation-arbitration (med-arb)** — *scoped 2026-08-28 on `claims-auditor`'s finding; this row instructed the unscoped class form "Mediation/Arbitration" that Q39 struck and that `schema.ts` deliberately does not follow. Family arbitration carries prescribed training and has its own NOT OFFERED row, so unscoped "Arbitration" is the struck universal in a field nobody reads. Do not widen these strings without a §4 row to widen them from* — `provider` → Person, ⚠️ **`priceRange` DECLINED 2026-08-31 — this row said *"once `/fees/` is real"*, the page became real at step 9, the field went in, and it came out the same day.** Its own defence rejected a `min`/`max` over `FEES` because *"a range whose ends mean different units is a range that misinforms"* — and the ends it chose had different units too: the floor was the hourly rate, the ceiling a flat documents-only fee. The floor misinformed in the direction that matters, because the least anyone pays for the headline service is **$2,000**. **Nothing on the site states a price in machine-readable form**, and no `Offer` node either: every figure on `/fees/` is conditional on session length, party count or format, and schema.org's `Offer` models one price for one item. This row gates the field; it does not require it. **Never `LegalService`** — schema.org defines it as a business providing legal advice and *representation*, which asserts in machine-readable form exactly what D13 bars and §4 Forbidden calls out |
|
||
| `Service` | **`/mediation/`, `/arbitration/`, `/med-arb/`** and each practice page | `serviceType`, `provider` → Person, `areaServed`. **The Person node travels in the same `@graph`** so `provider: {'@id'}` resolves in one document rather than relying on a crawler joining two — `homeGraph`'s reasoning, applied. `serviceType` is scoped where §4 scopes it: *Commercial arbitration*, never a bare "Arbitration". No `BreadcrumbList` on the three — one hop from the root, no visible breadcrumb, and this spec requires the markup to match the visible one |
|
||
| `Article` | Each article | `headline`, `description`, `datePublished`, `dateModified`, `author` → Person, `image` |
|
||
| `BreadcrumbList` | All nested pages | Matches visible breadcrumbs |
|
||
| `FAQPage` | `/for-parties/`, `/med-arb/` | Only where the visible page genuinely is Q&A. Never fabricate questions to farm a rich result |
|
||
|
||
**`hasCredential` must reflect reality.** ⚠️ **Q.Med AND Q.Arb are both held as
|
||
of 2026-08-29** (`AGENTS.md` §4) and the field carries both — it was Q.Med-only
|
||
while Q.Arb was a commenced pathway. The rule is unchanged and cuts both ways:
|
||
marking an unheld credential as held is a misrepresentation that happens to be
|
||
machine-readable, and **omitting a held one understates the record in a field
|
||
whose whole meaning is "holds"**. `personNode` maps `CREDENTIALS.designations`
|
||
rather than indexing it, so a designation added to that constant reaches the
|
||
graph automatically. **That links the CONSTANT to the graph, not §4 to the
|
||
graph** — a designation added to §4 and not to `src/data/site.ts` still drifts
|
||
silently, and no mechanism catches it. `src/data/schema.ts` states the condition
|
||
in full; this sentence overstated it for one pass.
|
||
|
||
## Crawlability
|
||
|
||
**`public/robots.txt` is the artefact — read it, do not read a copy of it
|
||
here.** This spec used to reproduce the file inline and the reproduction had
|
||
already drifted from it by 2026-08-26, which is the failure mode the `AGENTS.md`
|
||
§7 rule exists to stop.
|
||
|
||
**It disallows nothing, and that is deliberate.** This spec previously
|
||
prescribed `Disallow: /legal/` alongside `noindex` on those pages, and the two
|
||
cancel each other: a crawler forbidden to *fetch* a URL never reads the
|
||
`noindex` on it. `/legal/privacy/` and `/legal/terms/` are linked from the
|
||
footer of every page, so they are discovered regardless — and the likely result
|
||
of the pair was Google listing the bare URLs as "no information available", the
|
||
opposite of the intent, with the directive that would have suppressed them
|
||
sitting unread behind the wall. **`noindex` is what de-indexes; `Disallow` is
|
||
what prevents fetching.** Use the one that matches the problem, and never both
|
||
on the same path.
|
||
|
||
Do not block AI crawlers. Being read by an assistant that a general counsel is
|
||
using to shortlist neutrals is the point.
|
||
|
||
**Sitemap:** `@astrojs/sitemap`, excluding `/legal/*` and any `draft: true`
|
||
article. Submit to Google Search Console and Bing Webmaster Tools at cutover.
|
||
|
||
**Internal linking.** Every practice page links to `/mediation/` and
|
||
`/arbitration/`; those link back to the practice areas; every article links to
|
||
at least one practice page. This is what turns Insights into ranking power for
|
||
the pages that convert. Breadcrumbs on every nested page.
|
||
|
||
**404 page.** Real, styled, with search-intent links out. CloudFront must return
|
||
it with a genuine 404 status — not a 200, which the S3 website-endpoint pattern
|
||
gets wrong by default.
|
||
|
||
## Performance
|
||
|
||
Core Web Vitals are a ranking input, and the current build fails all of them.
|
||
|
||
| Metric | Budget |
|
||
|---|---|
|
||
| LCP | < 2.0 s, Slow 4G |
|
||
| CLS | < 0.05 |
|
||
| INP | < 150 ms |
|
||
| JS per route | < 100 KB |
|
||
| Lighthouse (mobile) | ≥ 95 all four categories — **measurable again as of 2026-08-31, see below** |
|
||
|
||
> ✅ **THE INSTRUMENT IS BACK — build step 7a, 2026-08-31. `npm run lighthouse`,
|
||
> and it is `lighthouse` rather than `@lhci/cli`.** R11's re-add trigger said to
|
||
> put `@lhci/cli` back; this is a deliberate deviation from its literal wording
|
||
> and `AGENTS.md` §7 records both the reason and what it costs.
|
||
>
|
||
> **The reason is that §7's advisory attribution was wrong, and it was the
|
||
> attribution that made the tool look unusable.** §7 recorded the ten findings as
|
||
> arriving *"via `lighthouse → puppeteer-core → extract-zip`"*. Measured from two
|
||
> probe lockfiles: `@lhci/cli@0.15.1` carries 10 (7 high) and pins **lighthouse
|
||
> 12.6.1**, and the two high carriers are `tmp@0.1.0` — *its own direct
|
||
> dependency* — and `extract-zip@2.0.1` via `@puppeteer/browsers`.
|
||
> `lighthouse@13.4.1` standalone is 109 packages, and both are **absent**:
|
||
> `npm audit` returns 0. So Lighthouse was never the carrier, and the budget was
|
||
> unmeasurable for five days on a cause nobody re-derived.
|
||
>
|
||
> **What it does not do: run in CI.** Standalone Lighthouse drives an installed
|
||
> browser and the Gitea runner has none (§7, Q23). So it is a local gate plus a
|
||
> blocking item on `docs/06`'s cutover checklist, and it is deliberately not
|
||
> wired into `npm run build` or either deploy path — a check described as running
|
||
> where it cannot is the defect Q22 turned out to be.
|
||
>
|
||
> ⚠️ **THE ACCESSIBILITY CATEGORY IS MEASURED WITH `prefers-reduced-motion`
|
||
> FORCED, and that is a deviation that has to travel with the number.** Measured
|
||
> twice per condition on `/process/`: motion on gives **96** with
|
||
> `color-contrast` failing on **24 nodes**; motion off gives **100** with 0. The
|
||
> 24 were the scroll-driven reveal caught mid-flight — axe reported foregrounds
|
||
> like `#d0cbc4` on `#f8f4ed`, and neither is in this palette; they are the real
|
||
> colours blended toward the background by an in-progress `opacity` keyframe. A
|
||
> category reporting 24 known-false nodes on ten of fourteen pages cannot surface
|
||
> the twenty-fifth real one. The reduced-motion rendering is the branch
|
||
> `global.css` ships for a real user setting, and it is the one where every
|
||
> element sits at its final colour. Palette ratios are computed in
|
||
> `docs/02-design-system.md`; `scripts/lighthouse.mjs` carries the measurement.
|
||
|
||
How: static HTML, self-hosted preloaded subset fonts, AVIF/WebP with explicit
|
||
dimensions, critical CSS inlined, no third-party scripts on any page except the
|
||
booking embed on `/contact/` — and that one is lazy-loaded behind a click.
|
||
|
||
## Local and professional presence
|
||
|
||
Not code, but it belongs in the launch checklist: Google Business Profile for the
|
||
practice; ADRIC and ADRIO directory listings pointing at the site; a LinkedIn
|
||
profile whose headline and Featured section match the brand (brief §VIII);
|
||
consistent naming across all of them. **Not "name, address and phone"** — §4
|
||
publishes no phone number and no street address, only "Toronto, Ontario; by
|
||
appointment". Directory forms that demand a full NAP get what §4 verifies and
|
||
nothing more.
|
||
|
||
## Post-launch verification
|
||
|
||
- [ ] `curl -s https://adr.smlcompany.ca/ | grep -c "<h1"` returns ≥ 1
|
||
- [ ] Every page renders its full text with JavaScript disabled
|
||
- [ ] Rich Results Test passes on Person, ProfessionalService, Article
|
||
- [ ] OG preview renders correctly in LinkedIn Post Inspector and Slack
|
||
- [ ] Sitemap submitted to Google Search Console and Bing
|
||
- [ ] No page returns 200 for a URL that should 404
|
||
- [ ] Lighthouse ≥ 95 mobile on **every built page** — `npm run lighthouse`,
|
||
which enumerates `dist/` rather than taking a list, so the set cannot go
|
||
stale as pages are added. Do not tick this box from a manual Chrome
|
||
DevTools run and call it the same check
|