@kentcdodds/invisible-software

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.