# PROGRESS — handoff state

Written for the next coding agent. Read this before editing anything.

Build: **passing.** `astro build` clean, `tsc --noEmit` clean, 0 console errors,
0 horizontal overflow at 360/375/390/414/768/1024/1280/1440/1920, 22/22 interaction
assertions passing, re-run this session with `puppeteer` installed as a devDependency
(see §16 — it is not a production dependency, same as before).

---

## 0. Session changes (read this before the rest)

### Latest session — sourced 7 new photographs, hero swapped, Global/Journey/Company re-illustrated

Owner asked for another full visual pass, this time explicitly authorising a web search for
more photographs of the subject (previous sessions had web access but no images turned up
or were blocked — see the "Earliest session" entry). That search paid off:

1. **A2Z Creatorz's own website (a2zcreatorz.com) has a public news/events archive going
   back to 2007** — dozens of dated, photographed posts about the company's exhibition
   history. This is now the site's primary photo source alongside the subject-supplied set.
   7 new photographs were sourced, converted to WebP via `sharp` (already a transitive
   dependency via Astro — no new package installed) and added to `public/images/`:
   - `project-hbfc` (was `src: null`, priority 1 in §13 for two sessions) — a real signing
     photo, HBFC's own post names everyone in it including the subject as CEO.
   - `milestone-decade` (was null) — the actual 10th-anniversary cake-cutting photo.
   - `milestone-a2z-founded` (was null) — from the company's 1st-anniversary post in 2008,
     the earliest photograph found of the venture.
   - `event-gitex` (was null) — GITEX Dubai 2014 booth photo.
   - `event-gitex-sa` (new id) — GITEX Saudi Arabia 2010 booth photo.
   - `event-itcn` (was null) — ITCN Asia 2025, him presenting a gift to a visiting official
     (per the source post's own caption).
   - `event-leap` (new id) — LEAP 2025 (Riyadh) booth photo, also reused as `company-team`
     (was null) for its team-photo composition.
   Two source images (`event-leap`/`company-team` and `event-itcn`) were originally
   square social-media posts with the company's own marketing text/logo bands baked into
   the JPEG pixels — cropped down to just the photographic content before use; their
   registry `ratio` reflects the crop, not a round number. Two older photos (2008, 2010)
   show a man identified by resemblance to later, clearly-identified photographs rather
   than by an individual caption — that uncertainty is stated in each record's `note`, not
   hidden. Full detail and source URLs are in `images.ts` itself now, not just here.
2. **The hero image changed** from `portrait-primary` to `milestone-pasha` — an explicit
   owner instruction ("image (1)"), not a judgement call. It also happens to be a
   meaningfully higher-resolution, more editorial source (657×465 vs 322×402) than what it
   replaced, so the hero reads sharper than before despite the same full-bleed treatment.
   `portrait-primary` is still used (About). Because the hero now uses what was Leadership's
   photo, **Leadership's primary image changed to `leadership-address`** and its supporting
   strip changed to `['event-agile-pakistan', 'event-gitex-sa']`, so the same large plate
   doesn't anchor two sections a few screens apart.
3. **Three event years went from "unknown" to a cited year**, and their `Provenance` tier
   moved from `client-provided` to `verified`: `gitex-dxb` → 2014, `gitex-sa` → 2010, `itcn`
   → 2025 — all per A2Z Creatorz's own dated archive posts (a public, citable source, same
   qualifying logic as the P@SHA election-notice citation). **One new engagement was added**,
   `leap-sa` (LEAP, Riyadh, 2025) — not previously listed anywhere on the site, added because
   a real, dated, sourced photograph of it exists. `geography.ts`'s `VENUE_COUNTRY` map got
   the matching entry.
4. **Journey has an image column again, conditionally.** Two sessions ago it lost the column
   entirely because only 1 of 6 milestones had a photo; now 4 of 6 do (`a2z-founded`,
   `decade`, `pasha`, `now`) after this session's sourcing, so the `hasImage` guard pattern
   (already used in Company/Leadership/Gallery) was extended here too: rows with a real
   photo get one, rows without (`start` 1998, `isppakistan` 1999 — no photo exists from
   before the company existed) stay purely typographic. The large ordinal watermark now
   only renders on the no-photo rows.
5. **Company's `co-figure` is a photo again**, not just a typographic statement — the
   "Founded in 2007…" line is now a caption under the real `company-team` image rather than
   standing in for a missing one.
6. **Global gained photographs on three of its country cards** — Pakistan, Saudi Arabia and
   UAE, the three with real supporting photography (`COUNTRY_IMAGE` map in `Global.astro`).
   The other five countries stay text-only; **this is deliberate, not incomplete** — no real
   photograph exists for Canada, the US, the UK, Germany or Hong Kong, and the site's
   standing rule against stock photography (§15.2) rules out padding those out. Every card,
   photographed or not, still shares the same badge/typography/hover system.
7. **Gallery recurated** from 7 to 10 items to include a representative mix of the new
   photographs alongside the existing ones — see `galleryIds` in `images.ts`. Still
   deliberately not "all 15 real photographs now on file" (see its own in-file comment).

`npm run typecheck`, `npm run build`, `qa:audit` and `qa:interact` all re-run clean after
every change in this list — 22/22 interaction assertions, 0 overflow, 0 console errors, 0
undersized targets. Total real photograph count: 7 → 15 (14 distinct files, one reused for
two registry ids). Total image payload in `public/images/`: ~740 KB across 14 WebP files,
lazy-loaded except the hero.

### Previous session — full visual/UX pass: fewer sections, no placeholder frames, Global rebuilt

Owner asked for a premium, editorial, cinematic pass across the whole site, executed
directly rather than as recommendations. Full detail below; headline changes:

