# Agent guide: invisible-software

This package app serves one self-contained, phone-only product demo. The story is told only through the phone: Victoria, Max, Grok Bot, ChatGPT, their apps, and their notifications. Keep it that way. Don't add architecture or behind-the-scenes material. The page makes no external requests (no CDNs or remote fonts), and every image and font is inlined.

## Layout

- **Pages:** `/` is `src/pages/home.html`, `/demo` is the deck (`src/deck.html` + slides), `/graph` is `src/pages/graph.html`. Anything else 404s, except `/c/<path>` assets under any page.
- **Graph data:** `data/*.csv` and `data/make_trend.py` are the source (Epoch AI + METR). `src/data-trend.json` is derived from `data/benchmark-trend-data.csv` and inlined into the graph at build time. Credit Epoch AI and METR on the chart; no model IDs on screen.

- **`app/router.ts`:** the app entry, which default-exports `{ fetch }`.
  - `/c/<path>` serves an inlined image or font.
  - `/health` returns JSON.
  - Every other path serves `index.html`.
- **`app/assets.generated.ts`:** generated by `npm run build` (`scripts/build-assets.mjs`). Never edit it by hand. Rebuild and commit it after any change under `src/`.
- **`src/deck.html`:** the page shell.
  - Only each slide's `.phone` is shown, centered and scaled to fit. Everything else in a slide is hidden.
  - It plays one slide timeline at a time and holds each step on its last frame.
  - It keeps the hash in sync as `#<label>.<n>`. Steps are pushed to history, and `hashchange` jumps to the new step.
  - It exposes `window.__slideshow` for tests.
- **`src/slides/*.html`:** one `<section class="slide">` per slide, in file-name order. Each has these attributes:
  - `data-label`: its URL name.
  - `data-duration`.
  - `data-steps`: motion segments `[[from, to], ...]`, each starting and ending at rest.
  - `data-human`: the 1-based segments that begin with a person's action.
  - `data-opener` (optional): 1-based segments that start a step with no human action (a scene opener).
- **Steps:** a deck step is one human segment plus every automatic segment after it, even across slides (a step can also run into the next slide). One press plays all of it; the next press waits for the next human action. Only the scene openers have no human segment: 2.1 (first slide), 6.1 and 7.1 (`data-opener`). A step that ends on a result (Booked, Sent, a loaded page) rests there; the next scene waits for the arrow.
  - Current slides: `2` Grok Bot ping, `3` Victoria's app, `5` Max forks through ChatGPT, `6` Grok Bot merges both wishes, `7` Max asks Muse, which can't reach his ChatGPT-built scheduler.
  - Labels are kept stable, so existing links still work.
- **`src/c/`:** the shared timeline runtime (`lib.js`, `lib.css`), Victoria's app (`vc-finder.js`, `vc-app.css`), the chat apps (`chat.css`), photos, icons and fonts.

## Rules

- **The phone tells the whole story.** No code, editors, architecture diagrams, build or hosting details, or behind-the-scenes screens.
- **Every step except the 2.1, 6.1 and 7.1 openers must begin with a human action** (a tap, typing or sending, or opening a link). Computer activity, such as replies, apps opening and notifications, goes in automatic segments.
- **Every step must visibly change the phone.** If a step doesn't change the phone, merge it or drop it, then run `npm run steps -- --write` and `npm run build`.
- **A step never stops mid-motion.**
- **Brand marks:** Grok Bot uses `src/c/assets/grokbot.svg` (Kent prefers it). ChatGPT and Muse use official assets (OpenAI Blossom, Muse avatar from Meta's App Store screenshots). Never redraw them.
- **Name:** always "Grok Bot" on screen and in docs.
- **Muse** follows Muse's own chat look (near-white, round top buttons, gray bubbles, Message bar, 5-icon tab bar) with the official Muse avatar. Keep it a plain chat.
- **Grok Bot never sends texts.** It gives Victoria a link to her app.
- **Max's app opens at `schedule.maxbarber.example`,** never a kody.run URL.
- **No IDs, hashes or tokens on screen.** Say "credentials", never "secrets".
- **Keep every URL relative.** Kody mounts the app under `/packages/invisible-software/`; the demo is `/demo` and the chart `/graph`.

## Verify

Run `npm run build && npm run serve`, then `npm run verify`. Verify needs `playwright`; set `CHROMIUM_PATH` to choose a browser. It fails on any of these:
- console errors or external requests;
- a step that doesn't hold, or that starts or ends mid-motion;
- a hash or deep link that doesn't match its step;
- an opener other than 2.1, 6.1 or 7.1, or any other step that has no tap within 1.5 s of its start, or that doesn't play its automatic segments to the end from a single press.