# AGENTS.md — Operating Manual for mutaafaziz.com

You are working on a single-file, seven-edition personal website. This document gives you
full context: how it's built, what must never break, and every lesson already paid for.
Read this before touching `public/index.html`.

## 0 · Prime directives (violating any of these fails review)

1. **The page must never blank.** The era switcher IIFE runs FIRST in the single `<script>`
   block. Never add code above it; never let another module's failure prevent it from running.
   The served `<body>` carries `data-era="control"`, CSS shows Mission Control when `data-era`
   is absent, and a `<noscript>` rule hides the (useless without JS) switcher. Preserve all
   three layers of this fallback.
2. **One file, zero external resources.** No CDNs, fonts, images, fetch/XHR, analytics, or
   frameworks. Everything inline. If you need an image, draw it with CSS/canvas/SVG-in-CSS.
   `validate.mjs` fails on any request API (fetch, XHR, beacons, sockets). Crawler-only files
   such as `/og.png` are fine: the page itself never loads them.
   **One exception** (owner, 2026-10-18): the J.A.R.V.I.S. easter egg. Only after a visitor
   explicitly opts in, the page injects `/vendor/face/tracker.mjs`, which loads MediaPipe
   Face Landmarker from `/vendor/mediapipe-1.1.1/` (self-hosted, version-pinned, Apache-2.0,
   NOTICE.txt beside it). Nothing third-party, nothing before consent, and the camera video
   never leaves the device: only a head pose reaches the page. `validate.mjs` fails if the
   page references any other `/vendor/` path.
   **Exception 3** (owner, 2026-10-30: every app at mutaafaziz.com carries ads): the Marquee
   ad loader, `<script async src="/ads/v1/ads.js" data-app="site">`, the last tag in `<body>`.
   It is same-origin (the Marquee Worker serves `mutaafaziz.com/ads*`; source: the marquee
   repo, whose AGENTS.md is the integration contract) and the path stays relative so local
   servers never touch the network (it simply 404s there). It fetches slot decisions from
   `/ads/api/config`, sends aggregate counts to `/ads/api/beacon`, and, once AdSense is
   approved and after consent, loads Google's ad hosts (`pagead2.googlesyndication.com`,
   `*.adtrafficquality.google`, `fundingchoicesmessages.google.com`, Google ad frames) in the
   browser. That is the only third-party content and the only request API allowed, and it
   lives in the loader, never in this page. Two banner slots: `footer` (Mission Control,
   above its footer) and `inline` (2026, before Contact). In the markup they are
   `<aside data-mq>`; the "sponsor slots" module turns one into `[data-marquee]` only when
   its edition is shown, so nothing fills a hidden container. Both take no space until
   filled (`:empty` / `[hidden]` hide them, and so does
   `:has(ins.adsbygoogle[data-ad-status="unfilled"])`: Google lazy-fills units below the fold,
   after the loader's 6 s check, so an unfilled unit must not leave its reserved box). No ads in the Door, Work, Pro, 1996 or 2006
   editions. Every footer that sits near a slot links "Ads & privacy" (`/ads/privacy/`), and
   every "zero dependencies" claim about the page (footer, console, view-source banner,
   humans.txt) says "one ad loader" beside it.
   `validate.mjs` fails on any other `<script src>`. No analytics: the loader counts
   impressions in aggregate only (no visitor ids).
3. **`node scripts/validate.mjs` must pass** before any commit. CI runs exactly this.
4. **Privacy rules (from the owner's timeline doc):** no children's names or birthdates
   ("father of three" is the ceiling); no phone number; no internal Disney/ESPN system
   codenames or incident details beyond what's already public-safe here; no names of
   companies from private recruiting conversations. **Digital Craft AI is public** (owner,
   2026-10-18): name it and link https://digitalcraftai.com
   and https://cto.digitalcraftai.com, but never name its clients,
   never link its private repo, and use only the owner's own revenue wording, verbatim:
   "a seven-figure book of retained, recurring clients". No other figures, no dates the owner
   hasn't given.
5. **ES5-compatible syntax** in inline JS (function(){}, var). No arrow functions, template
   literals, optional chaining, or classes — old-device resilience is part of the product.
   (`String.padStart` and `NodeList.forEach` are the accepted ceiling.)

## 1 · System map

```
public/index.html     ← THE PRODUCT (all CSS + HTML + JS, banner-commented sections)
public/llms.txt       ← plain-text brief for AI agents (facts mirrored from the page)
public/AGENTS.md      ← published copy of this file — must be byte-identical (CI checks)
data/scoreboard.json  ← Fleet Scoreboard source of truth (scripts/scoreboard.mjs writes it)
public/humans.txt     ← humanstxt.org credits + a hint for the secrets hunt
public/resume.json    ← JSON Resume for agents (facts mirrored from llms.txt)
public/_headers       ← serves the text files as UTF-8 plain text
public/.well-known/apple-app-site-association ← universal links for the Moon Club iPhone/iPad app
                        (team Z73865R687). Scoped to /metaphases/kids/* deep-link paths only, served as
                        application/json via `_headers`, never redirected. The URL map is owned by
                        mutaaf/moon-club docs/LINKS.md (+ metaphases shared/kidsLinks.ts); change all three
                        together. Workers static assets serve the dot-directory as-is (checked with
                        `wrangler dev`, 2026-11-04). Verify: curl -sI https://mutaafaziz.com/.well-known/apple-app-site-association
public/404.html       ← the not-found page (wrangler `not_found_handling: "404-page"`), no JS
public/about/, public/contact/ ← plain no-JS publisher pages (who runs the site, how to reach him); facts only from llms.txt. /privacy 301s to /ads/privacy/ (Marquee). Added 2026-11-09 for AdSense review.
public/robots.txt     ← allow all + sitemap; public/sitemap.xml lists the canonical URLs
public/adhan/         ← /adhan/, the interactive Adhan Clock guide (index.html, guide.css,
                        guide.js); see "Sub-pages" in §3
wrangler.jsonc        ← Worker config: static assets from public/
scripts/validate.mjs  ← CI gate: structure markers + node --check on inline scripts
.github/workflows/ci.yml
ops/uptime.yml        ← uptime check (every 30 min, non-200 fails); staged, move it to
                        .github/workflows/ to turn it on
```

`public/index.html` internal layout (find sections by their banner comments):

1. `<style>` — scoped per edition: switcher (`#timewarp`), `THE DOOR`, `ERA PRO`,
   `ERA 1996 — THE CONSTRUCT`, `ERA 2006`, `ERA 2026`, `SCREENSAVER`, `MOBILE & TOUCH POLISH`
2. Markup — `#screensaver`, `#flashintro`, `#timewarp`, then one `div.era` per edition:
   `#era-control`, `#era-door`, `#era-work`, `#era-pro`, `#era-1996`, `#era-2006`, `#era-2026`
3. One `<script>` — module IIFEs in this order: **era switcher (must stay first)**,
   fantasy kit (trophies, confetti/18-0 mode, football calendar, league of the eras,
   18-0 spin, leverage, hologram, door fantasy, 1996 arcade, 2006 project draft),
   screensaver, 2026 boot agents, 2026 fleet terminal, 2026 concierge, 2006 flash intro,
   2006 ad/replay, 1996 hit counter, 1996 sparkle trail, 1996 matrix rain, app launcher, secrets

## 2 · The era system

- `body[data-era]` selects the visible edition; `.era{display:none}` + per-era display rules.
- Eras: `control | door | work | pro | 1996 | 2006 | 2026`. Hash-linkable (`#1996`), persisted in
  `localStorage.mutaaf_era`. Fresh visitors → Mission Control (since 2026-10-18; the Door
  was the landing before); returning → their last edition (a saved `door` counts as fresh).
- The switcher nav (`#timewarp`) is restyled *per era* so it belongs to each world. Since
  2026-11-10 (owner: "the navbar between eras and types is overdone") it holds four buttons
  only: Mission Control ("Control" on phones), Work, Pro and 1996 (owner: "its nostalgia is
  epic"). 2006, 2026 and the Door have no switcher button: they're reached from the Door (its Google-style
  "mutaafaziz.com offered in: 1996 2006 2026" line and its buttons), Mission Control's footer
  "Time machine" link (to the Door), the ⌘K palette, Mission Control's prompt, and their hashes.
  Don't add an era button back without the owner. Anything with `data-warp="<era>"` becomes a switch trigger.
- Modules that must react on era entry expose `window.playFlashIntro` (2006) and
  `window.bootAgents` (2026); the switcher calls them guardedly, and each module self-starts
  after definition if its era is already active (the switcher runs before they're defined).

**Adding a new era, checklist:** CSS block scoped `#era-<name>` + `body[data-era="<name>"]`
rules (incl. switcher restyle) → `div.era#era-<name>` markup → a way in from the Door (not `#timewarp`, §2) → add
to `ERAS` array → door button/search mapping if audience-worthy → screensaver scene mapping →
marker in `validate.mjs` → mobile pass (§5) → test checklist (§7).

## 3 · Subsystem guides

### Screensaver (all eras, 20s idle by default)
- **Every edition: the page decays into the helm** (since 2026-10-18; it began on Mission
  Control). The helm is tinted per edition (`ERA_PAL`: 1996 phosphor green, 2006 aqua, 2026
  white, Pro steel, Door Google blue, Mission Control aurora), and follows your head if
  J.A.R.V.I.S. tracking is on. The period scenes (maze, bounce, flurry) are now only reached by
  WOPR's forced scenes (`mfScreensaver(scene)`). It never starts while the J.A.R.V.I.S. card,
  the HUD or a secret is open.
- **How the decay works.** After 5s of stillness (`DSTART`)
  an overlay (`#ssdis`, three canvases: mask, motes, helm) blacks out the real page cell by
  cell (8px, 6px on phones), edges first (threshold = 0.62·random + 0.38·(1 − distance from
  centre)). Each dying cell may throw a mote in the colour beneath it: an exact pixel read
  for canvases (the sky), otherwise the computed text or background colour from
  `elementFromPoint` (cached per 32px block). Motes spiral into the centre, where an
  aurora-field `helm` assembles (it fades in from 22% decay). Progress is
  `p(u) = (e^(4u) − 1)/(e^4 − 1)` over `u ∈ [0,1]` from 5s to the visitor's delay: slow,
  then fast, landing on black + helm exactly at the screensaver time. Any input removes
  it instantly; the settings pill appears if it got past halfway. The check for
  `window.AuroraField` happens when the timer fires, because the library is inlined later
  in the script than this module (it ran the legacy flurry when checked at load).
- **Visitor-tunable.** After every wake a pill (`#sswake`) offers Turn off · − · delay · + ·
  Done (steps 10s/20s/30s/1m/2m/5m), auto-hides after 9s unless hovered or focused, Esc
  closes. The choice persists in `localStorage.mutaaf_ss` (seconds; `0` = off). Mission
  Control's prompt takes `screensaver`, `screensaver off|on|45|2m` via
  `window.mfScreensaverDelay(sec)`; with no arg it returns the current delay.
One engine, era-mapped scenes: `1996→maze`, `2006→bounce`, `pro/2026→flurry`.
- DPR-aware canvas: `resize()` scales by devicePixelRatio (cap 2); **draw in CSS pixels
  using `VW`/`VH`**, never `canvas.width/height` directly.
- `initScene()` picks the scene from `body[data-era]`; `frame(now)` dispatches per scene.
- Maze: recursive-backtracker grid, left-hand-rule walker, per-column raycaster (1px rays).
  Walls sample an animated offscreen texture (two counter-scrolling pattern layers blended
  with `difference` + perpetual `hue` rotation = infinite moiré). Distance-adaptive source
  width anti-aliases far walls. Glass floor AND ceiling: per-column reflections drawn both
  ways + `glassGrad`/`ceilGlassGrad` sheens + 1px horizon line. Smileys spin the walker 180°.
- Wake = any input; 450ms grace after show; never triggers over the 2006 flash intro;
  disabled entirely under `prefers-reduced-motion`.

### Mission Control (`#era-control`, the landing)
- **Identity (owner, 2026-10-18): founder first.** The site must not rest on any employer.
  Digital Craft AI leads (kicker, lede, the primary CTA, the `.mc-dc` band under either hero,
  the feed's first row, the Pro résumé's first entry, every era's bio and timeline); Disney/ESPN
  stays as a major credential, phrased as "also". If the ESPN role ends, it becomes a past
  entry and nothing else on the page should need to change.
- Purpose: tell a first-time visitor who this is, show what's live, and route them: hiring →
  Work, AI work → the 2026 Lab/scoreboard, the work → `/manifest/`, apps → the launcher, the
  eras → the footer's "Time machine" link (the Door).
- The terminal feed (`<!-- SCOREBOARD:CONTROL:* -->`) and metrics strip
  (`<!-- SCOREBOARD:CONTROLM:* -->`) are generated by `scripts/scoreboard.mjs`; edit copy in
  `renderControl*` in the renderer, never in the page.
- **Sleek and simple (owner, 2026-11-10).** Under the sky the page is five things, in order:
  the Digital Craft AI band (one row), the operating model, the live console (terminal feed
  and prompt, with the four metrics beside it on the same night panel), three paths (Work,
  the Lab, the manifest), the footer. The signal-map canvas and the "time machine" path card
  were retired then; the apps live in the launcher and the eras on the Door. Add to an
  existing section before adding a new one.
- The `ask` prompt is a regex router, not a model, and says so. Contact intent stays first
  (§6). It also accepts the secrets' cheat codes (the secrets module captures `#mcform`).
- No-JS: hero, feed, metrics, paths and contact are plain HTML; only animation is JS.
- **The operating model** (`#mcops`, owner request 2026-10-18: "get my expertise and
  AI-native engineering forward"). Six rules, right under the Digital Craft AI band: contracts,
  not prompts · CI lands the work · review is a required check · autonomy on a leash ·
  measured, never typed · built for the agents that read it. Each rule carries a "proof →"
  link to a public artifact; a rule without checkable proof doesn't go on the list, and no
  rule types a fleet number (those stay generated). Each rule is a `<details name="mcops">` row
  (one open at a time): the title shows, the paragraph and its proof open on a tap. The heading
  sits sticky on the left beside them. The prompt answers `how do you build`, `principles`,
  `ai native`, `governance`… with the six in one line. Pro mirrors it as "AI-Native
  Engineering" (four plain bullets, after Profile), and `llms.txt` lists all six.
- **The machine-readable résumé.** `/resume.json` (JSON Resume v1.0.0) and a schema.org
  `Person` JSON-LD block in `<head>` restate facts already in `llms.txt`, nothing new;
  update all three together. `_headers` opens CORS on `/resume.json` and `/llms.txt` so
  agents in browsers can read them. `validate.mjs` fails if either doesn't parse.
- **Hero: the sky** (`.mc-sky`). It won an owner call over a birch-paper hero on 2026-10-18,
  after a short public A/B (Experiment 01, retired the same day; see §6). There is no
  variant split any more; old `#vote` links land on Mission Control. Link previews come from
  the Open Graph tags and `/og.png` (1200×630, rendered from a scratch HTML card in headless
  Chrome).
- **The sky is a library: [aurora-field](https://github.com/mutaaf/aurora-field)** (public,
  MIT, demo at mutaaf.github.io/aurora-field). The page inlines it between the
  `// AURORA-FIELD:BEGIN/END` markers; `data/aurora-field.json` locks its version and
  sha256, and `validate.mjs` fails on any hand edit. To improve the sky: change the
  aurora-field repo (tests: `node test/run.mjs`), then here run
  `node scripts/sync-aurora.mjs` (it also copies aurora-field/face into `public/vendor/face/`; default source `../aurora-field/src/aurora-field.js`,
  or `--from <path>`) and commit both files. **Usually you don't have to:**
  `.github/workflows/sync-aurora.yml` does it hourly (and on `workflow_dispatch`, or instantly
  on a `repository_dispatch` of type `aurora-field-updated`). It runs the library's tests,
  inlines aurora-field's `main`, runs `validate.mjs`, and pushes to `main` only if the sky
  changed. That push is the deploy, so one change in aurora-field is all it takes. The site's own glue (words → shapes, HUD
  captions, era pause/resume) is the "Mission Control: the sky" module right after it.
- The sky: ~1,600 particles (900 on phones) morph between three shapes tied to the
  headline's words: `mind` (Fibonacci sphere, synapses with travelling signals), `teams`
  (a lead orb and six around it), `platforms` (three layers, traffic streaming up). Words
  hover/focus/click to pin a shape; otherwise it cycles every 6.5s. Drag spins, the cursor
  parts the field, a click sends a shockwave. The HUD readout (nodes, fps) is measured, not
  scripted; under 38 fps it halves the drawn nodes. The PR count in its caption is read from
  the generated metrics strip, never typed in, and never animated. Paused off-screen, in
  other eras and in hidden tabs; reduced motion gets one still frame.
- **Helmets in the header.** Mission Control's header has a `helm · ranger` toggle
  (`.mc-hb`, owner request, 2026-10-18). It summons either one into the sky (pinned for 10 min),
  and `aria-pressed` follows the sky's shape. Pressing the helm while it's up suits up (opens
  the HUD); pressing the ranger while it's up stands down to `mind`. Since aurora-field 2.0 both are
  lit solids (normals, a key light and rim, surfels on WebGL): the helm a gold faceplate over a red
  shell, the ranger white with gold trim and a black glass visor. The ranger brings its own
  palette (`ranger`, aurora-field 1.0's two-tone preset); every other shape wears the aurora.
  A third button, **track my head** (`#mccam`, only where getUserMedia and WebAssembly exist),
  summons the helm and opens the same J.A.R.V.I.S. opt-in card. Pressed while tracking, it
  stops the camera. It never starts the camera by itself.
  The headline's closing words, "work beside them", summon the helm too (owner request,
  2026-10-20): the AI that works beside you is the story the helm tells. They work like the other
  headline words (hover, focus or click); the helm stays out of the rotation.
- **J.A.R.V.I.S. HUD (the helm, kept).** `jarvis` in the prompt summons the helm, then opens
  a full-screen heads-up display (`#mfhud`, the HUD module) around its own aurora-field. You can
  also click the helm in the sky, follow a `mutaafaziz.com/#jarvis` link, or use the "◆ HUD"
  link the sky keeps once a browser has unlocked it (`localStorage mutaaf_jarvis`).
  - The helm looks where the cursor, a finger or the arrow keys point.
  - Six targets lock onto its features through `field.anchors()`, with leaders that fade when
    a feature turns away. Each opens real content: aurora-field (forehead), Digital Craft AI
    (left eye), head tracking (left ear), the agent fleet (right eye), other editions (right
    ear) and Disney · ESPN (mouth).
  - Every number on it is measured: heading, pitch and roll from `field.view()`, nodes and fps
    from `onStats`, and the merged-PR count read from the metrics strip. Never add a gauge
    that isn't real.
  - It is a modal dialog with a focus trap: Esc closes a target, then the HUD. It pauses the
    sky while open, holds off the screensaver, and closes when you leave Mission Control.
- **J.A.R.V.I.S. (opt-in head tracking).** The HUD's Sensors target (or, without the HUD,
  a card that says "Easter egg unlocked") asks before anything happens: "Enable camera" or
  "Not now". On yes: camera permission, then `/vendor/face/tracker.mjs`, a thin wrapper around
  **aurora-field/face** (`face.mjs`, `face-core.mjs`, `face-worker.mjs`, copied next to it by
  the sync script and hash-locked like the inlined library; never hand-edit them).
  - **The engine:** MediaPipe Face Landmarker runs in a Web Worker (GPU, falling back to the
    CPU), with One Euro smoothing, a two-second calibration of your resting face, and an
    adaptive frame rate. MediaPipe and the model are self-hosted (about 17 MB, cached for a year
    via `_headers`); `/vendor/face/*` is our own code, so it caches for five minutes, and the
    page loads `tracker.mjs?v=<release>`.
  - **Self-healing:** a watchdog restarts a stalled detector or camera; a crashed worker falls
    back to the main thread and a failing GPU to the CPU, and both climb back after a healthy
    spell; a lost camera is re-acquired with backoff; hidden tabs pause.
  - **Status:** `mfface-status` events drive the pill ("Tracking your face", "Looking for your
    face…", "Reconnecting…"). If it gives up, the camera turns off and says so.
  - **To test the tracker without the site,** use the aurora-field demo's camera button
    (`mutaaf.github.io/aurora-field/?camera`) or `examples/face.html?autostart&chaos` (the
    failure drill).
  It turns the facial transformation matrix into a selfie-mirrored `{yaw, pitch, roll}`, plus
  `eyes` from the blink blendshapes, and feeds `field.setPose()`. Since aurora-field 1.1 it also
  sends `face`: sixteen channels from the blendshapes (each eyelid, jaw, lips, cheeks, chin and
  brows), each measured against a learned resting baseline. The helm and the ranger are rigged,
  so they wink, open their mouths and smile with you. Mirrored, so your left eye is the helm's
  screen-left eye; `?faceswap` flips sides if a camera mirrors. With the camera on, the HUD
  footer shows the live readings (measured, never decorative). A pill ("Tracking your head
  · on this device only · Stop") stays up while the camera is on. Leaving Mission Control or
  the page stops the camera. Never auto-start it on a later visit.
- **References stay subtle.** Each is invisible unless you know it or go looking: "nominal"
  and MET (Apollo), "end of line." (Tron), "tops out at 88" / "no plutonium" (Back to the
  Future), "1.21 GW" when you spin the sky hard enough, `jarvis` in the prompt summoning
  the sky's helm (in the field, never in the auto-rotation; "At your service."), "go go power
  rangers" / "morphin" summoning the ranger in its white-and-gold palette ("It's morphin' time."), the faint Konami glyph, and prompt-only answers for `sudo`, `make coffee` (418),
  `ping`, `rm -rf`, `exit`, `jarvis`, "shall we play a game". Never put a reference in a
  heading or a metric; never explain the joke. Clean first, nerdy second.

### Work (`#era-work`, work with me; owner request 2026-10-27)
- **"Folded it's a business card, easy to add and CTA; open it's a creative and innovative
  playground."** Reached from the switcher (between Control and Pro), `#work`, `#card`,
  `#hire`, and the paths `/work` and `/hire` (`public/_redirects`). Hiring intent routes
  here everywhere (Mission Control's hero, path 01 and prompt, the Door's search); résumé
  intent still opens Pro, which stays the printable one-pager.
- **The form** is `#era-work[data-form]`, decided by the Work module and re-decided live
  (resize, `(horizontal|vertical)-viewport-segments: 2`, `device-posture`); the card glides
  between forms in a view transition. `?fold=card|open|table` forces one.
  - `card`: phones, the iPhone Duo closed, cover screens down to 280px. The card, then
    Save contact · Book time · Email · Résumé, then three ways to work together (pre-written
    emails).
  - `open`: the Duo open (the Leadership Library's screen table: an iPhone screen 600pt+ on
    its short side), a foldable spanning two segments, or a window ≥900px wide and
    landscape. The card on the left page; the playground on the right: pick a lane, the
    email writes itself, and an aurora-field takes the matching shape (Digital Craft AI's
    crew by industry, or the builder and his agents; `teams` for a leadership role; `mind`
    for talks). With a hinge, each page is one segment and the switcher keeps to the right
    page.
  - `table`: half-folded with the hinge across. The card turns to its QR code on the top
    screen; the actions are below.
- **The card's facts are data/card.json** (no phone number, §0.4). `node scripts/card.mjs`
  writes `/mutaaf.vcf` (served as `text/vcard`; `/card` redirects to it, which is the URL
  to write on NFC tags) and the QR on the card's back, a vCard in the code itself, so any
  phone's camera offers "Add contact" with no network. `scripts/qr.mjs` is a dependency-free
  QR encoder; level L, because level M at 161px didn't decode in WebKit. `validate.mjs` fails
  if either drifts from the data.
- **NFC.** iPhones read only URL records from tags, so a tag holds `mutaafaziz.com/card`.
  On Android Chrome (Web NFC) the card offers "Write to an NFC tag" and writes that record.
- **The flip** never relies on `backface-visibility` (WebKit ignored it in tests): each face
  hides itself as the card passes edge-on. Keep `container-type` and `view-transition-name`
  on `.wk-cardwrap`, never on `.wk-card`: both flatten its 3D.
- Quiet by design: no screensaver (it re-arms instead), no toasts, confetti, secrets,
  launcher dock or ⌘K palette, and launches navigate instantly.

### 1996 time circuits (`#tcirc`, owner request 2026-11-10: "translates through some of the 2000s")
- A year dial under the hit counter: 1996 · 1999 · Y2K · 2001 · 2003. The page is the website;
  the year decides the browser it's seen in (the `.brz` bar: Netscape 3, IE5, IE5.01, IE6,
  Firebird) and the desktop under the dial (`#desk`: none in 1996, Win98 teal for 1999/Y2K,
  XP Bliss for 2001/2003, via `#era-1996[data-yr][data-os]`). Badges in the badge row follow
  the year (`.yb.y99/.y00/.y01/.y03`). State: `mutaaf_1996_year`; `?year=` forces one.
- On the desktop: **Winamp** (the shipped work as a playlist; silent by design, says "0 kbps ·
  silent"; eject or double-click opens the app; the visualizer runs only while playing, in 1996,
  in a visible tab), **AIM** (every launcher app is a buddy, plus agent-fleet; some are away with
  messages in a 2001 voice; a buddy opens an IM with its blurb and link), **Napster** (newest
  work downloading at modem speeds in 1999/Y2K; offline from 2001, as it really was) and the
  **burned CD** (2001 and 2003). Windows drag on wide screens with a mouse.
- Choosing Y2K plays the rollover (`#y2kroll`, a modal): 23:59:55 to midnight, the hit counter
  shows 1900 for a moment, the page glitches, then a Y2K.EXE dialog. Click or Esc skips.
- Everything is read from the launcher's `a.ld-app` links (name, blurb, link, kind, date):
  add an app there and it joins the buddy list, the playlist and the CD. Screen names and away
  messages live in `SN` / `AWAY` in the module; keep them inside what the page already says.
  Track lengths and modem speeds are jokes, never presented as data. No sound, ever.
- Reduced motion: no sign-on stagger, no glitch, no CD spin, no scrolling title; the rollover
  goes straight to its dialog.

### 2026 concierge (`mutaaf.assistant`)
- Scripted local KB — **array order is priority order**. Contact must stay FIRST (see §6).
- Regexes must use word boundaries for short tokens (`\bai\b`, `\bdoes\b`).
- Answers containing `mailopt` (the email-drafting cards) render instantly; others type out.
- All answers are HTML strings; keep links `class="mlink"`.

### 2026 fleet terminal & boot
- Terminal replays a scripted agent shift; ticket/PR numbers increment per cycle; the chip
  row (`.achip`) lights per log author; the stats under it are real (counted from GitHub) and static — never animate a real number.
- `bootAgents()` reveals sections staggered behind an agent-status line; runs once per load.

### The Lab (2026 `#lab-2026`; 1996 already owns `#lab`) and the machine-readable layer
- The Lab is dated field notes, newest first: status chip (`next` / `run` / `ship`), what was
  built, a "Kept" lesson, a source link. Every claim must be checkable in a public repo
  README; private repos never appear. Pro mirrors it in two plain bullets.
- `public/llms.txt` restates facts already on the page — never new biography. When you add
  a Lab entry or change a fact, update `llms.txt` in the same PR.
- This file is public at `/AGENTS.md`. Edit the root copy, then
  `cp AGENTS.md public/AGENTS.md`; `validate.mjs` fails if they differ. Never put anything
  here you wouldn't publish.
### Fantasy & 18-0 kit (ROADMAP §7, items 1–25)
- Modules talk only through guarded `window.mf*` hooks: `mfTrophy(id)`, `mfOnTrophies(fn)`,
  `mfEraHooks` (the switcher calls `mfOnEra` inside a try), `mfPerfect`, `mf180`, `mfCal`,
  `doorFantasy`. Every module is try-wrapped; none may be moved above the switcher.
- **18 trophies = an 18-game season.** Adding a trophy means removing one; the record math
  and the "perfect season" both assume exactly 18.
- 18-0 spin cards are real (18-0 dataset v1.2.0, top card per slot). Never invent ratings;
  the perfection floors (94 every slot, 96 QB/DEF) come from 18-0's README.
- Test hooks: `?18-0` forces the 1-in-6,000 banner, `?sunday` / `?saturday` force the modes.
- Toasts and confetti are suppressed in Pro (and toasts on the Door). All state is
  localStorage-only: `mutaaf_trophies`, `mutaaf_league`, `mutaaf_trash`, `mutaaf_arcade_*`.
- Saturday and Pathfinder are private repos: mention, never link.

### Fleet scoreboard (ROADMAP D1) — numbers are generated, never typed
- `node scripts/scoreboard.mjs` recounts and rewrites three blocks: 2026
  `<!-- SCOREBOARD:2026:* -->`, Pro `<!-- SCOREBOARD:PRO:* -->`, and the agent-fleet line in
  `llms.txt`. `data/scoreboard.json` is the source; `validate.mjs` re-renders it with
  `scripts/scoreboard-render.mjs` and fails on any mismatch. Change copy in the renderer.
- Repos are listed only inside the script. Business repos count toward totals but their
  repo names are never on the page (owner decision 2026-10-16). The company itself, Digital
  Craft AI, is public as of 2026-10-18 (§0.4).
- Cloud routine repos (`ROUTINE_REPOS`) are counted as one separate total: merged PRs on `build/`, `fix/`, `scout/`, `keep/`. They have no reviewer verdict, so they stay out of every review figure.
- **Definitions** (an interviewer may ask — these are exact):
  - *Agent PR*: head branch starts `feat/`, `eng/` or `chore/gtm-`, in a fleet repo.
  - *Merged*: agent PRs in state MERGED. Weekly bars run from the first merge's week.
  - *Blocking verdict*: the reviewer's review heading says blocking / changes requested /
    do not merge (GitHub forbids request-changes on your own PR, so verdicts arrive as
    comments). Block rate = reviewed agent PRs (merged or closed) with ≥1 blocking verdict.
  - *Self-healed*: merged PRs with ≥1 `heal:` commit. *Escalation*: ≥2 `heal:` commits
    (the fleet's two-attempt cap).
  - *Lead time*: median minutes from PR opened to merged.
  - *Effort index*: Σ `total_cost_usd` ÷ merged PRs over the last 30 days, against the first
    full month with ≥20 merges = 100. The Max plan makes dollars relative effort, so the page
    never shows dollars (owner decision). *Runs per merge*: run-log entries ÷ merges, 30 days.
  - *Reviewed before merge*: a review's `submittedAt` ≤ the PR's `mergedAt`. Split at
    `GATE_SINCE` (2026-10-17, agent-fleet ticket 0070: reviewer sign-off became a required
    check). *Merged over a block*: merged before the gate with a blocking last verdict.
- The review-gap finding publishes in the `.sbfind` line (owner decision: fix first, then
  publish — the gate went live on every fleet repo that can still merge on 2026-10-17;
  courtiq's adoption PR waits on its own stale tests, and its fleet is dormant).
- Refresh: `scripts/scoreboard-nightly.sh` (launchd, 05:30 daily, installed by
  `scripts/install-scoreboard-job.sh`) opens a PR only when a number changes. A human merges
  it. It runs from `~/.local/share` against a clone in `~/.cache`: launchd can't read
  `~/Desktop` (macOS TCC), so never point the plist at the working tree.

### Secrets (16 nostalgia eggs, last module in the script)
- Typed codes (anywhere outside a text box), the `C:\>` box in SECRETS.TXT, and the Door
  search all feed one `CODES` table. Overlays share `#ngover` (Notepad hint file, WOPR, BSOD,
  Snake II); `#ngclippy` and `#ngfx` (iddqd glow, Great Scott trails, Pac-Man) sit beside it.
- **Pro is a no-fun zone**: no codes, no Clippy, no Great Scott. Only the console banner and
  the view-source comment exist there, and recruiters never see either.
- The Door hides toasts, so its replies go in `#ngdoorcap` under the search box.
- Exactly 16 secrets, separate from the 18 trophies (which stay at 18). Adding one means
  updating its hint line in `SECRETS`; every egg needs a hint somewhere in the site's voice.
- State is `mutaaf_secrets`, `mutaaf_snake`, `mutaaf_clippy` (localStorage only).
- Reduced motion: no glow, trails, Pac-Man, roll or type-out; the rabbit sits still.
  `window.mfScreensaver(scene)` (WOPR's Falken's Maze) returns false under reduced motion.
- Testing in automation: dispatch real `KeyboardEvent`s (the type tool doesn't fire keydown),
  and remember open overlays swallow codes by design.

### App launcher (`#launcher` dock + `#lpal` palette, every edition but the Door)
- The dock's `<a class="ld-app">` links are the source of truth: the script reads name, tip,
  colour (`data-color`), kind, search keywords (`data-kw`) and launch date (`data-added`,
  YYYY-MM-DD, the day it joined the dock) from them, so adding an app is one link plus one
  `<symbol id="lic-<app>">` icon. Only apps the page already links to.
- **The dock never shows everything (owner, 2026-11-10).** The script picks what fits
  (3 to 7, from the width): Digital Craft AI first, then the visitor's recents, then the newest
  by `data-added`; the rest are hidden (`#launcher.smart`, `[data-dock]`). An app is "new" for 7
  days or until opened (a dot on the icon and in the palette). The last button is **All apps**.
- **All apps is a home screen.** Empty query: a "New and suggested" (or "Jump back in") row,
  then every app on pages you swipe, one per kind: Apps, Games, Studio (Company + Library),
  with dots. Page size is measured (columns from the width; two rows, more on the Duo), and
  the arrow keys move in two dimensions. Typing switches to the ranked results list with
  quick actions and editions, as before.
- **iPhone Duo.** Same device test as Work (`#era-work`): an iPhone with a 600pt+ short side
  or the 466×678 cover. Open (or any foldable across two segments), the palette is a two-page
  spread: search and suggestions with their descriptions on the left screen, the app pages on
  the right, nothing on the hinge (`viewport-segment` env values when the browser has them,
  50%/2px otherwise), and the dock keeps to the right page. Closed, it's the phone sheet.
  `?duo` fakes the device on a desktop for testing.
- Deep links must be ones the target app really reads, listed in that repo's AGENTS.md
  § URL parameters (OUTATIME: `?play=friends|quick|daily`, `?board=`, `?garage`, `?view=3d|2d`;
  OpenAero: `?airport=`, `?mission=`, `?view=terrain`; COLD GAS: `?play=reveal|jump`,
  `?board=today`; KIN: `?wx=snow|rain|storm|wind|heat|cold|clear`, `?hour=`,
  `?debug`; Hearth: the `/hearth/demo/` path, no parameters; Chalk Talk: `?sport=basketball|flag5|flag7`,
  `&play=<concept key>`; Metaphases: the `/metaphases/t/<TICKER>`,
  `/metaphases/compass`, `/metaphases/retrace`, `/metaphases/watchlist` and `/metaphases/learn` paths; Metaphases Kids:
  the `/metaphases/kids/` and `/metaphases/kids/app` paths (the app page keeps the Moon Club download behind
  its grown-up gate: never link the TestFlight or App Store URL directly); the Leadership Library:
  `/library/<book-slug>/` paths, no parameters). Verify each on prod
  before adding one; never invent a parameter.
- ⌘K / Ctrl+K toggles, `/` opens (not while typing, not over a secrets overlay). The Door
  ignores both. ≤900px: the dock becomes a thumb button (bottom-left) and the palette a
  bottom sheet you drag down to dismiss; phones don't auto-focus the input.
- One model, five skins: 2026 frosted dock with magnification, Pro restrained (no flood),
  1996 PROGMAN.EXE / RUN.EXE with phosphor icons, 2006 Aqua shelf with reflections.
- Launch = `#lfly` floods the app's colour from the icon, then navigates. Reduced motion and
  Pro navigate instantly; modifier/middle clicks keep the browser's new-tab behaviour.
- Recents: `mutaaf_launcher_recent` (localStorage, max 4) → dock order and dots, suggestions.
- The dock also carries **aurora-field** (`data-app="af"`, kind Library), which links to its demo.
  Its icon is the helm in particles with a gold grille.
- It opens with the company: **Digital Craft AI** (`dc`) and **Fractional CTO** (`cto`), kind Company.
  Both Digital Craft sites carry the same launcher from github.com/mutaaf/launcher, which holds
  the shared app list and icons; when an app or icon changes here, change it there too.

### Sub-pages (`/adhan/`, the Adhan Clock guide; 2026-11-02)
- A standalone page, not an edition: no era switcher, launcher or secrets. Its facts are the
  Adhan Clock product facts in `llms.txt` and nothing more; links go to
  adhantv.live. The prayer times in its sky are a labelled example.
- Same rules as the page, enforced by `validate.mjs`: ES5, no request APIs, no third-party
  anything, no em-dashes, no audio. The script and CSS are same-origin files so `_headers`
  can serve a strict CSP (`script-src 'self'; style-src 'self'`): never add an inline
  `<script>`, `<style>` or `style=""` there (set styles from JS through the CSSOM instead).
- State is `adhan_guide` in localStorage, always inside try/catch.
- Listed in `sitemap.xml` and `llms.txt`. Test hook: `?t=HH:MM` pins the living-sky demo at that time.
- **Look (owner, 2026-11-02: "Tesla and Apple like minimal", then "extreme parallax through
  the day per prayer matched"):** the page is one day. A fixed world (sky, stars, sun, moon,
  clouds and a city drawn in three depths: far ridge, middle town, near city with domes and
  minarets) sits behind everything, and the scroll position is the time of day. Each section is
  pinned to its prayer with `data-time` (minutes): the hero is Fajr, the living sky is morning,
  then Dhuhr, Asr (setup), Maghrib (privacy) and Isha (support); the time lingers at each
  prayer and moves on between them. At a prayer the city's lamps glow and gold rings rise from
  the horizon; the nav shows the time and the rail (wide screens) the prayer. `data-ink` gives
  each section ink that suits its sky (navy by day, cream by night); the demo is night glass,
  the setup checklist day glass (night glass without the script). The demo opens at 9:20 AM (the
  morning section's time), not the visitor's time, and follows the scroll until it is dragged,
  played or jumped (its "Now" button jumps to the visitor's own clock); it follows the scroll
  again once it leaves the screen. Dragging the demo turns the whole sky while it is on screen.
  The time of day is the theme, so there is no light/dark toggle. Under reduced motion the city and clouds
  hold still; the sun, moon and sky colour still follow the scroll. Gold (#E8C27A) and cream (#F6EAD0) are the
  only accents; huge tight headlines, very few words. Never letter-space Arabic.
- **Images are the real app icon.** `icon.svg` is copied from the azan repo
  (`public/icons/icon.svg`); `icon-32.png`, `apple-touch-icon.png` (full bleed) and `og.png`
  (1200×630) are rendered from it by `scripts/adhan-assets.mjs` (needs Playwright via
  `PLAYWRIGHT=`). Share links are plain `<a>` URLs with encoded text; the Share button uses
  `navigator.share` and falls back to copying the link.

### `/apps/`, the app developer page (2026-11-05)
- A standalone page with no JS: the owner's background and the five apps on his App Store account, so a reader (App Review included) can check who makes them. Facts come from `llms.txt`. Same CSP approach as `/adhan/`; no inline styles or scripts. Never call Moon Club a kids app here, or 17-0 fantasy football: both listings avoid those words on purpose. Update the list when an app's store status or the account's app list changes.

### `/manifest/`, the AI-Native Manifest (2026-11-05)
- A standalone parallax page: index.html, manifest.css, manifest.js (ES5, same-origin, strict CSP, enforced by `validate.mjs`) and self-hosted OFL fonts in `fonts/`. No inline scripts, styles or style attributes; set styles through the CSSOM.
- It works backwards: the page opens on the finished work (`.wall`, real screens in `shots/`, every tile a live link) at 0 ft, then each section answers the next question back (`.back`), climbing to the first line of the contract at 42,000 ft. Keep that order. The sky runs the same way, ground first.
- Altitudes and some headings are pop culture references, kept subtle and never explained beyond the last line. Real figures are never altered for a joke: the Builder really has eleven steps. Add a tile and update the "13 products" stat when a product ships, and only for something a visitor can open.
- Section `data-alt` drives the altimeter; `#stage` is the pinned line-to-loop morph, and its static markup and Figure 1 are what show without JS or under reduced motion. `#sim` runs the same check order as cold-gas `agent-automerge.yml`: update it if that workflow changes.
- Every claim comes from a repo, a log or a store record, and each lifecycle stage carries an Enforced, Partly enforced or Unproven tag. Keep failures and "Still broken" current; it is the point of the page. The audit table comes from `scripts/conformance.mjs` (`data/conformance.json`), which reads each repo from GitHub nightly and is checked by `validate.mjs`; add a repo to its `REPOS` list when one ships. Business repos stay out by name. Merged counts sit in `<span data-sb>` tags, rewritten by `scoreboard.mjs` and checked by `validate.mjs`; the weekly chart is a dated snapshot. Never name business repos (see the scoreboard rule), and never call Moon Club a kids app or 17-0 fantasy football.
- Every app people can install shows how, at all times. Native tiles are `<div class="tile">` with a stretched `.tl` link and a `.dl` download button; the status label and button sit between `<!--store:BUNDLE-->` markers and the hero's App Store stat between `<!--stores:stat-->`, all rendered by `scripts/stores.mjs` from Cast List (`https://mutaafaziz.com/cast/api/apps`, which hears from App Store Connect hourly through Stage Manager; no Apple key on this machine) into `data/stores.json`, nightly in `scoreboard-nightly.sh`. Live → App Store button; otherwise an open public TestFlight link → beta button. Gated apps (`store.gate` in Cast List's catalog, Moon Club) always link the grown-up gate, never Apple. `validate.mjs` fails if the page differs from the data or an installable app has no tile (add one, or an `OMIT` reason). Never hand-edit between the markers.

### `/ensemble/`, The Ensemble (2026-11-10)
- A standalone page that explains the shared services (Cue, Prompter, Stage Manager, Cast List, Playbill, Marquee, Lobby) six times: Act I for a five-year-old, then a new grad, an engineer, an architect, a CTO and a CEO, ending with a curtain call that sets the target state against today. Linked from the manifest's Ensemble section (1,776 ft).
- Same rules as `/manifest/`, enforced by `validate.mjs`: index.html, ensemble.css, ensemble.js (ES5, same-origin, strict CSP) and self-hosted OFL fonts in `fonts/` (Bodoni Moda, Courier Prime, Instrument Sans). No inline styles or scripts; icons are `<symbol>`s coloured through `stroke`/`color` on the outer `<svg>`, because CSS can't reach inside `<use>`.
- Each act keeps the same shape: analogy, a diagram, all seven services at that depth, then "not yet" and "the ideal" boxes. Each act has its own stage-light colour (`.act1` to `.act6`, `.fin`).
- Every act head carries a "you are here" seat map, and each act has several diagrams. Four of them are data, not illustration, and go stale: the whisper jars and the meal-plan bar (Prompter shares), the share-vs-used chart (a dated `/prompter/api/health` snapshot), the "who works on which show" matrix (Cast List surfaces plus Prompter shares and Stage Manager's apps) and the curtain-call timeline and rings. Update them with the facts they show.
- Facts come from the services' repos and their live health endpoints (`/cast/api/drift`, `/prompter/api/health`, `/stage/api/health`) and are dated in the footer. When a service ships, a phase lands or a "not yet" closes, update the act that mentions it and the curtain-call table. Pop culture references in headings stay subtle and unexplained. Never name Moon Club as a kids app (validate checks).

### 2006 flash intro
- `#flashintro` overlay: fake preloader → letter fly-in → ENTER SITE. Auto-plays once per
  load on entering 2006; footer "replay flash intro" link replays; skip always visible.

## 4 · Voice & aesthetics per edition

- **Mission Control**: Nordic restraint. Birch paper (#F3F1EC), ink (#15181B), hairlines,
  Avenir; one aurora accent (#7BE3C3) that lives only in polar night (the sky hero and the
  console). Calm, real numbers, no exclamation marks.
- **Door**: Google-homepage spartan. Arial. Nothing extra — restraint IS the joke.
- **Pro**: recruiter-grade professionalism. Georgia headings. No jokes, no emoji, real metrics.
- **1996**: phosphor-green Courier terminal, Matrix references, blink tags, maximal kitsch —
  but executed precisely.
- **2006**: Trebuchet gloss, gradients, rounded everything, BETA badges, self-aware Web 2.0
  optimism.
- **2026**: Apple-keynote minimalism. Helvetica Neue, one accent (#0066CC), monospace only
  for agent surfaces. Every flourish must feel inevitable, not decorated.
- Facts about the owner come from the timeline data already embedded in the page (career,
  Karachi→South Florida→Carrollton→UTA arc, Hebron '05, DEP presidency, The Bros/Rising
  Stars DFW, Family XP flagship). Don't invent new biography.

## 5 · Mobile bar (non-negotiable)

- Touch targets ≥44pt (`@media(pointer:coarse)` block handles most; extend it, don't inline).
- Inputs ≥16px font (iOS zoom-jump prevention).
- Safe-area insets on fixed elements (`env(safe-area-inset-*)`).
- No horizontal body scroll ever; wide content scrolls in its own container.
- Test at 390px width minimum before shipping.

## 6 · Lessons log (bugs already paid for — do not repay)

| Lesson | What happened |
|---|---|
| **Script order = availability** | The switcher originally ran last; any earlier module error blanked the whole site on some devices. Switcher now runs first — keep it there. |
| **Loose regex hijacks intent** | KB pattern contained bare `do`, so "How **do** I reach him?" matched the *work* answer. Short tokens need `\b` boundaries; KB order is priority. |
| **DPR or it's pixelated** | 1× canvas stretched on Retina looked rough; always scale by devicePixelRatio and draw in CSS px. |
| **Verify deploys with cache-busters** | Edge/browser caches serve stale HTML for a while; `curl "https://mutaafaziz.com/?cb=$(date +%s)"` when confirming. |
| **Grouping properties flatten 3D** | The Work card's flip showed its mirrored back in WebKit and nothing in Chromium: `container-type` and `view-transition-name` on the 3D element flatten it. Put them on a wrapper. |
| **Era-scoped CSS only** | Every rule is prefixed `#era-X` / `body[data-era=X]`. Unscoped rules leak across worlds. |
| **Back button restores the page as you left it** | A launch animation that covers the screen will still be covering it when bfcache restores the page. Anything that floods or locks the screen before navigating must reset on `pageshow`. |
| **Seed nothing you show as real** | Experiment 01 (2026-10-18) put a live A/B vote on the landing. A request to seed 200 fake votes "for a 50/50 baseline" was declined: the card promised an honest tally. The fix was a *visible* 100 + 100 prior and no percentages under 20 votes. The owner then picked the sky outright and retired the vote and its Worker. Any number shown as real must be real. |
| **`marquee` and friends are load-bearing** | Period-authentic elements (marquee, blink) are features. Don't "modernize" them away. |

## 7 · Definition of done

- [ ] `node scripts/validate.mjs` green
- [ ] All seven editions render via their `#hash` URLs (Mission Control is `#control`)
- [ ] Mission Control renders with JS disabled
- [ ] Screensaver correct in each era; wakes on input; absent under reduced-motion
- [ ] 390px-width pass on any touched edition
- [ ] No new external requests (check DevTools network tab: only the document itself and `/ads/v1/ads.js`, §0.2 exception 3)
- [ ] Privacy rules (§0.4) respected — in `index.html`, `llms.txt`, and this file
- [ ] `llms.txt` updated if facts or Lab entries changed
- [ ] Pushed to a branch → CI green → PR (or `main` if trivial); Workers Builds deploys

## 8 · The future

**[ROADMAP.md](ROADMAP.md)** holds the 2036 vision and feature backlog. Refine it via PR
*before* building anything from it; the owner approves direction there first.

## 9 · Pipeline

Push to `main` = production deploy (Cloudflare Workers Builds, `npx wrangler deploy`).
Other branches = preview versions (`npx wrangler versions upload`). Rollback:
`npx wrangler rollback`. Emergency manual deploy: `npx wrangler deploy` (OAuth-authed local).
The legacy Worker (old Notion proxy; name in the Cloudflare dashboard) is detached — leave it, or delete
with owner approval only.