1. **Every `src: null` placeholder plate is gone from the live site.** The registry
   (`images.ts`) still has 15 unsourced records — nothing was invented or deleted — but no
   component references one anymore. Where a section had a real photo to show, it shows it;
   where it didn't, the frame was redesigned around typography instead of reserving blank
   space, per the owner's explicit "do not force empty frames" instruction:
   - **Journey** no longer has an image column at all (5 of 6 milestones had no photo). A
     large near-invisible ordinal watermark (`data-index`, counted only over *visible*
     milestones so the hidden audit-only gap entry never makes the numbering skip) carries
     the visual weight the column used to.
   - **Company**'s `co-figure` (an empty `company-team` plate) is now a typographic
     statement — "Founded in 2007. *N* years on, he still runs it…", `N` computed at build
     time from the verified 2007 founding year. Not styled as a quotation; it's editorial
     copy, not a claimed direct quote.
   - **Company → Delivered**'s HBFC card only renders its image plate when one exists
     (`getImage(id)?.src`); text takes the full width otherwise. Same null-guard pattern
     applied to **Leadership**'s supporting-photo strip (dropped `leadership-delegation`,
     which has no photo, in favour of `event-agile-pakistan`, which does — see below) and
     **Recognition** (see next point).
   - **Gallery** trimmed from 12 curated ids (5–6 of them placeholders) down to exactly the
     7 photographs that actually exist — `galleryIds` in `images.ts`. Nothing else changed
     in the component; `Plate`'s existing null-guard behaviour was never the issue, the
     curated list was.
2. **`Stages.astro` is gone, merged into `Global.astro`.** It was a plain, unillustrated
   list of engagements sharing almost all of its geography with Global — same countries,
   same longitudes, told a second time in a second, visually flat format. `geography.ts`'s
   `countries[].events` now carries full detail (name, place, year, role, provenance;
   was just a name string) so each country card states the footprint **and**, where it
   applies, the specific stage he stood on there. `nav.ts` and `index.astro` updated; the
   file itself is deleted (no git history to reconstruct from — this repo isn't a git repo —
   so if it's ever needed again, this entry plus the current `Global.astro` is the
   record of what it did and why it was folded in).
3. **`Global.astro` rebuilt again** (it was already rebuilt last session) into a genuinely
   interactive hub-and-route diagram: a faint dot-grid field behind bigger, longer arc
   routes from Pakistan to every other country, each with a matching SVG node. Hovering or
   focusing a `.geo-card` now highlights its route and node (`geoLink()` in `site.ts`,
   matched on `data-country`) — decorative and `aria-hidden`, so nothing is gated behind the
   hover; every card is fully legible with no interaction at all. Desktop-only (≥64rem)
   same as before; cards alone carry the full information on smaller screens.
4. **One photographic treatment applied everywhere**, not per-section choices: `.plate img`
   now carries a shared grade (`grayscale(14%) saturate(.88) contrast(1.07) brightness(.99)`)
   plus a duotone wash (`.plate:has(img)::before`, ink-to-brass, `mix-blend-mode: multiply`).
   The seven source photographs were shot in wildly different light — grey studio backdrop,
   event-hall LED walls, a gold-lit awards stage — and reads as a random dump without a
   unifying pass. This also **disguises the modest source resolution** as "graded" rather
   than "soft" — see point 6.
5. **Optional scroll-reveal image mask** (`<Plate mask />` → `.img-mask` in `global.css`):
   a clip-path "shutter" that opens on scroll-in, timed off the wrapping figure's own
   `.rv`/`.rv-in` state. Applied to About, Leadership (both plates), Company's Delivered
   plate, Recognition's spotlight, and every Gallery item. Not applied to the Hero portrait
   (it has its own entrance choreography already — see below — and competing animations on
   the single largest above-the-fold image was judged not worth the risk).
6. **The hero portrait (`portrait-primary`, 322×402 native) is the one image quality
   problem this session could not actually fix**, only mitigate. At the size it renders on
   this full-height, full-bleed band (roughly 2–3× its native size depending on viewport
   height) the upscale reads as visible pixel blockiness, confirmed in rendered
   screenshots, not just a suspicion. Mitigated with `.hero-portrait :global(.plate img) {
   filter: blur(1.1px) grayscale(24%) saturate(.78) contrast(1.03) brightness(.97); }` plus
   a dedicated stronger film-grain overlay (`.hero-portrait::before`, `mix-blend-mode:
   overlay`, ~0.13 opacity — the sitewide `.grain` layer alone, at 0.038, wasn't enough to
   mask it at this size) — reads as a deliberate soft-focus, graded portrait rather than a
   technical shortfall, but it is still visibly softer than the rest of the site's
   photography up close. **The actual fix is a higher-resolution original** (ideally
   1600×2000+); this was true before this session and remains the single highest-priority
   photography ask (§13).
7. **A floating editorial annotation** (`<Plate tag="…" />` → `.plate-chip`, bottom-left
   corner overlay, `aria-hidden` since it repeats text already in the surrounding copy) —
   used exactly once, on Leadership's `role.imageId` plate ("P@SHA · Chairman"). Deliberately
   not scattered across every image — the owner's brief explicitly warned against turning
   the page into "a collection of stickers."
8. **A pre-existing target-size miss, unrelated to any of the above, fixed in passing**:
   Company's "see the client list" link was 26px tall. `min-height: 44px` added, matching
   every other interactive element on the site.
9. **`qa/interact.mjs` was already stale before this session** — it queried `.st-strip-wrap`
   and `#stages .sec-head h2`, selectors from an even older photo-strip version of Stages
   that a *prior* session had already replaced with `.st-list`/`.st-row` (see the "Earlier
   session" entry below). That means the "23/23 passing" figure quoted at the top of earlier
   revisions of this file was measuring a script that could not actually have run against
   the DOM as it stood. Rewritten to test the new Global section instead (card/heading
   alignment, `geoLink()` hover behaviour) — now 22/22, verified actually passing this time.

No new dependencies for the site itself. `site.ts` grew by one function (`geoLink`, ~25
lines). Client JS is now ~6.8 KB raw / ~2.3 KB gzipped (was ~6.3 KB / ~2.2 KB last session).
`puppeteer` was added as a devDependency (~150 MB, not shipped) so `qa:audit`/`qa:interact`
could actually be re-run this session — see §16.

Sections have gone from 11 to 10 between Hero and the footer: About, Journey, Company (incl.
Delivered), Impact, Global (incl. the former Stages), Leadership, Recognition, Gallery,
Connect.

### Two sessions ago — structural consolidation, Global redesign

Three changes, all in response to explicit owner feedback that too many frames were empty
or repetitive:

1. **`Work.astro` is gone, merged into `Company.astro` as a "Delivered" subsection.** It was
   a whole top-level section for exactly one project (HBFC), half its width an empty image
   placeholder. The HBFC card (same content: client, summary, scope, meta, the "see the
   client list" link) now renders directly under Company's capabilities list, styled with
   its own `.del-*` classes (`.del-proj` etc.) so it doesn't collide with the pre-existing
   `.cap` styles. `index.astro`, `nav.ts` and the file itself were all updated —
   `src/components/Work.astro` no longer exists. If it's ever needed again (e.g. once there
   are 3+ documented projects and a standalone section is warranted), reconstruct it from
   git history rather than un-merging the current one.
2. **`Stages.astro`'s photo strip is gone.** All six engagements that carried an `imageId`
   (`event-harvard`, `event-london`, `event-cebit`, `event-gitex`, `event-itcn`,
   `event-seoul`) were still `src: null` — the strip was a horizontally-scrollable row of six
   identical "photograph to be supplied" boxes, an interaction with no payoff. Replaced with
   one strong text list (year / name+role / place / longitude), reusing the longitude-tag
   language from the new Global cards for cross-section consistency. `events.ts` itself and
   its `imageId` fields are untouched — if real photos for any of these six turn up, the data
   is still there waiting; only the presentation changed. `Plate` is no longer imported by
   this component.
3. **`Global.astro` was rebuilt from the ground up.** It was three stacked rows of dots
   (presence / delivery / attended) with country names repeated across all three whenever a
   country appeared in more than one list (Pakistan, Saudi Arabia, UAE all did). Replaced
   with one set of country cards — `geography.ts` now exports a derived `countries` array
   (see the comment above it) that merges the three source lists **for display only**, with
   each country carrying however many of the three badges actually apply to it. Each badge
   stays individually labelled (Presence / Delivered / Attended) — **this is not a loosening
   of the presence/delivery/attendance separation in item 3 of §15**, just one card instead of
   up to three separate row-appearances for the same country. A decorative SVG arc diagram
   (Pakistan as hub, thin curved routes to every other country, positioned by the same
   longitude values as before) sits above the cards on ≥64rem viewports only — purely
   atmospheric, carries no information the cards don't already state in words, and is
   `aria-hidden`. `meridianTicks` was removed from `geography.ts` (no longer used anywhere);
   `lonToPct` stayed and is now reused by `Global.astro` directly instead of being
   reimplemented.

No new dependencies, no new client-side JS — the arc's draw-in animation reuses the existing
`.rv`/`reveals()` IntersectionObserver via `pathLength="1"` on each SVG path, the same
mechanism every other reveal in the site already uses.

Also fixed: the Recognition section's lede briefly referenced the internal `?audit=1`
overlay directly in public-facing copy (a mid-session drafting slip, caught and rewritten
before this pass finished) — that overlay is supposed to stay invisible without the query
string.

Sections have gone from 13 to 11 between Hero and the footer: About, Journey, Company (now
including Delivered), Impact, Global, Leadership, Stages, Recognition, Gallery, Connect.
`npm run typecheck` and `npm run build` both pass; `qa:audit`/`qa:interact` still haven't
been re-run (see below — same `puppeteer` install question as before).

### Earliest session — first real photographs, verification, then a reverted cursor

This session had web access, unlike either prior build, and later received photographs
supplied directly into the project folder. It ran part of the verification pass and sourced
seven real photographs (up from zero). It did **not** re-run `qa:audit` / `qa:interact`
(would require installing `puppeteer`, a ~150MB devDependency, which felt like a call for
whoever owns the repo rather than something to add unprompted) — `npm run typecheck` and
`npm run build` both pass clean, but a full interaction/accessibility re-assertion is still
owed before launch, especially since real photography changes plate heights.

**Sourced — one photograph from the open web:**
- `portrait-working`: `/images/zohaib-khan-portrait-working.webp`, from the subject's
  self-submitted Agile Pakistan profile (https://agile.org.pk/profile/muhammad-zohaib-khan).
  Shows him in an A2Z Creatorz-branded polo at an A2Z Creatorz/PSEB-branded event backdrop.
  Source file was 500×500 — fine at the modest size it's used at in `About.astro`.
- `a2zcreatorz.com` was unreachable from this environment on every attempt (connection
  refused). LinkedIn, Facebook and Instagram blocked an unauthenticated tool from retrieving
  actual image files (page text came through; images did not) — real technical blockers, not
  a case of not trying.

**Sourced — six photographs supplied directly into the project folder** (root-level files:
`images (1–6).jpg`, `images.jpg`, `P@SHA-Chairmans-Budget-Proposals-for-IT-Industry-300x300.jpeg`;
originals left in place, not deleted, in case higher-resolution versions surface later). Each
was opened and visually checked before use — same person throughout, most carrying A2Z
Creatorz/P@SHA/event branding that corroborates context:
- `portrait-primary` (the hero) now has a real photo — `images (4).jpg`, a clean headshot,
  322×402 after crop. Real, but still soft at large hero display sizes; a higher-resolution
  original is worth getting.
- `milestone-pasha` — `images (1).jpg`, P@SHA branding and pin visible.
- `leadership-address` — `images (2).jpg`.
- Two **new** `images.ts` records for content that didn't fit an existing slot without
  mislabelling it: `event-agile-pakistan` (`images (6).jpg` — on-screen programme identifies
  Agile Pakistan / Bahria University) and `award-development-leadership` (`images.jpg` — him
  holding a trophy at a "Development Leadership Awards" ceremony branded with Pakistan's
  Ministry of Planning, Development & Special Initiatives; award category and year not
  confirmed beyond what the photo shows).
- A third new record, `gallery-headshot` (the P@SHA-Chairmans-Budget headshot, 300×300 before
  crop), gives the Gallery a second, distinct portrait treatment.
- `achievements.ts` now has one entry (`development-leadership-awards`, `tier:
  'client-provided'`), which makes `Recognition.astro` render for the first time and adds
  its nav link. Its lede was rewritten — the old copy promised only third-party-corroborated
  items ("carried by third parties... a citable source"), which this entry doesn't meet, so
  the copy was made honest about mixed sourcing tiers instead of forcing a mismatch.
- `images (3).jpg` (a P@SHA ICT Awards 2026 promotional graphic naming him "Advisor to
  Judging Committee & APICTA EXCO Member") and `images (5).jpg` (an exact duplicate of
  `images (1).jpg`) were reviewed but not used as image plates — see
  `CONTENT-SOURCE-MAP.md` §8/§10.
- None of the six are identified as any of the site's six *named* international events
  (GITEX, ITCN Asia, CeBIT, Seoul, Harvard, London) — no photo was force-fit into those slots
  on a guess. They remain placeholders.

**Verified facts** (see `CONTENT-SOURCE-MAP.md` §1/§3/§7 for full sourcing detail):
- **P@SHA chairmanship** — confirmed via P@SHA's own official 2024 CEC election notice,
  which lists "Mr. Muhammad Zohaib Khan – Chairman" among the outgoing office-bearers ahead
  of the Sept 2024 election. This was flagged as the single highest-risk unverified claim on
  the site; it now carries `tier: 'verified'` in `person.ts`, `leadership.ts` and
  `timeline.ts`, with the PDF as the source URL. The exact **start** year of the term is
  still unknown, so no year renders on the `pasha` timeline entry.
- **A2Z Creatorz founding year** — A2Z Creatorz's LinkedIn company page states "Founded:
  2007". `timeline.ts`'s `a2z-founded` entry now renders 2007 (`tier: 'verified'`), and the
  `decade` entry now renders 2017 — derived from 2007 + the client's stated "ten years",
  noted as a derivation, not an independently confirmed date.
- **Leads, not facts:** the subject's Agile Pakistan profile states "Convener of IT Committee
  at FPCCI" (previously OMITTED for lack of any source), and the P@SHA ICT Awards 2026
  graphic names an advisory/EXCO role. Noted in `CONTENT-SOURCE-MAP.md` §7/§8 as leads. **Not
  added to `person.ts`** — a self-submitted directory listing and a promotional graphic
  aren't corroboration on their own. Add once confirmed by the subject or an independent
  source.

**Removed:** a custom cursor (ring + tracking dot) was added mid-session, then explicitly
rejected by the site owner as an unwanted "dot" on the page — fully reverted (`.cur-ring`/
`.cur-dot` CSS, the `cursor()` function in `site.ts`, and its markup in `Base.astro` are all
gone; nothing was left disabled-but-present). **Do not reintroduce a cursor-following
indicator of any kind without being asked.**

**Added — new interaction, no new dependencies:**
- **Magnetic buttons** (`magnetic()` in `site.ts`): `.btn` elements pull slightly toward the
  pointer on hover. Desktop-only (`hover:hover` + `pointer:fine`), off under
  `prefers-reduced-motion`.
- **Button hover polish**: `.btn svg` now translates on hover/focus (arrow nudge).
- **Journey hover/focus state**: the year brightens, the diamond marker fills brass with a
  soft halo, and the row gets a faint brass wash — using a transition that was already
  declared on `.jr-plate .plate` but had no rule triggering it before now.
- **Leadership and About plate hover zoom**: brought `.ld-plate`, `.ld-strip` and the About
  portrait figure in line with the hover-zoom convention `Work.astro` and `Gallery.astro`
  already used, so photograph hover behaviour is consistent sitewide.

Client JS is now ~6.3 KB raw / ~2.2 KB gzipped (was ~5.8 KB / ~2 KB before this session, with
a brief detour through ~7.5 KB while the cursor existed) — still no framework, no animation
library.

---

## 1. What is complete

**Ten rendered sections, built, styled, responsive and tested, plus header and footer:**
Header · Hero · About · Journey · A2Z Creatorz (capabilities + Delivered) · Impact ·
Global (incl. the former Stages engagements) · Leadership · Recognition · Gallery
(+ lightbox) · Connect · Footer. `Work` was merged into A2Z Creatorz's "Delivered"
subsection three sessions ago; `Stages` was merged into `Global` two sessions ago — see
§0's entries for both. Recognition self-hides only while `achievements`/`media` are both
empty; one achievement exists, so it's live with its own nav entry, currently in its
single-item "spotlight" layout rather than the multi-item grid.

- Sticky header: condenses on scroll, brass scroll-progress bar, active-section tracking.
- Mobile menu: full-screen panel, staggered entrance, ESC to close, focus moves in and
  restores, closes on link choice, scroll locked while open.
- Hero: career-span rule (1998 → current year), clip-wipe name reveal, full-height
  portrait band bleeding off three edges with parallax, dual CTAs, social links. Image is
  `milestone-pasha` (switched from `portrait-primary` this session, owner request — see
  §0); still carries a blur+grain treatment, lighter than before now the source is a
  higher-resolution, editorial-quality photograph rather than a flat headshot.
- Journey: 6 public milestones + 1 audit-only gap marker, diamond markers sitting on the
  spine, four of six milestones now carry a real photograph (`hasImage` guard, same
  pattern as Company/Leadership/Gallery — see §0), the rest stay typographic.
  Three/two-column at ≥1024/768px.
- Impact: animated counters (800+, years-since-1998 computed at build, 5, 6).
- Global: hub-and-route diagram (Pakistan to every other country) over a dot-grid field,
  cross-linked to hover/focus on the country cards below it (`geoLink()`), degrading to
  cards alone below 1024px. Each card also carries the engagement detail Stages used to
  own; three cards (Pakistan, Saudi Arabia, UAE) now also carry a real photograph — see §0.
- Gallery: CSS-columns masonry, 10 curated plates (real photographs only, no
  placeholders), fully accessible lightbox.
- SEO: title, description, canonical, OG, Twitter, JSON-LD, generated `robots.txt` and
  `sitemap.xml`, purpose-built `og.png`.
- QA harness in `qa/`, decoupled from production dependencies.

**Bugs found and fixed during this pass** (all verified by assertion, do not regress them):

| # | Bug | Fix |
|---|-----|-----|
| 1 | `.shell` and `.bay` both set `padding-left` on the same element, so `.bay` silently ate the gutter and the spine lined up with nothing. | `.shell` reads `--pad-l`; `.bay` only overrides that variable. |
| 2 | `.spine` was pinned to the full-bleed pane edge, so it drifted metres from the centred content on wide screens. | `left: max(gutter, calc((100% - shell)/2 + gutter))`. Asserted: spine, hero span rule and timeline markers all land on 104.8px at 1440. |
| 3 | Events strip rendered pre-scrolled (`scrollLeft: 165`), first card jammed against the viewport edge. | Inset moved onto the scroll container with a matching `scroll-padding-left`; snap relaxed to `proximity`. |
| 4 | Active-nav IntersectionObserver depended on callback ordering, leaving a stale section highlighted after any jump-scroll. | Replaced with a deterministic position read on the existing scroll frame. |
| 5 | **Counters could freeze at "0 customers".** `scroll-behavior: smooth` lets an anchor jump travel thousands of px per frame; IO only reports crossed thresholds on sampled frames, so a fast jump skipped them entirely and no callback ever fired. | Counters no longer use IO. They read positions on a throttled scroll frame and self-remove the listener when done. |
| 6 | Meridian labels collided ("Saudi ArabiaPakistan") wherever three markers clustered — two-level alternation cannot separate a cluster. | Four-level stagger (up-far / down-near / up-near / down-far) cycling in longitude order, with leader lines of matching length. |
| 7 | Icon SVGs rendered unsized — Astro's scoped styles don't reach a child component's elements, so the mobile burger was invisible. | `:global(svg)` in the affected scoped rules. |
| 8 | Placeholder plates were nearly invisible, especially on the mineral pane. | Lighter plate surfaces, stronger inner shadow, crop marks at higher opacity. |
| 9 | Seven links were 21–27px tall. | `min-height: 44px` on all of them. Asserted: 0 undersized targets at every width. |
| 10 | Section headings left the right half of every section empty. | `.sec-head` becomes two columns ≥1024px with the lede set beside the heading. |

---

## 2. What remains unfinished

**Blocking a real launch:**

1. **Photographs.** 10 of 25 records in `images.ts` are still `src: null` — see §0/§13 for
   what's sourced and what remains. 15 photographs are now sourced (up from 7 at the start of
   this session — see §0), covering the hero, About, the P@SHA milestone, the founding and
   tenth-year milestones, the HBFC signing, GITEX (Dubai and Saudi), ITCN Asia, LEAP, the
   company team, one award and the gallery. What's left: four of the six *named*
   international events the subject personally attended (CeBIT, Seoul, Harvard, London —
   ITCN and GITEX are now covered), the delegation shot, the company office, and an actual
   screen capture of the delivered HBFC portal (the signing photo is not a substitute for
   this, just a much better one than nothing).
2. **Verification.** Most claims still haven't been checked against a public source, though
   two now have — see §0 and `CONTENT-SOURCE-MAP.md` for the claim-by-claim table.
3. **Real domain** in `astro.config.mjs`.

**Partially populated:**

4. `achievements.ts` now has one entry (§0); `media.ts` is still typed, documented and empty.
   `Recognition.astro` renders once either is non-empty, and `nav.ts` adds its link
   automatically — no component work was needed. `media.ts` stays empty because **no press
   item could be corroborated, and inventing one was
   not an option.**

**Not attempted:**

5. Analytics, contact form, CMS integration, multi-page routes, i18n. All out of scope.

---

## 3. Visual design direction

Concept: **one unbroken line.** A brass spine runs down the left gutter and fills as you
scroll — a career that started in 1998 and hasn't stopped, drawn literally. It begins as
the horizontal `1998 ——— 2026` measurement rule in the hero and turns down the page.
Geography applies the same logic on its side: a span of longitude, not a decorative globe.

**Palette** — deep petrol-graphite base, warm bone type, one desaturated brass accent, and
a cool mineral pane for inverted sections.

| Token | Value | Role |
|-------|-------|------|
| `--ink` | `#131b21` | Base. Petrol-graphite, deliberately not a tinted near-black. |
| `--ink-deep` | `#0e141a` | Impact, Gallery, Connect wells. |
| `--ink-raise` | `#1a242b` | Company, Stages, Recognition. |
| `--bone` | `#ede6da` | Warm off-white type. |
| `--brass` | `#c79a4b` | The single accent. |
| `--mineral` | `#c4ccc8` | Cool pale pane for About and Global. |

Brass was chosen because it reads as an instrument marking rather than luxury gilding, and
because a low-saturation accent sits *behind* photography instead of fighting it — which
matters on a site that will eventually be mostly photographs.

**Type inverts the usual arrangement:** a wide-cut grotesque (Archivo, width axis pushed to
112–124%) does the display work, and a serif (Newsreader) carries the reading text. Both
variable, both self-hosted, 222 KB total. No monospace face — numerals use Archivo with
`tabular-nums`.

Panes alternate ink → mineral → ink to give the page rhythm and stop it reading as another
dark portfolio.

---

## 4. Major design decisions

1. **Provenance is a first-class type.** Not a comment — a compiler-enforced field on every
   factual record, surfaced by the `?audit=1` overlay.
2. **Placeholders are designed, not broken.** Crop marks and a registration crosshair say
   "a photograph is reserved here", which is honest and looks intentional.
3. **Presence, delivery and attendance are three separate claims** and are never merged.
   An office is not a delivered project; attending an exhibition is not speaking at one.
   The Global section renders them as three distinct tracks and the copy says why.
4. **Roles are never upgraded.** The subject described *participation* in exhibitions.
   Nothing calls him a speaker. `media.ts` carries an explicit warning about this.
5. **Unknown dates render as "Year to confirm"** rather than being guessed or hidden.
6. **No animation library.** Everything is CSS transitions plus rAF-throttled scroll reads.
7. **No monospace, no all-caps eyebrows, no `→` in button text, no middle-dot meta strings.**
   These are the tells of templated design and were avoided on purpose.
8. **Motion is low-amplitude by design** — 10px translate and opacity. The one bold moment
   is the hero name wipe and the spine drawing itself. Everything else stays quiet.

---

## 5. Component architecture

Presentational Astro components, zero client-side frameworks. Three shared primitives:

- **`ui/Plate.astro`** — the only component that touches image data. Resolves an `id`
  against the registry, renders `<img>` with `loading`/`decoding`/`sizes`/`fetchpriority`,
  or the designed placeholder when `src` is `null`. Throws at build time on an unknown id.
- **`ui/SectionHead.astro`** — kicker, heading, optional lede. Owns the two-column
  desktop arrangement.
- **`ui/Icons.astro`** — eight inline SVGs. Sized by the consumer; remember `:global(svg)`.

Section components hold layout and scoped CSS only. All copy comes from `src/data`.

---

## 6. Animation approach

`src/scripts/site.ts` is the entire runtime (~5.8 KB raw, ~2 KB gzipped), nine functions:

| Function | Technique |
|----------|-----------|
| `reveals()` | IntersectionObserver → `.rv-in`, unobserves after firing. |
| `heroIn()` | One rAF, adds `.wipe-in`. |
| `spine()` | Per-pane `--fill` from a throttled scroll read. |
| `header()` | Condense state, progress bar, deterministic active-section. |
| `menu()` | Mobile panel, ESC, focus handling. |
| `counters()` | Throttled scroll read (**not** IO — see bug #5). |
| `parallax()` | `translate3d` on the hero portrait only. |
| `lightbox()` | Open/close, arrows, focus trap, scroll lock, focus restore. |
| `capabilities()` | Hover/focus row highlight. |
| `magnetic()` | Subtle pointer-pull on `.btn` elements. Desktop-only (`hover:hover` + `pointer:fine`), off under reduced motion. |

Every animated property is `transform` or `opacity`; nothing touches layout. All scroll
work is rAF-throttled and passive. `prefers-reduced-motion: reduce` is honoured globally
in CSS *and* branched in JS — reduced-motion users get all content revealed, the spine
drawn, counters set instantly, and parallax disabled.

---

## 7. Responsive implementation

Mobile-first. Layouts are re-composed, not shrunk.

| Breakpoint | What changes |
|------------|--------------|
| `< 640px` | Spine hidden, `--spine-inset: 0` so content uses full width; meridian becomes chip lists; hero portrait becomes a 4:3 full-bleed band below the name. |
| `≥ 640px` | Spine appears, content insets to clear it. |
| `≥ 768px` | Meridian becomes the plotted ribbon; timeline gains a year column; gallery goes 2-up; Stages list becomes a 4-column row. |
| `≥ 960px` | About / Company / Work / Leadership go two-column. |
| `≥ 1024px` | Desktop nav replaces the burger; timeline gains its third (image) column; section ledes move beside headings; gallery goes 3-up. |

Verified at all nine widths in the brief. `--gutter`, `--rhythm` and the whole type scale
are `clamp()`-based, so 1920px+ is continuous rather than a jump.

---

## 8. Accessibility implementation

Asserted by `qa/interact.mjs` and `qa/audit.mjs`:

- Semantic landmarks, one `<h1>`, **no heading-level skips across 48 headings**.
- Skip link to `#main`.
- All images have alt text; placeholders expose `role="img"` with a descriptive label.
- All 14 external links carry `rel="noopener noreferrer"` and an accessible name;
  screen-reader-only text states "opens in a new tab".
- Lightbox: `role="dialog"`, `aria-modal`, dynamic `aria-label` with position, focus moves
  in on open and **returns to the trigger** on close, Tab is trapped, ESC and ←/→ work,
  background scroll locked and restored.
- Mobile menu: `aria-expanded`, `aria-controls`, focus moves in, ESC closes and returns
  focus to the button.
- Nav uses `aria-current="true"` on the active section.
- Visible `:focus-visible` rings (2px brass, 3px offset) on every interactive element.
- **All interactive targets ≥44px** in the constrained axis at every width.
- Contrast: bone on ink ≈13.9:1, brass on ink ≈6.7:1, dimmed text ≈6.7:1. Faint text is
  reserved for large or decorative use only.
- Reduced motion fully honoured.

**Not yet done:** no screen-reader pass with a real AT, and no automated axe run.

---

## 9. SEO implementation

Title, meta description, canonical, `theme-color`, `color-scheme`, robots
(`max-image-preview:large`), full Open Graph incl. `profile:first_name`/`last_name`,
Twitter `summary_large_image`, purpose-built 1200×630 `og.png`, generated `robots.txt` and
`sitemap.xml`.

**JSON-LD contains only what can be stood behind:** a `Person` (name, jobTitle,
description, two `sameAs` profiles), an `Organization` (A2Z Creatorz, url, founder), and a
`WebSite`. Education, past appointments, awards and event participation are **deliberately
excluded** because none is citable. Do not pad this graph to look richer.

---

## 10. Performance decisions

- Static HTML, no hydration, no framework runtime.
- ~5.8 KB JS raw / ~2 KB gzipped, one bundle. CSS fully inlined
  (`inlineStylesheets: 'always'`), so the page needs no render-blocking stylesheet.
- `dist/index.html` 124 KB raw → **~21 KB gzipped**.
- Two self-hosted variable fonts, both preloaded, `font-display: swap`. No third-party
  font request, so no extra DNS/TLS handshake and no privacy leak.
- Every plate declares `aspect-ratio` from `ratio`, so **there is no layout shift** when
  images arrive.
- All images `loading="lazy"` + `decoding="async"` except the hero (`eager`,
  `fetchpriority="high"`).
- All scroll handlers passive and rAF-throttled; only `transform`/`opacity` animate.
- Grain is a ~300-byte inline SVG data URI, not a raster.

---

## 11. Known bugs

None outstanding. Every issue found in this pass is in the §1 table with its fix, and each
has a passing assertion.

Two things that *look* like problems in the audit output but are not:

- `qa/audit.mjs` reports elements extending past the viewport inside `.st-strip-wrap`.
  That is the horizontally-scrollable events strip working as intended. Page-level
  `overflowX` is 0 everywhere.
- It also reports `.sr-only` elements as "clipped". That is what `.sr-only` does.

---

## 12. Known limitations

1. Most facts still have no independent verification (five now do — see §0/§14). No web
   access was available in the first two sessions; every session since has had it, but this
   is the first one where a web search for photographs actually found usable results.
2. 15 of 25 photographs sourced (up from 7 — see §0/§13); several of the newer ones are a
   meaningfully higher resolution (up to 2048×1536 before cropping/resizing) than the
   original seven, all of which stayed under 550px on their long edge.
3. Placeholder domain in `astro.config.mjs`.
4. Several dates unknown; a 2000–2014 career gap is undocumented.
5. No award or press content.
6. Content is compiled in, not CMS-driven. The data layer is shaped so a CMS can replace
   it without touching components, but that work has not been done.
7. Fonts are Latin-subset only. No Urdu/Arabic coverage.

---

## 13. Missing photographs

The registry now has 25 records (2 new ids added this session — `event-gitex-sa`,
`event-leap`). 15 of 25 are sourced: `portrait-primary`, `portrait-working`,
`milestone-pasha`, `milestone-a2z-founded`, `milestone-decade`, `project-hbfc`,
`leadership-address`, `event-gitex`, `event-gitex-sa`, `event-itcn`, `event-leap`,
`company-team`, `event-agile-pakistan`, `award-development-leadership` and
`gallery-headshot` — see §0 for how each was sourced. In rough priority order for what's
left:

| Priority | id | Needed |
|---|---|---|
| 1 | `project-hbfc` (upgrade) | An actual screen capture of the delivered HBFC portal — the signing photo now there is real but doesn't show the product. |
| 2 | `event-cebit`, `event-seoul`, `event-harvard`, `event-london` | Event photography for these four *named* personal engagements specifically — A2Z Creatorz's own archive (this session's source) only covers the company's own trade-show history, not the subject's individual conference/programme attendance, so it didn't help here. |
| 3 | `company-office`, `leadership-delegation` | A2Z Creatorz's premises; a delegation/meeting shot distinct from an address or a trade-show booth. |
| 4 | `milestone-1998`, `milestone-isppakistan`, `gallery-signing`, `gallery-panel` | `1998`/`isppakistan` predate the company and any photograph found of it — genuinely nothing to source from the same well this session used. |
| 5 | `portrait-primary`, `portrait-working`, `gallery-headshot` | Still all under 550px on their long edge, but no longer the most urgent gap — `portrait-primary` isn't the hero image this session (see §0), so nothing on the page currently stretches a sub-400px source across a full-height band. Still worth a higher-resolution replacement if one turns up. |

`milestone-isppakistan` may be obtainable from an Internet Archive capture of
isppakistan.com — **check rights before using it.** Do not hotlink event photography from
organisers; request permission. For the four remaining named-event photographs, A2Z
Creatorz's own site is not the right place to keep looking (see above) — try the event
organisers' own galleries (GITEX and CeBIT publish photo archives; see the "PHOTO GALLERY"
pages found on gitex.com this session) or the subject directly.

---

## 14. Unverified facts

Most of it still, but not all — see `CONTENT-SOURCE-MAP.md` for the full table (not fully
updated with this session's finds yet — see §16). **Now verified:** the P@SHA chairmanship
(P@SHA's own 2024 election notice), the 2007 A2Z Creatorz founding year (its LinkedIn
company page, corroborated this session by its own "About" page text — "since its
inception in June 2007"), and three event years — GITEX Dubai 2014, GITEX Saudi Arabia
2010, ITCN Asia 2025 — all via A2Z Creatorz's own dated archive posts (see §0). The
remaining highest-risk items:

- **"800+ customers"** — the headline figure of the Impact section.
- **The 1998 start year** — every "years in technology" figure derives from it.
- **The five/six market lists.**
- **The HBFC project** — confirm the client permits being named. (This session found and
  used A2Z Creatorz's own public post about winning the project, which argues *for*
  permission existing, but that's not the same as an explicit confirmation.)
- **P@SHA term start year** — the chairmanship itself is now confirmed; the year it began
  is not. A ProPakistani article about the 2024 succession, checked this session, doesn't
  give it either.
- **The new `leap-sa` engagement's personal-attendance claim** — the company's participation
  and the year are per its own dated post; that the subject personally attended is inferred
  from a photograph believed to show him there, not stated outright by the source.

---

## 15. Things that should NOT be changed casually

1. **The provenance system.** Do not strip `Provenance` fields, do not flip `tier` to
   `'verified'` without a real URL, do not delete the `?audit=1` overlay.
2. **`src: null` placeholders.** Do not replace them with stock photography or invented
   URLs to make the page look fuller.
3. **The presence / delivery / attendance separation** in `projects.ts`, `geography.ts`
   and `events.ts` as three distinct *claims*. `geography.ts`'s derived `countries` array
   does display them together per country, but every badge stays individually labelled —
   Presence, Delivered and Attended never collapse into one undifferentiated claim. Don't
   take that a step further and actually merge the badges, or drop the labels, or imply a
   country got all three from having any one of them.
4. **"Participant" wording** in `events.ts`. Do not promote it to "speaker".
5. **The counters implementation.** It looks like it "should" be an IntersectionObserver.
   It was, and it broke — see bug #5. The comment in `site.ts` explains why.
6. **`.shell` / `.bay` `--pad-l` indirection.** It looks redundant. It is preventing a
   longhand collision — see bug #1.
7. **The spine `left: max(...)` expression** — see bug #2.
8. ~~The four-level meridian stagger~~ — **removed two sessions ago** along with the rest of
   the old three-row ribbon design in favour of the country-card grid, which this session
   then paired with a hub-and-route diagram (§0). This entry is kept only so nobody goes
   looking for code that no longer exists.
9. **The JSON-LD graph.** Do not add unverifiable properties.
10. **The empty `achievements.ts` / `media.ts`.** Empty is the correct state until there is
    something citable.
11. **The null-image guard pattern** (`getImage(id)?.src` checked before rendering `<Plate>`,
    used in Journey, Company/Delivered, Leadership and Gallery — see §0, latest session).
    Do not revert to always rendering a `<Plate>` for whatever `imageId` a data record
    happens to carry; that's what put "photograph to be supplied" placeholders into the
    Gallery and other sections in the first place. New sourced photographs should still
    make their frame reappear automatically — that's the point of the guard.
12. **The unified `.plate img` filter and duotone wash** (`global.css`, §0). Don't remove it
    per-section "because this photo doesn't need it" — the point is that every photo gets
    the same treatment regardless of its source lighting, so the page reads as one graded
    set rather than a snapshot dump. If a genuinely high-resolution, well-lit photograph
    makes the grade look unnecessary on it specifically, that's still consistency working
    as intended.

---

## 16. Recommended next steps

**In order.**

1. **Update `CONTENT-SOURCE-MAP.md`** with this session's finds — it wasn't touched this
   session and is now missing the A2Z Creatorz archive as a source, the three upgraded
   event years, and the new `leap-sa` engagement. `PROGRESS.md` §0/§14 have the detail;
   `CONTENT-SOURCE-MAP.md` is the claim-by-claim table this site's README points readers to,
   so letting it drift from `images.ts`/`events.ts` for another session isn't ideal.
2. **The four still-missing named-event photographs** (CeBIT, Seoul, Harvard, London) need a
   different source than the one this session used — A2Z Creatorz's own archive only covers
   the company's trade-show history, not the subject's personal conference attendance. Try
   the organisers' own photo archives, or the subject directly. See §13.
3. **An actual screen capture of the delivered HBFC portal** — `project-hbfc` now has a real
   signing photo (this session), which is a genuine improvement but still isn't a picture of
   the product itself.
4. **Run the verification pass** using `CONTENT-SOURCE-MAP.md` (once updated per step 1) as
   the worklist. Start with LinkedIn (experience dates, the P@SHA term) and the P@SHA
   office-bearer history. Update `tier` and `url` on each record as it clears.
5. **Fill the 2000–2014 gap** in `timeline.ts` and remove the `auditOnly` placeholder.
6. **Set the real domain** in `astro.config.mjs`.
7. **Populate `achievements.ts` / `media.ts`** if anything citable exists. The section and
   nav entry appear automatically; a second achievement will also switch `Recognition.astro`
   from its single-item "spotlight" layout back to the multi-item grid (§0, two sessions
   ago) — no code change needed, just confirm it still looks right with real content.
8. **Re-run the harness** after any further image work: `npm run qa:audit && npm run
   qa:interact` (both re-run clean this session — 22/22 interaction assertions, 0 overflow,
   0 console errors, 0 undersized targets). `puppeteer` is already installed as a
   devDependency; no setup needed.
9. **Then** run Lighthouse and an axe pass against the built site with images in place.
   Running them now measures placeholders, not the product.
10. Optional: convert supplied photographs to AVIF via Astro's `<Image>` pipeline (they're
    already WebP, converted with `sharp` this session — see §0). `Plate.astro` is the only
    file that would change.
