waygraph 0.13.6 → 0.14.0

package/README.md

@@ -3,7 +3,10 @@
 A typed graph of reusable Blocks for driving a browser through E2E flows, in place of a
 flat pile of ad hoc helper functions.
 
-**Current:** `0.12.44` — floating todo dock (visible under `--mini`, `ctx.todoPos` / click / `--todo-left|right`), live `ctx.title` banner updates, instant highlight tone snaps.
+Not yet `1.0.0` - breaking changes between minor versions are expected. See
+[ROADMAP.md](./ROADMAP.md) for what's shipped, spec'd, and planned, and
+`openspec/specs/` for the current merged spec behind each capability
+(`openspec/changes/archive/` holds the historical planning artifacts once a change ships).
 
 This repo is the `waygraph` npm package itself. The full live **Sauce Demo** example
 (Page inventory hub, Effect Add/Remove, MemNav Open details, `waygraph auto`) ships
@@ -11,48 +14,325 @@ in-tree at [`examples/saucedemo`](./examples/saucedemo). `waygraph try demo` cop
 [`templates/quickstart`](./templates/quickstart) (same Sauce Demo Blocks) into an OS
 temp dir.
 
-See [ROADMAP.md](./ROADMAP.md) for what's shipped, spec'd, and planned by version, and
-`openspec/changes/` for the actual planning artifacts behind each roadmap item.
-
 ## Docs (GitHub Pages)
 
-Browser docs (quick start, **demo / run**, **auto explore**, engine handout, consumer layout, deploy):
-
-- **Published:** https://deviate-dv8.github.io/waygraph/ (workflow auto-enables Pages via `enablement: true`; manual Settings only if org policy blocks it)
-- **Source:** [`docs/`](./docs/) — static HTML, no build step
-- **Local preview:** `npm run docs:preview` → http://127.0.0.1:4173/
-- **Deploy:** push to `main` touching `docs/**` runs [`.github/workflows/pages.yml`](./.github/workflows/pages.yml) (`workflow_dispatch` also works)
-- **Demo / run contract:** [`docs/demo.html`](./docs/demo.html) — `list` / `.flow.ts` path / export / flags
-- **Auto explore:** [`docs/auto.html`](./docs/auto.html) — prefer `auto --cli` / `npm run auto:cli` (same menus as headed)
-- **In-repo example:** [`examples/saucedemo`](./examples/saucedemo) — full Sauce Demo project
-- **Convention showcase (Pages):** [`docs/saucedemo/`](./docs/saucedemo/) —
+Browser docs (quick start, **demo / run**, **auto explore**, engine handout, consumer
+layout, deploy):
+
+- **Published:** https://deviate-dv8.github.io/waygraph/ (workflow auto-enables Pages via
+  `enablement: true`; manual Settings only if org policy blocks it)
+- **Source:** [`docs/`](./docs/) - static HTML, no build step
+- **Local preview:** `npm run docs:preview` -> http://127.0.0.1:4173/
+- **Deploy:** push to `main` touching `docs/**` runs
+  [`.github/workflows/pages.yml`](./.github/workflows/pages.yml) (`workflow_dispatch` also
+  works)
+- **Demo / run contract:** [`docs/demo.html`](./docs/demo.html) - `list` / `.flow.ts` path
+  / export / flags
+- **Auto explore:** [`docs/auto.html`](./docs/auto.html) - prefer `auto --cli` /
+  `npm run auto:cli` (same menus as headed)
+- **In-repo example:** [`examples/saucedemo`](./examples/saucedemo) - full Sauce Demo
+  project
+- **Convention showcase (Pages):** [`docs/saucedemo/`](./docs/saucedemo/) -
   https://deviate-dv8.github.io/waygraph/saucedemo/
 - **Helpers (consumer copy):** [`examples/saucedemo/docs/HELPERS.md`](./examples/saucedemo/docs/HELPERS.md)
 
-This README stays the in-repo API narrative; Pages is the same material for eyeballing and cross-mesh handoff.
+This README stays the in-repo API narrative; Pages is the same material for eyeballing and
+cross-mesh handoff.
+
+## Install
+
+```bash
+npm install waygraph @playwright/test
+```
+
+`@playwright/test` is a peer dependency, not bundled - you bring your own version
+(`^1.40.0` or later) since it's also what drives the rest of your test suite. Requires
+Node 22+ (uses `URL`/`URLPattern` from `@types/node` for `Trait.url`'s type checking).
+
+## Core concepts
+
+- **`Checkpoint<Tag>`** - a state identified solely by its string tag. Carries no data.
+- **`MemPage`** / **`MemKey<T>`** - typed shared memory across a run, keyed by object
+  identity (`key<T>("debug-name")`), not by name string.
+- **`Block<In, Out>`** - one step: `act(page, input, mem)` does the work,
+  `resolve()` decides the resulting Checkpoint (never touches the page or mem),
+  `verify` (optional) confirms the page actually matches what `resolve()` claimed.
+- **`Trait`** - a named, independently-reportable check (`{ name, check(page, mem) }`).
+  Built-in factories: `Trait.url` / `Trait.text` / `Trait.visible` (also importable as
+  free functions `urlMatches` / `textEquals` / `visible`).
+- **`Flow`** - several Blocks chained with `Engine().defineFlow([start, ...blocks, end])`,
+  run with `flow.run(mem)` (Engine launches its own browser) or `flow.run(context, mem)`
+  (reuse an existing `@playwright/test` `context` fixture).
+
+## Quick start
+
+```typescript
+import { Engine, start, end, MemPage, key, checkpoint, Trait } from "waygraph";
+import type { Block, Checkpoint, Start } from "waygraph";
+
+type LoggedIn = Checkpoint<"LoggedIn">;
+
+const Username = key<string>("username");
+
+const Login: Block<Start, LoggedIn> = {
+  name: "login",
+  instruction: {
+    async act(page, _input, mem) {
+      await page.goto("https://example.com/login");
+      await page.getByLabel("Username").fill(mem.get(Username));
+      await page.getByRole("button", { name: "Sign in" }).click();
+    },
+    resolve: () => checkpoint("LoggedIn"),
+    verify: [Trait.url({ pathname: "/dashboard" })],
+  },
+};
+
+const mem = new MemPage();
+mem.set(Username, "alice");
+
+const flow = new Engine().defineFlow([start, Login, end]);
+const result = await flow.run(mem); // Engine launches its own browser
+// result === { __state: "LoggedIn" }
+```
+
+Inside an existing `@playwright/test` file, reuse its `context` fixture instead of having
+the Engine launch its own browser: `await flow.run(context, mem)`.
+
+See `tests/define-flow.spec.ts` here, and
+`examples/saucedemo/tests/checkout-flow.spec.ts` (a real multi-Block flow against live
+saucedemo.com), for this running for real. The lower-level `connect()`/`runGraph()` still
+exist and are what `defineFlow` builds on - reach for them directly only if you need a
+shape `defineFlow`'s array can't express yet.
+
+## Engine features
+
+A Block's output type is the only contract the next Block can rely on. `resolve` is
+structurally incapable of touching the browser or shared memory. `verify` runs only after
+`resolve` has already decided (confirms or fails loud, never redirects).
+
+### Routing and composition
+
+- **`branch()`** attaches routing to a Block - including back to itself (self-loops) -
+  without ever touching that Block's own phases. A `maxSteps` safety cap keeps a routing
+  bug from hanging a run forever.
+- **`withVerify(block, verify)`** decorates any existing Block with different
+  confirmation, same `act`/`resolve`, same routing - without that Block needing to have
+  been authored as a parameterized factory (`withVerify(LoginBlock, [])` is the "I only
+  care that I navigated this far, no DOM check" case).
+- **`flow.withBlockVerify` / `flow.modBlockVerify`** patch one Block's verify from
+  outside a finished `Flow` - addressed by the Block reference (preferred), its name, or
+  its numeric position - without editing the flow's own file.
+- **`composeBlock(name, steps)`** chains several Blocks into one named unit, the same way
+  `connect()` already does - useful for a multi-step form that's naturally "one feature"
+  but still wants each step's own real `verify` independently overridable, not one giant
+  Block with no per-step confirmation. `composedBlock.withStepVerify` / `modStepVerify`
+  patch one step from outside, addressed the same three ways as `withBlockVerify`. A
+  `composeBlock` result is a plain Block, so it drops straight into
+  `defineFlow([start, ..., composed, ..., end])` like any other.
+- **`fastForwardComposeBlock(name, steps)`** is the same shape marked for wall-clock
+  **fast-forward**: one opaque demo step that blitzes (no per-inner gate, no smooth cursor
+  theater, Playwright `slowMo` off for that flow unless `WAYGRAPH_SLOWMO` is set) unless
+  expanded. Put several FF units in one Flow to race past auth, then a heavy dashboard
+  settle, then watch the interesting middle. `waygraph demo --ff-disabled` (alias
+  `--no-ff`) expands every FFCompose into its inner Blocks so a broken step is visible as
+  its own panel row; former FF inners keep blitz pacing so wall-clock stays comparable.
+  `--ff-expand` is the older expand-only flag (same flatten).
+
+### Traits beyond the page
+
+A hand-written `Trait`'s `check(page, mem)` receives `mem` too, for the same-Checkpoint
+case: an action that doesn't navigate at all (clicking "+" to bump a cart item's quantity,
+say) has `In === Out`, which `defineBlock`/`defineFlow` already accept with no
+special-casing - `act()` updates `mem` alongside the real click, and a bespoke `verify`
+Trait confirms the page's own displayed value actually matches what `mem` now expects, not
+just that *some* number is showing. `resolve()` itself stays exactly as pure as ever - it
+never sees `mem`, only `verify` does.
+
+`Trait.url` takes a structured `URLPatternInit` (`{ pathname, hostname, search, hash, ... }`,
+the same shape the standard `URLPattern` Web API takes), not a hand-written regex -
+whichever components you leave out default to "match anything," so
+`Trait.url({ pathname: "/inventory.html" })` already ignores whatever query params a
+hybrid SPA tacks on, with no separate flag needed for that.
+
+### `precondition` - confirming the page is *still* there
+
+`verify` only ever confirms what a Block itself just did - nothing previously checked
+whether the page was still there by the time the next Block's `act()` starts. A
+`precondition` (same `Trait[]` / `(input) => Trait[]` shape as `verify`, checked
+automatically by `connect()`/`runGraph` right before `act()` runs, never called directly)
+closes that gap: a session timeout, a redirect, an interstitial popup - anything that
+changes the page in the moment between one Block finishing and the next one starting -
+fails loud with a clear "trait X failed before Y," instead of a confusing error deep
+inside `act()` trying to click something that's no longer there.
+
+### `requires` and `preflight()`
+
+A Block's `requires: MemKey[]` gets checked by `preflight()` (built into `runGraph`)
+before a tab even opens - a missing credential fails in milliseconds, not after several
+real browser actions already ran.
+
+### Engine config and pluggable browsers
+
+`new Engine({ headless, browserName, slowMo })` configures a browser the Engine launches
+and owns itself: `flow.run(mem)` (no context) uses it, and
+`flow.run(mem, { ...overrides })` overrides it per call - so one module-level `Flow`,
+imported by many specs, doesn't force every caller into the same settings.
+`flow.run(context, mem)` still works exactly as before and ignores all of this, since that
+context is already launched.
+
+`new Engine({ browsers: { chromium, firefox, webkit } })` overrides which `BrowserType`
+actually launches for a `mem`-only run, per browser name - waygraph is deliberately "just
+an opinionated Playwright," so a stealth-patched or otherwise customized launcher (e.g.
+`playwright-extra` plus a stealth plugin) drops in unmodified, since those already expose
+the same `.launch()` shape as Playwright's own `chromium`/`firefox`/`webkit`.
+
+### Driving an existing page / tabs
+
+`spawnTab(entry, page, mem)` drives a genuinely separate second tab through its own
+Block/Flow, in the same browser context an existing `page` already belongs to - the
+pattern `observe()` could already reach for (it's the only phase allowed to touch
+`page.context()`), now a named, discoverable, tested primitive.
+
+`flow.run(context, mem, options)` also accepts a trailing optional options object -
+additively, so `flow.run(context, mem)` still behaves byte-for-byte as before:
+`options.page` drives that already-open page instead of opening a fresh tab (the run
+won't close a page you handed it unless you say so), and `options.closeOnFinish: false`
+leaves the run's page open and returns `{ result, page }` so the caller can keep driving
+it. See [Recipes](#recipes) for the surviving-tab and popup-capture patterns.
+
+### NavBlock / ActionPage / waygraph check
+
+`defineNavBlock({ name, checkpoint, url })` or
+`defineNavClickBlock({ name, checkpoint, click })` builds a Block whose only possible
+action is navigating. Prefer `defineNavClickBlock` for click-nav in app code;
+`defineNavBlock` for `url` / `goto` deep links. Both accept a plain string or
+`(mem) => string` / `(mem) => selector`. Generated `act()` is always exactly
+`page.goto(url)` or `page.locator(click).click()`. For screen hubs that also register
+methods, prefer `definePageBlock` (see [Block helpers](#block-helpers-page-method-sel)
+below).
+
+A regular `defineBlock` / `defineMethodBlock`'s `act()` receives `page` typed as
+`ActionPage` - `goto`/`reload`/`goBack`/`goForward` are `@deprecated` there (editor
+strike-through pointing at Nav/Page helpers). This is a soft, TypeScript-only signal:
+nothing is blocked, nothing fails to build. `waygraph check [project]` is the
+complementary whole-project sweep for contexts with no editor watching (CI, generated
+code, an autonomous agent authoring Blocks) - it warns, never fails the process.
+
+### Demo narration
 
-## 0.9.0 — Page, Method, Sel
+Automation rings are gray; authored stubs/slides can use
+`tone: "info" | "warning" | "danger" | "success"` (iconified captions), plus
+`size: "sm" | "md" | "lg"` and `weight: "normal" | "bold"`. Flow episode defaults:
+`withHighlightStyle(flow, { size, weight, tone? })` (slot/fixture wins). Episode pacing:
+`withDemoPace(flow, "fast" | "slow" | "normal" | "blitz" | number)` or
+`withBlockPace(block, ...)` (`number <= 20` = scale vs normal, e.g. `0.5` / `2`; `> 20` =
+absolute ms, e.g. `4500`). FFCompose stays blitz. Living objectives:
+`docs/proposals/OBJECTIVES.md`.
+
+### Graph traversal
+
+`waygraph traverse` walks the Block graph. `--parallel N` (default `--session clone`)
+bootstraps one context, forks N workers with `storageState` + mem snapshot, partitions
+edges by hash, and claims via in-process edge leases (audit trail under
+`.waygraph-traverse/`). `--session inherit` is refused when `parallel > 1`. It writes
+`.waygraph-traverse/coverage.json` and prints `[Coverage edges=H/T ratio=R%...]`;
+`--min-edge-coverage 80%` fails the suite with exit 2 when the ratio is below the gate
+(even if every worker leaf-PASSed). `--coverage-out PATH` / `--no-coverage-report` adjust
+the JSON. See `docs/proposals/traverse-ffcompose-rfc.md`.
+
+### Not yet implemented
+
+Tracked on the project board / roadmap, not in this package today:
+
+- Interstitials/Watchers - background overlay handling (cookie banners, popups).
+- Split `requires` (externally-supplied vs producedBy) recovery hints.
+- Federated multi-package pool of waygraphs.
+
+## Block helpers (Page, Method, Sel)
 
 Runtime is still one type: `Block`. Helpers are TypeScript salt.
 
 | Helper | Role | Typical file |
 |--------|------|----------------|
 | `definePageBlock` | Screen hub (checkpoint + `verify` + registered methods) | `*.page.block.ts` |
-| `defineMethodBlock` | One-shot non-nav step (submit, upload, logout) | `methods/*.method.block.ts` |
+| `defineMethodBlock` | One-shot non-nav step, exactly one action (submit, upload, logout) | `methods/*.method.block.ts` |
+| `defineAssertBlock` | Self-loop-only assertion (no state change) - `verify` only | `methods/*.method.block.ts` |
 | `defineEffectBlock` | Instance mutate + `instanceOptions` auto menu | `methods/*.effect.block.ts` |
 | `defineNavBlock` / `defineNavClickBlock` | `goto` / click-nav | `nav-*.block.ts` |
 | `defineMemNavBlock` | Nav + per-row `instanceOptions` | `nav-*.block.ts` |
-| `defineActionBlock` | **Deprecated** alias of `defineMethodBlock` | — |
+| `defineActionBlock` | Deprecated alias of `defineMethodBlock` | - |
 
 **Page hub:** one Checkpoint = this screen. Methods hang off the page for readability /
 auto grouping. Arrival-only hubs omit `url`/`click` (previous Block already landed here).
 Deep-link hubs pass `url` or `click` like a Nav.
 
-**`methods/` folder** (was `actions/`): on-page work lives next to the route, not free-floating.
+**One distinct action per Block - hard rule.** A Method that fills form fields *and*
+submits, or that drives several steps inside one `act()`, is wrong even if it "works" -
+split it into atomic Blocks (a login form is `fill-username` + `fill-password` +
+`submit-login`, never one Block doing all three; see `examples/saucedemo`'s own
+`saucedemo-web/methods/` for the real split). A Block that only asserts something on the
+current page, with no state change, is `defineAssertBlock({ name, checkpoint, verify,
+waitForHeading?, requires? })` - self-loop and `resolve` are generated for you, so there's no
+hand-written `act`/`resolve` to accidentally make do two things. It also accepts
+`stubBefore`/`stubAfter`/`stubOnError`/`slides`, the same narration fields every other
+Block helper takes, so converting a hand-written assertion Method loses no demo/highlight
+fixture data. `requires` (declare it whenever a mem-aware Trait reads a mem key the caller
+must supply externally - see the mail example below) lets preflight catch a missing input
+before the flow ever runs, the same as every other Block helper:
+
+```typescript
+export const AssertInventoryHeaderBlock = defineAssertBlock({
+  name: "assert-inventory-header",
+  checkpoint: "LoggedIn",
+  waitForHeading: "Products",
+  verify: [Trait.visible(InventorySel.list)],
+});
+```
 
-**`*Sel`:** DOM selectors only (static strings + `(id) => …` for item-no-1 style). Mem keys
-store values (which item / upload queue), not selectors. `instanceOptions` scrapes the live
-DOM into menu rows and `mem.set`s on pick; predefined methods seed mem from the flow instead.
+`waygraph check` warns when a `verify` array inlines a literal selector string
+(`Trait.visible("#some-id")`) instead of referencing a `*Sel` object - the exact pattern
+`defineAssertBlock` exists to make easy to avoid.
+
+**Give `defineAssertBlock` an explicit type argument when it sits mid-chain.** Without one,
+`Out` defaults to wildcard `Checkpoint<string>` on both sides - harmless when the assert is
+the last real Block before `end` (nothing downstream needs it narrower), but a `defineFlow`
+array's tuple typing breaks once a wildcard Block is sandwiched between two
+specifically-typed ones. Write `defineAssertBlock<LoggedIn>({ ..., checkpoint: "LoggedIn",
+... })` any time the assert has a real Block after it, not just before.
+
+**An assert Block can check the *result* of an action, not just static page state.** Since
+`Trait.check(page, mem)` receives mem as well as the page, an assert placed right after a
+Method/Effect can confirm what that specific action actually did - not a duplicate of that
+Block's own inline `verify`, a genuinely separate, nameable QA checkpoint:
+
+```typescript
+const removeButtonVisibleForSelectedItem: Trait = {
+  name: "remove-button-visible-for-selected-item",
+  async check(page, mem) {
+    const { id } = mem.get(SelectedItem.key); // what add-item just acted on
+    return page.locator(RemoveBtnSel(id)).isVisible();
+  },
+};
+
+export const AssertItemAddedBlock = defineAssertBlock<ItemInCart>({
+  name: "assert-item-added",
+  checkpoint: "ItemInCart",
+  verify: [removeButtonVisibleForSelectedItem, Trait.text(CartCountSel, "1")],
+});
+
+// wired right after the action it checks:
+engine.defineFlow([start, NavHomeBlock, AddItemBlock, AssertItemAddedBlock, ClearCartBlock, end])
+```
+
+Live reference: `templates/scaffold/src/blocks/demo-web/methods/assert-item-added.method.block.ts`,
+wired into `shop.flow.ts`.
+
+**`methods/` folder:** on-page work lives next to the route, not free-floating.
+
+**`*Sel`:** DOM selectors only (static strings + `(id) => ...` for item-no-1 style). Mem
+keys store values (which item / upload queue), not selectors. `instanceOptions` scrapes the
+live DOM into menu rows and `mem.set`s on pick; predefined methods seed mem from the flow
+instead.
 
 ```typescript
 import { definePageBlock, Trait } from "waygraph";
@@ -80,240 +360,539 @@ export const InventoryPage = definePageBlock({
 
 Live reference: `examples/saucedemo/src/blocks/saucedemo-web/inventory/`
 (`inventory.page.block.ts` + `methods/` + `InventorySel`). Bulk `add-all-to-cart` /
-`remove-all-from-cart` are one menu row each (`from: "*"` — works after leave/return).
+`remove-all-from-cart` are one menu row each (`from: "*"` - works after leave/return).
 
+## Mail adapters (cross-origin, browser-driven)
 
-## Getting started (pick one)
+For flows driven by an email (signup confirmation, password reset, a magic link), the
+convention is **not** a REST/HTTP client to the mail catcher - it's more Blocks, pointed at
+the catcher's own web UI (MailHog, MailDev, Mailpit all ship one) as a real, separate,
+cross-origin page. This needs zero new engine surface: a `NavBlock` navigates there like any
+other page, `MethodBlock`s read the DOM with ordinary `page.locator`/`page.frameLocator`
+calls, and a final `NavBlock` carries the extracted link back into the app under test.
+Convergent, real-world evidence for this exact shape: independently, more than one real
+consumer project settled on it rather than a REST client.
 
-| Goal | Command |
-|------|---------|
-| Watch Sauce Demo step-through (temp dir only) | `npx waygraph try demo` |
-| Interactive explore (Add/Remove/Open details from live page) | `cd examples/saucedemo && npm i && npx waygraph auto` |
-| Scaffold a new **offline** project (green `npm test` on local fixture `:4177`) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
-| Install coding-agent defs for diving an app into Blocks | `npx waygraph agent-dive --loop claude` (also `opencode` / `cursor` / `vscode`) |
-| Add waygraph to an existing repo | `npm install waygraph @playwright/test` |
+**Keep it in its own `*-external/<tool>/` folder, never mixed into your app's own Blocks** -
+it's a different origin, driving a different site:
 
-**Scaffold is not hidden inside waygraph alone** - the offline starter also ships as
-[`create-waygraph`](https://github.com/deviate-dv8/create-waygraph) on npm (same template as
-`waygraph init` since 0.7.5). Use whichever entry you already have: `npx create-waygraph my-app`
-when reading the GitHub Pages docs, or `npx waygraph init my-app` when the CLI is already
-installed. After either:
+```typescript
+// demo-external/mailpit/nav-mailpit-inbox.block.ts
+export const NavMailpitInboxBlock = defineNavBlock<MailpitInbox>({
+  name: "nav-mailpit-inbox",
+  checkpoint: "MailpitInbox",
+  url: () => process.env.WAYGRAPH_MAIL_URL ?? "http://127.0.0.1:8025",
+  verify: [Trait.url({ pathname: "/" })],
+});
 
-```bash
-cd my-app && npm install && npx playwright install chromium && npm test
-```
+// demo-external/mailpit/methods/open-message.method.block.ts
+export const OpenMessageBlock = defineMethodBlock<MailpitInbox, MailpitMessageOpen>({
+  name: "open-message",
+  requires: [ExpectedRecipient.key], // externally supplied - avoids picking the wrong inbox row
+  instruction: {
+    async act(page, _in, mem) {
+      const { email } = mem.get(ExpectedRecipient.key);
+      await page.locator(MailpitSel.messageRow, { hasText: email }).first().click();
+      await page.waitForURL(/\/view\//);
+    },
+    resolve: () => checkpoint("MailpitMessageOpen"),
+  },
+});
 
-`try demo` is different: live saucedemo.com, step-through **Sign In → Shop & Checkout →
-blocked Viewer login**, then headless tests. Permanent full example:
-[`examples/saucedemo`](./examples/saucedemo). Offline empty scaffold: `init` /
-`create-waygraph`.
+// demo-external/mailpit/methods/extract-email-link.method.block.ts
+// Named for what it does, not for one scenario - see "reusable across
+// scenarios" below for why.
+export const ExtractEmailLinkBlock = defineMethodBlock<MailpitMessageOpen, MailpitMessageOpen>({
+  name: "extract-email-link",
+  requires: [ExpectedLinkPattern], // which link in the body to follow - externally supplied
+  instruction: {
+    async act(page, _in, mem) {
+      const pattern = mem.get(ExpectedLinkPattern);
+      const link = page.frameLocator(MailpitSel.previewIframe).locator(`a[href*="${pattern}"]`).first();
+      const href = await link.getAttribute("href");
+      if (!href) throw new Error(`no link matching "${pattern}" found`);
+      mem.set(EmailLink({ url: href }));
+    },
+    resolve: () => checkpoint("MailpitMessageOpen"),
+  },
+});
 
-```bash
-# From this checkout, after npm run build:
-cd examples/saucedemo && npm install && npx playwright install chromium
-npm test                  # live Playwright suite
-npm run auto              # headed interactive explore
-npm run demo:step         # stepper (manual Next)
-npm run demo:autoplay     # stepper with Auto-advance
+// demo-web/nav-verification-link.block.ts - back into the app, no `requires` (see below)
+export const NavVerificationLinkBlock = defineNavBlock<HomeVerified>({
+  name: "nav-verification-link",
+  checkpoint: "HomeVerified",
+  url: (mem) => mem.get(EmailLink.key).url,
+  verify: [Trait.visible(DemoSel.verifiedBanner)],
+});
 ```
 
+Four atomic Blocks, each doing exactly one thing - `open-message` and `extract-email-link`
+stay separate Methods for the same reason `fill-username`/`submit-login` do in the Sauce
+Demo example: reading the link and navigating to it are two distinct actions, so they are
+two distinct Blocks (`nav-verification-link` does the actual navigation).
 
-## Install
+Note `nav-verification-link` deliberately does **not** declare `requires: [EmailLink.key]` -
+`requires` means "the caller must seed this externally before the flow starts" (preflight
+checks a whole chain's requires up front), and this key is instead produced by
+`extract-email-link` earlier in the very same chain. Declaring it as a requirement would make
+preflight reject the run before it ever gets a chance to produce it - `requires` is only for
+keys a caller truly must supply from outside the chain (like `ExpectedRecipient` above).
 
-```bash
-npm install waygraph @playwright/test
-```
+Live reference, proven end to end against a real, throwaway Mailpit container:
+`templates/scaffold/src/blocks/demo-external/mailpit/` + `src/flows/mail-verify.flow.ts` +
+`tests/mail-verify.spec.ts`.
 
-`@playwright/test` is a peer dependency, not bundled - you bring your own version (`^1.40.0`
-or later) since it's also what drives the rest of your test suite. Requires Node 22+ (uses
-`URL`/`URLPattern` from `@types/node` for `Trait.url`'s type checking).
+### Reusable across scenarios: mem-driven, not one Block per email
 
-## Quick start
+The natural instinct once you have a signup-verification flow is to want a matching set of
+Blocks for password reset, then another for a magic link, and so on - N scenarios, N Block
+sets. That's the wrong axis to scale on. `open-message`, `extract-email-link`, and the two
+assert Blocks below are already scenario-agnostic: **only mem varies per run, never the
+Blocks**:
 
-A Block wraps one `act`/`resolve` step (add `observe`/`verify` once you need them); a `Flow`
-chains several into a run:
+| Mem key | Answers |
+|---|---|
+| `ExpectedRecipient` | Which inbox row to open |
+| `ExpectedLinkPattern` | Which link in the body to follow (a real email often has more than one - "report abuse" and the real link both present) |
+| `ExpectedEmailContent` | What the body is supposed to say |
+
+The same four Blocks (`assert-email-received`, `open-message`, `assert-email-content`,
+`extract-email-link`) run a signup-verification check and a password-reset check identically
+- just with different mem, in `templates/scaffold/tests/mail-verify.spec.ts`:
 
 ```typescript
-import { Engine, start, end, MemPage, key, checkpoint, Trait } from "waygraph";
-import type { Block, Checkpoint, Start } from "waygraph";
+mem.set(ExpectedRecipient({ email: "demo-user@example.com" }));
+mem.set(ExpectedLinkPattern, "verified=1");
+mem.set(ExpectedEmailContent, "Please confirm your email address...");
+await mailVerifyFlow.run(context, mem); // signup verification
+
+mem.set(ExpectedRecipient({ email: "password-reset-user@example.com" }));
+mem.set(ExpectedLinkPattern, "verified=1"); // picks the real link, not the "report abuse" decoy also in the body
+mem.set(ExpectedEmailContent, "We received a request to reset your password.");
+await mailVerifyFlow.run(context, mem); // same flow, same Blocks, different email entirely
+```
 
-type LoggedIn = Checkpoint<"LoggedIn">;
+Naming matters here: a Block named `extract-verification-link` would wrongly imply it only
+ever handles verification emails - once a Block's behavior is mem-driven, its name should
+describe the mechanism (`extract-email-link`), not one scenario that happens to use it.
 
-const Username = key<string>("username");
+A **mail-provider page hub** ties it together, the same `definePageBlock` pattern used
+everywhere else - one page, several reusable methods, each pulling its specifics from mem:
 
-const Login: Block<Start, LoggedIn> = {
-  name: "login",
-  instruction: {
-    async act(page, _input, mem) {
-      await page.goto("https://example.com/login");
-      await page.getByLabel("Username").fill(mem.get(Username));
-      await page.getByRole("button", { name: "Sign in" }).click();
-    },
-    resolve: () => checkpoint("LoggedIn"),
-    verify: [Trait.url({ pathname: "/dashboard" })],
+```typescript
+export const MailpitInboxPageBlock = definePageBlock<MailpitInbox>({
+  name: "page-mailpit-inbox",
+  checkpoint: "MailpitInbox",
+  verify: [Trait.url({ pathname: "/" })],
+  methods: {
+    assertEmailReceived: () => AssertEmailReceivedBlock,
+    openMessage: () => OpenMessageBlock,
+    assertEmailContent: () => AssertEmailContentBlock,
+    extractEmailLink: () => ExtractEmailLinkBlock,
+  },
+});
+```
+
+### QA-rich: does the email exist, and does it say the right thing
+
+Two more assert Blocks slot into the same chain, both mem-driven, both proven to fail loud
+(not silently pass) on a real negative case - no email arrived, and an email arrived with
+the wrong copy:
+
+```typescript
+// "Did the email even arrive" - doesn't open/consume it, safe to check before deciding to.
+// A mem-aware Trait: the selector depends on the expected recipient, so it
+// can't be a static Trait.visible(...) string - check(page, mem) already gets mem.
+const emailReceived: Trait = {
+  name: "email-received",
+  async check(page, mem) {
+    const { email } = mem.get(ExpectedRecipient.key);
+    try {
+      await page.locator(MailpitSel.messageRow, { hasText: email }).first().waitFor({
+        state: "visible",
+        timeout: 10_000,
+      });
+      return true;
+    } catch {
+      return false;
+    }
   },
 };
+export const AssertEmailReceivedBlock = defineAssertBlock<MailpitInbox>({
+  name: "assert-email-received",
+  checkpoint: "MailpitInbox",
+  requires: [ExpectedRecipient.key],
+  verify: [emailReceived],
+});
 
-const mem = new MemPage();
-mem.set(Username, "alice");
+// "Does the email say what it's supposed to" - reads the body content, not
+// just whether a link exists. The expected text comes from mem too (same
+// reuse reasoning as above) via another bespoke mem-aware Trait, since
+// Trait.frameContains's own factory bakes its expected string in at
+// Block-definition time, not runtime.
+const bodyContainsExpectedText: Trait = {
+  name: "body-contains-expected-text",
+  async check(page, mem) {
+    const expected = mem.get(ExpectedEmailContent);
+    const text = await page.frameLocator(MailpitSel.previewIframe).locator("body").textContent();
+    return (text ?? "").includes(expected);
+  },
+};
+export const AssertEmailContentBlock = defineAssertBlock<MailpitMessageOpen>({
+  name: "assert-email-content",
+  checkpoint: "MailpitMessageOpen",
+  requires: [ExpectedEmailContent],
+  verify: [bodyContainsExpectedText],
+});
+```
 
-const flow = new Engine().defineFlow([start, Login, end]);
-const result = await flow.run(mem); // Engine launches its own browser
-// result === { __state: "LoggedIn" }
+`Trait.frameVisible(frameSelector, innerSelector)` / `Trait.frameText(frameSelector,
+innerSelector, expected)` (exact match) / `Trait.frameContains(frameSelector, innerSelector,
+expected)` (substring match, for a *fixed* known expected string) mirror
+`Trait.visible`/`Trait.text` exactly, scoped to a frame - reusable for any iframe content,
+not just mail; reach for a bespoke mem-aware Trait instead when the expected value itself
+needs to vary per run, as both examples above do. Wired into the chain right where they
+belong:
+
+```typescript
+engine.defineFlow([
+  start, NavMailpitInboxBlock, AssertEmailReceivedBlock, OpenMessageBlock,
+  AssertEmailContentBlock, ExtractEmailLinkBlock, NavVerificationLinkBlock, end,
+])
 ```
 
-Inside an existing `@playwright/test` file, reuse its `context` fixture instead of having the
-Engine launch its own browser: `await flow.run(context, mem)`.
-
-**Status:** `Checkpoint`, `MemPage`, `Instruction`/`Block` (`act`/`observe`/`resolve`/`verify`),
-`connect()`, `Trait`, `Engine.defineFlow([start, ...blocks, end])`, and `branch()`/self-loops
-with a `maxSteps` safety cap. A Block's output type is the only contract the next Block can
-rely on, `resolve` is structurally incapable of touching the browser or shared memory,
-`verify` runs only after `resolve` has already decided (confirms or fails loud, never
-redirects), `branch()` attaches routing to a Block - including back to itself - without ever
-touching that Block's own phases, a Block's `requires: MemKey[]` gets checked by
-`preflight()` (built into `runGraph`) before a tab even opens - a missing credential fails
-in milliseconds, not after several real browser actions already ran - and `new Engine({ headless, browserName, slowMo })` configures a browser the Engine
-launches and owns itself: `flow.run(mem)` (no context) uses it, and `flow.run(mem, {
-...overrides })` overrides it per call - so one module-level `Flow`, imported by many
-specs, doesn't force every caller into the same settings. `flow.run(context, mem)` still
-works exactly as before and ignores all of this, since that context is already launched.
-`withVerify(block, verify)` decorates any existing Block with different confirmation - same
-`act`/`resolve`, same routing - without that Block needing to have been authored as a
-parameterized factory (`withVerify(LoginBlock, [])` is the "I only care that I navigated
-this far, no DOM check" case). Built-in Trait factories are reachable two ways - as free
-functions (`urlMatches`, `textEquals`, `visible`) or, for autocomplete discoverability,
-off `Trait.` itself (`Trait.url`, `Trait.text`, `Trait.visible` - the exact same functions,
-just findable by typing `Trait.` without needing to already know their names). `Trait.url`
-takes a structured `URLPatternInit` (`{ pathname, hostname, search, hash, ... }`, the same
-shape the standard `URLPattern` Web API takes), not a hand-written regex - whichever
-components you leave out default to "match anything," so `Trait.url({ pathname:
-"/inventory.html" })` already ignores whatever query params a hybrid SPA tacks on, with no
-separate flag needed for that. A hand-written `Trait` isn't limited to the page, either - its
-`check(page, mem)` receives `mem` too, for the same-Checkpoint case: an action that doesn't
-navigate anywhere at all (clicking "+" to bump a cart item's quantity, say) has `In === Out`,
-which `defineBlock`/`defineFlow` already accept with no special-casing - `act()` updates `mem`
-alongside the real click (`mem.set(Quantity, mem.get(Quantity) + 1)`), and a bespoke `verify`
-Trait confirms the page's own displayed value actually matches what `mem` now expects
-(`shown === String(mem.get(Quantity))`), not just that *some* number is showing. `resolve()`
-itself stays exactly as pure as ever - it never sees `mem`, only `verify` does. `verify` only
-ever confirms what a Block itself just did, though - nothing previously checked whether the
-page was STILL there by the time the NEXT Block's `act()` starts. A `precondition` (same
-`Trait[]`/`(input) => Trait[]` shape as `verify`, checked automatically by `connect()`/
-`runGraph` right before `act()` runs, never called directly) closes that gap: a session
-timeout, a redirect, an interstitial popup - anything that changes the page in the moment
-between one Block finishing and the next one starting - fails loud with a clear "trait X
-failed before Y," instead of a confusing error deep inside `act()` trying to click something
-that's no longer there. Once Blocks are composed into a `Flow`, `flow.withBlockVerify`/
-`flow.modBlockVerify` patch one Block's verify from outside - a spec that only imports the
-finished flow, addressed by the Block reference (preferred), its name, or its numeric
-position in the flow - without editing the flow's own file. `composeBlock(name, steps)`
-chains several Blocks into one named unit the same way `connect()` already does - the
-multi-step-form case (a government form with several stepper pages, say), which is
-naturally "one feature" but still wants each step's own real `verify` independently
-overridable, not one giant Block with no per-step confirmation. `composedBlock.withStepVerify`/
-`modStepVerify` patch one step from outside, addressed the same three ways
-`withBlockVerify`/`modBlockVerify` already are - a `composeBlock` result is a plain Block,
-so it drops straight into `defineFlow([start, ..., composed, ..., end])` like any other.
-`fastForwardComposeBlock(name, steps)` is the same shape marked for **wall-clock
-fast-forward**: one opaque demo step that **blitzes** (no per-inner gate, no smooth
-cursor theater, Playwright slowMo off for that flow unless `WAYGRAPH_SLOWMO` is set)
-unless expanded. Put **several** FF units in one Flow when you need to race past auth,
-then a heavy dashboard settle, then watch the interesting middle.
-
-**Dispute / disable FF:** `waygraph demo --ff-disabled` (alias `--no-ff`) expands every
-FFCompose into its inner Blocks so a broken login step is visible as its own panel row.
-Former FF inners keep blitz pacing so wall-clock stays comparable to opaque FF (same
-real acts). `--ff-expand` is the older expand-only flag (same flatten). Saucedemo
-`checkoutFlow` uses `ff-owner-auth` for the login prefix; `loginFlow` stays expanded for
-Sign In narration.
-
-`waygraph traverse` walks the Block graph (Phase B-E). `--parallel N` (default
-`--session clone`) bootstraps one context, forks N workers with `storageState` + mem
-snapshot, partitions edges by hash, and claims via in-process edge leases (audit under
-`.waygraph-traverse/`). `--session inherit` is refused when `parallel > 1`. Phase E
-writes `.waygraph-traverse/coverage.json` and prints `[Coverage edges=H/T ratio=R%...]`;
-`--min-edge-coverage 80%` fails the suite with exit 2 when the ratio is below the gate
-(even if every worker leaf-PASSed). `--coverage-out PATH` / `--no-coverage-report` adjust
-the JSON. See `docs/proposals/traverse-ffcompose-rfc.md`.
+### Where this shows up in `waygraph auto`
+
+A `NavBlock` always has wildcard `In` (`from: "*"` in the static graph), so it's reasonable to
+wonder whether `nav-mailpit-inbox` clutters the live picker on every single screen. It
+doesn't - `waygraph auto`'s menu builder already special-cases exactly this
+(`src/auto-explore.ts`, `buildExploreMenu`): a URL-based Nav is excluded from the interactive
+menu once you're on a known screen, offered only as a "Start here" bootstrap option. The
+static graph still keeps the `from: "*"` edge for `waygraph graph`/`findBlockPath`/`traverse`,
+so `waygraph auto --blocks "<AppCheckpoint> MailpitInbox"` can still route there deliberately -
+it's just never suggested unprompted. The tested, recommended way to actually use this is an
+authored flow/chain (`someAppFlow then mailVerifyFlow`), exactly like `mailVerifyFlow` itself.
+
+## Waygraph Pilot
+
+Bootstraps a real, persistent, inspectable browser session for an **agent** to discover and
+drive toward a natural-language goal it plans itself - not a tool that resolves one ask to one
+Block internally. A real request is a multi-step task ("log in and buy the backpack for me",
+"make a signature draft request") that needs an agent reasoning over a sequence of Blocks, not
+a single best-matching edge. Comparable in shape to a browser-use-style agent, but the action
+space is constrained to this project's own pre-verified Blocks (each with a real resolve/verify
+already checked) instead of freeform DOM/pixel guessing - narrower, but far more accurate and
+deterministic.
 
-**Richer demo narration:** automation rings are **gray**; authored stubs/slides can use
-`tone: "info" | "warning" | "danger" | "success"` (iconified captions), plus
-`size: "sm" | "md" | "lg"` and `weight: "normal" | "bold"`. Flow episode defaults:
-`withHighlightStyle(flow, { size, weight, tone? })` (slot/fixture wins). Episode pacing:
-`withDemoPace(flow, "fast" | "slow" | "normal" | "blitz" | number)` or `withBlockPace(block, ...)`
-(`number` `<=20` = scale vs normal, e.g. `0.5` / `2`; `>20` = absolute ms, e.g. `4500`).
-FFCompose stays blitz. Living objectives: `docs/proposals/OBJECTIVES.md`.
-`spawnTab(entry, page, mem)` drives a genuinely separate second tab through its own
-Block/Flow, in the same browser context an existing `page` already belongs to - the
-pattern `observe()` could already reach for (it's the only phase allowed to touch
-`page.context()`), now a named, discoverable, tested primitive instead of something
-you'd have to already know to hand-roll. `flow.run(context, mem, options)` also accepts a
-trailing optional options object - additively, so `flow.run(context, mem)` still behaves
-byte-for-byte as before: `options.page` drives that already-open page instead of opening
-a fresh tab (the run won't close a page you handed it unless you say so), and
-`options.closeOnFinish: false` leaves the run's page open and returns `{ result, page }`
-so the caller can keep driving it - hands a run tab back instead of losing it. See
-"Recipes" for capture-on-popup, which stays a documented pattern until a second real use
-case promotes it to an engine API.
-`defineNavBlock({ name, checkpoint, url })` or `defineNavClickBlock({ name, checkpoint, click })`
-builds a Block whose only possible action is navigating. Prefer `defineNavClickBlock` for
-click-nav in app code; `defineNavBlock` for `url` / `goto` deep links. Both accept a plain
-string or `(mem) => string` / `(mem) => selector`. Generated `act()` is always exactly
-`page.goto(url)` or `page.locator(click).click()`. For screen hubs that also register
-methods, prefer `definePageBlock` (see **0.9.0 — Page, Method, Sel** above). A regular
-`defineBlock` / `defineMethodBlock`'s `act()` receives `page` typed as `ActionPage` —
-`goto`/`reload`/`goBack`/`goForward` are `@deprecated` there (editor strike-through pointing
-at Nav/Page helpers). `waygraph check [project]` is the complementary whole-project sweep
-for contexts with no editor watching (CI, generated code).
-`new Engine({ browsers: { chromium, firefox, webkit } })` overrides which `BrowserType`
-actually launches for a `mem`-only run, per browser name - waygraph is deliberately "just
-an opinionated Playwright," so a stealth-patched or otherwise customized launcher (e.g.
-`playwright-extra` plus a stealth plugin) drops in unmodified, since those already expose
-the same `.launch()` shape as Playwright's own `chromium`/`firefox`/`webkit`.
+```bash
+waygraph pilot start --non-headless
+# {"sessionId":"bb65d74c","socketPath":"...","headless":false,"graph":{...},"snapshot":{...}}
+```
 
-See **Getting started** above for `try demo`, `create-waygraph`, and `waygraph init`.
-Both scaffold commands emit the same offline tree (route-shaped `demo-web/` +
-`methods/`, stubs, fixtures, one YAP slide). Layout:
-[`docs/scaffold.html`](./docs/scaffold.html) · `templates/scaffold/STRUCTURE.md`.
+One call gives an agent everything it needs to start: a real, already-running Playwright
+session (the exact mechanism `auto --cli --detach` already provides), and the whole project's
+Block graph (`graph` - every Checkpoint/edge/description, not just what's reachable from the
+current position, so the agent can plan several steps ahead). From there, the agent drives the
+session itself, one pick at a time, using the session-control commands that already existed
+before Pilot did:
 
-**Consumer layout (Next.js App Router):** block folders mirror `app/` page routes (`/`
-at the namespace root; no invented `landing/`/`root/`; sidebar = chrome + edges). See
-[`docs/consumer.html`](./docs/consumer.html) and mesh handout
-`WAYGRAPH-CONSUMER-CONVENTION.md` - separate from this package API doc.
+```bash
+waygraph auto status <sessionId>              # read the current menu (no side effects)
+waygraph auto send <sessionId> "<pick>"       # run one pick, get the resulting menu back
+waygraph auto dom <sessionId>                 # inspect the live DOM/ARIA tree
+waygraph auto trace <sessionId>               # read the Checkpoint/Block history so far
+waygraph auto reach <sessionId> <Checkpoint>  # run a whole multi-step route in one call
+waygraph auto resync <sessionId>              # force here to re-detect from the real page
+```
 
-Deliberately **not yet implemented** (tracked on the project board):
-- Interstitials/Watchers - background overlay handling (cookie banners, popups).
-- Split `requires` (externally-supplied vs producedBy) recovery hints.
-- Federated multi-package pool of waygraphs.
+Worked example (run for real against `examples/saucedemo`, no new execution code involved): an
+agent gets a plain request - "log me in and buy the backpack" - reads the graph and the starting
+`status`, reasons out login -> add-to-cart -> cart -> checkout info -> submit -> finish as the
+route to `OrderComplete`, then drives it by repeatedly reading each `status`/`send` response and
+picking the next index itself. The browser stays open the whole time; the user can watch it, or
+check the final tab afterward.
+
+**`auto reach <sessionId> <Checkpoint>`** runs a whole route in one call instead of one
+`send` per step - real, reported pain for any non-trivial task on a rich graph ("the entire
+prompts of the day" for one manual walkthrough). It path-finds via the same BFS `auto --blocks
+<From> <To>` already uses, then runs each step directly against the session's own live
+page/mem, verifying every step actually lands where its own graph edge promised (not just that
+it ran without throwing - a Block can legitimately resolve elsewhere, e.g. a login submission
+staying put after bad auth). **Real, stated limitation, not silently papered over:** for a
+target only reachable by crossing a wildcard (`from: "*"`) edge whose real DOM precondition
+depends on same-Checkpoint setup (e.g. filling form fields before a submit), neither `reach`
+nor the already-shipped `auto --blocks` can safely route there automatically - both fail loud
+within a bounded time (a real Playwright click/wait timeout) rather than silently guessing
+wrong or hanging. Full design history - three rejected approaches, a real correctness bug this
+change's own tests caught, and this limitation confirmed by direct reproduction - is in
+`openspec/changes/waygraph-pilot/tasks.md`'s own M5 section.
+
+**`auto resync <sessionId>`** - `here` is only ever updated by an action the session itself
+ran (`send`/`reach` set it from a Block's own resolved Checkpoint; the raw `click`/`type`/
+`goto` primitives null it because *they* just changed the page). Anything that changes the
+page *outside* the session - a human clicking around in a visible `--non-headless` session
+someone is co-driving, for instance - leaves `here` silently stale, since `send`/`reach` only
+ever re-detect when the position is already unknown, never to double-check a known one.
+`resync` forces that re-detection unconditionally, right now, against whatever the real page
+actually shows. Doesn't crash or corrupt anything if you never need it - it's a real, found
+gap (confirmed by reading the exact code path, `src/auto-session.ts`'s `currentMenu()`), fixed
+outright rather than left as a caveat.
+
+**On-page indicator.** A headful (`--non-headless`) session looks like an ordinary browser
+tab otherwise - no sign anything is driving it, which matters once a human might be watching
+or co-driving the same visible session. Every session now injects a small badge (bottom-right
+corner: `Waygraph Pilot - session <id> - <Checkpoint>`) that click-expands into a panel
+listing the current live menu's real edges (block name, kind, target Checkpoint,
+description) - the same data `auto status` returns, rendered in the page itself. Both refresh
+automatically after every `send`/`reach`/`reload`/`resync`/raw action - there's nothing
+separate to call to keep it in sync. Particularly useful for Blind Pilot: watching the panel
+update as newly-authored Blocks get picked up via `reload` shows the map actually growing,
+live, not just a JSON diff in a terminal. Self-contained (`src/pilot-overlay.ts`), not built
+on `waygraph demo`'s own panel/banner system, for the same `cli.ts`-side-effect reason
+`pilot-v1`'s old narrate-mode ring wasn't either.
+
+**Pilot itself does no planning, resolving, narrating, or acting** - `pilotStart`'s only job is
+starting the session and handing back its graph in one round trip; see `src/pilot.ts`. An
+earlier shape (`pilot ask "<text>"`, a deterministic ask-to-one-edge text matcher) was built,
+shipped, and then explicitly rejected as not matching this goal - preserved for reference at git
+tag `waygraph-pilot-v1-logs-prettified`, not on any active branch.
+
+**Honest scope, not silently redefined:** this capability's own proof runs against an in-repo
+example (`examples/saucedemo`), not a real external consumer application - it demonstrates the
+mechanism works, not the "demoable on one real consumer" bar `ROADMAP.md` sets for `1.0.0`,
+which remains separate, later, unmet work. Live reference: `tests/pilot/pilot.spec.ts` (the
+library function) and `tests/cli/pilot.spec.ts` (the real CLI), both proven against live
+saucedemo.com.
+
+## Blind Pilot (cold start, zero Blocks)
+
+Waygraph Pilot above assumes a Block library already exists. Blind Pilot is the opposite
+case: a session on a site nobody has described to this package yet. `AutoSession`/`auto --cli
+--detach` already tolerate a project directory with **zero** `.block.ts` files (no crash,
+`here` just stays `null`), so an agent can open a real session and start exploring cold with
+no new code at all - `auto dom <sessionId>` already gives real DOM/ARIA visibility
+independent of any Block library.
+
+What's actually new here is two primitives an agent needs to go from "exploring" to "building
+a Block library incrementally":
+
+```bash
+waygraph auto click <sessionId> "<selector>"          # act before any Block covers this
+waygraph auto type <sessionId> "<selector>" "<text>"  # same, for a real input
+waygraph auto goto <sessionId> "<url>"                # navigate the real live page
+waygraph auto reload <sessionId>                      # pick up a Block just written to disk,
+                                                       # without restarting the session
+```
+
+`click`/`type`/`goto` each re-detect the session's Checkpoint afterward (the same detection
+`send`/`status` already use) and return a fresh snapshot - a selector matching nothing is a
+reported failure naming it, not a silent no-op. `reload` re-discovers the project's Block
+library/graph from disk in place, leaving the live page, mem, and current Checkpoint
+untouched - so a Block an agent just wrote to disk becomes immediately runnable via the
+session's existing `send`, without relaunching the browser.
+
+**This package writes no Block content.** The driving agent recognizes a pattern ("this is a
+login form") and writes the `.block.ts`/`*Sel`/mem-keys files itself, using the conventions
+documented above - the same way it would write any other source file. Worked example (proven
+end to end in `tests/cli/auto-session-blind-pilot.spec.ts` against an in-repo synthetic
+fixture, `tests/fixtures/blind-pilot-site/`): start a session with zero Blocks, explore via
+`dom`/`click`/`goto`, write one real `defineNavBlock` to disk, `reload`, then `send` it -
+reaching the real Checkpoint it declares, proving it's genuinely driveable, not just visible.
+
+**Two real gotchas found while proving this, worth knowing before debugging a silent
+failure:** a `.block.ts` file that throws on import (e.g. a malformed Trait call) vanishes
+from the graph with no error printed anywhere - `discoverGraph`'s per-file import errors are
+mostly swallowed silently, so "reload did nothing" can mean a real mistake in the file just
+written, not a package bug. And a Block not wired into any `.flow.ts` (`waygraph graph`'s own
+"orphan" warning) is still fully visible and runnable in a live session's menu - orphan status
+only affects `auto --blocks <From> <To>` path-finding, not `auto`'s own menu.
+
+**Honest scope:** Blind Pilot does not currently author into the Waygraph Map convention
+below by default - it still writes plain files wherever it's pointed. Proof stays against an
+in-repo synthetic fixture, not a real external site.
+
+## Waygraph Map
+
+An opinionated, Next.js/Nuxt-style folder convention where a project's own directory
+structure mechanically *is* its map - not a separate schema file to generate, maintain, or
+let drift out of sync. Needs zero new engine code: `discoverGraph`/`loadBlockLibrary` already
+recurse through any folder structure, matching only the `.block.ts` filename pattern - folder
+naming and depth are already 100% cosmetic to every existing command.
+
+```text
+src/routes/
+  (base_app)/              # purely organizational - never part of any Checkpoint tag
+    dashboard/              # one folder per Checkpoint - "Dashboard"
+      page.block.ts          # arrival hub (definePageBlock) - fixed name, every folder
+      nav.block.ts            # navigation (defineNavBlock) - fixed name, every folder
+      dashboard.sel.ts
+      methods/
+        click-widget.block.ts
+  (external)/
+    docs/                    # a different group, same shape - "Docs"
+      page.block.ts
+      nav.block.ts
+      docs.sel.ts
+```
+
+Same Block helpers as today's freeform "manual mode" (`definePageBlock`/`defineNavBlock`/
+`defineMethodBlock`/etc.) - this only changes *where files live and what they're named*,
+never what kind of Block authors them or how they execute. A project adopts it incrementally,
+folder by folder; the two styles compose in the same flow with no special-casing (proven in
+`templates/scaffold`'s own `routes-demo.flow.ts`: `nav-home` from `src/blocks/`, manual mode,
+into `nav-docs` from `src/routes/`, Map convention, one real navigation).
+
+**"waypack" - loading another project's Blocks needs no separate manifest either.** A second
+project depending on a Map-convention project as a plain `file:` dependency (the same
+mechanism `examples/saucedemo`'s own `"waygraph": "file:../.."` already uses) is immediately
+understandable: `waygraph graph node_modules/<loaded-package>` correctly discovers its full
+Checkpoint/edge structure, with nothing generated or maintained separately. Proven end to end
+in `examples/routed-demo-consumer/` against `examples/routed-demo/`.
+
+**A real bug this proof surfaced, fixed, not left as a caveat:** a *live* `--detach` session
+against a package loaded through a consumer project's own deeply nested `node_modules/<pkg>`
+path used to fail with `listen EINVAL` - the session's Unix socket lived under the project
+directory, and that absolute path could exceed the OS's AF_UNIX limit (~108 bytes on Linux).
+Fixed: session sockets now live in a short, fixed location (`os.tmpdir()/waygraph-auto/`),
+independent of how deeply the project itself is nested - confirmed against the exact
+previously-failing path (`auto --cli --detach`, `auto reach`, and quit all working normally).
+Session metadata (`.waygraph-auto/<id>.json`, discoverable per-project) is unaffected - only
+the socket moved.
+
+Full design history (why "Router" isn't a separate thing to build, two prior wrong readings
+of this before landing here, and everything above stated as requirements) in
+`openspec/changes/waygraph-map/`.
+
+## Getting started (pick one)
+
+| Goal | Command |
+|------|---------|
+| Watch Sauce Demo step-through (temp dir only) | `npx waygraph try demo` |
+| Interactive explore (Add/Remove/Open details from live page) | `cd examples/saucedemo && npm i && npx waygraph auto` |
+| Scaffold a new **offline** project (green `npm test` on local fixture `:4177`) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
+| Install coding-agent defs for diving an app into Blocks | `npx waygraph agent-dive --loop claude` (also `opencode` / `cursor` / `vscode`) |
+| Add waygraph to an existing repo | `npm install waygraph @playwright/test` |
 
-**Available now:** `waygraph auto [project]` is the **interactive explore** loop:
-`locate()` reads where you are, lists runnable Blocks from the graph, you pick one
-(headful panel or `--cli` terminal menu), repeat. Static graph export (old JSON /
-Mermaid) is `waygraph graph [project]` (`--mermaid`). Unattended JSON execution is
-`chain` + `WAYGRAPH_JSON=1`.
+**Scaffold is not hidden inside waygraph alone** - the offline starter also ships as
+[`create-waygraph`](https://github.com/deviate-dv8/create-waygraph) on npm (same template
+as `waygraph init` since 0.7.5). Use whichever entry you already have:
+`npx create-waygraph my-app` when reading the GitHub Pages docs, or `npx waygraph init my-app`
+when the CLI is already installed. After either:
 
-**Friendly demo / run / auto (0.10.5 — flows are files):**
+```bash
+cd my-app && npm install && npx playwright install chromium && npm test
+```
+
+`try demo` is different: live saucedemo.com, step-through **Sign In -> Shop & Checkout ->
+blocked Viewer login**, then headless tests. Permanent full example:
+[`examples/saucedemo`](./examples/saucedemo). Offline empty scaffold: `init` /
+`create-waygraph`.
+
+```bash
+# From this checkout, after npm run build:
+cd examples/saucedemo && npm install && npx playwright install chromium
+npm test                  # live Playwright suite
+npm run auto              # headed interactive explore
+npm run demo:step         # stepper (manual Next)
+npm run demo:autoplay     # stepper with Auto-advance
+```
+
+Both scaffold commands emit the same offline tree (route-shaped `demo-web/` + `methods/`,
+stubs, fixtures, one YAP slide). Layout: [`docs/scaffold.html`](./docs/scaffold.html) ·
+`templates/scaffold/STRUCTURE.md`.
+
+**Consumer layout (Next.js App Router):** block folders mirror `app/` page routes (`/` at
+the namespace root; no invented `landing/`/`root/`; sidebar = chrome + edges). See
+[`docs/consumer.html`](./docs/consumer.html). A separate mesh handout
+(`WAYGRAPH-CONSUMER-CONVENTION.md`) covers the same convention outside this repo - not
+part of this package's own tree.
+
+## CLI reference
+
+`waygraph auto [project]` is the **interactive explore** loop: `locate()` reads where you
+are, lists runnable Blocks from the graph, you pick one (headful panel or `--cli` terminal
+menu), repeat. Static graph export (old JSON / Mermaid) is `waygraph graph [project]`
+(`--mermaid`). Unattended JSON execution is `run` + `WAYGRAPH_JSON=1`.
+
+**`--cli` session control:** `waygraph auto --cli` on its own is a blocking terminal loop -
+fine for a person, awkward for an agent that needs to inspect state between picks or send
+one command at a time without guessing a whole input sequence upfront. `--detach` runs that
+same session as a background socket server instead (session identity under
+`.waygraph-auto/` in the target project, mirroring `.waygraph-traverse/`'s convention);
+`auto send <sessionId> "<pick>"` and `auto status <sessionId>` are non-interactive
+request/response calls against it (no TTY needed), and `auto attach <sessionId>` reopens an
+interactive terminal against an already-running session. `send q`/`send quit` ends the
+session and cleans up its socket/metadata. `--detach` defaults to headless;
+`--non-headless` (the same flag `run`/`demo` already use) launches a real visible browser
+window while the session stays driven entirely through `send`/`status`/`attach`/`dom` - not
+a new picker UI, and the existing page-embedded headful panel (bare `waygraph auto`, no
+`--cli`) is untouched either way.
+
+**Session history:** `auto trace <sessionId>` returns a Checkpoint/Block-level record of
+what the session actually did - Block name, Checkpoint before/after, and (when the Block
+authors them) its resolved `stubBefore`/`stubAfter`/`stubOnError` demo-narration fixtures
+(the same highlight/todo/device data `waygraph demo`'s own lifecycle logging computes via
+`runStubPhase`, reused here since it's pure data with no browser side effects). Deliberately
+not a raw action recorder - no clicks/fills, only the same Block-level resolution the rest of
+the engine already reasons about, capped at the last 500 steps.
+
+**Reading the live page:** `auto dom <sessionId>` gives an agent driving a session read-only
+visibility into the actual page, without reading the target project's frontend source.
+Default `--mode aria` returns Playwright's AI-oriented accessibility snapshot
+(`ariaSnapshotJSON({ mode: "ai" })`) - small and usually enough to find "the Username
+textbox" or "the Login button." `--mode full` returns a bounded raw DOM subtree
+(tag/attributes/text/children - useful when you need actual CSS classes or data-attributes
+`aria` can't see), hard-capped on depth/node count/text length and marked `truncated: true`
+whenever a cap is hit, since this is read by an LLM, not a human. `--selector <sel>` scopes
+either mode to one element's subtree instead of the whole page - a modifier on the mode, not
+a third mode.
+
+**Agent bootstrap:** `waygraph pilot start` starts a `--detach` session and reads back the
+whole project graph in one call, so an agent can begin planning a multi-step request
+immediately - see "Waygraph Pilot" above for the full picture.
+
+**Cold start (zero Blocks):** `auto click/type/goto <sessionId>` act on the live page even
+when no Block covers that action yet, and `auto reload <sessionId>` picks up a Block just
+written to disk without restarting the session - see "Blind Pilot" above.
+
+Flows are files (0.10.5+):
 
 | Want | Command |
 |------|---------|
-| List flows | `waygraph list` → `src/flows/shop.flow.ts  shopFlow` |
-| Run by file | `waygraph run src/flows/shop.flow.ts --data '{…}'` |
-| Same via `auto` | `waygraph auto src/flows/shop.flow.ts --data '{…}'` |
+| List flows | `waygraph list` -> `src/flows/shop.flow.ts  shopFlow` |
+| Run by file | `waygraph run src/flows/shop.flow.ts --data '{...}'` |
+| Same via `auto` | `waygraph auto src/flows/shop.flow.ts --data '{...}'` |
 | Run by export | `waygraph run --blocks shopFlow` |
 | Manual watch | `waygraph demo src/flows/shop.flow.ts` |
 | Auto-advance | `waygraph demo --blocks shopFlow --auto-next` (nav auto-hides strip) |
-| Fast / full strip | `waygraph demo … --fast` (shorter gates; keeps cursor) · `--full` (classic chips; default = carousel) |
+| Fast / full strip | `waygraph demo ... --fast` (shorter gates; keeps cursor) · `--full` (classic chips; default = carousel) |
 | QA watch + record | `waygraph demo --blocks shopFlow --auto-play-video` |
-| Ad-hoc Blocks | `waygraph run --blocks "login then nav-cart" --data '{…}'` |
+| Ad-hoc Blocks | `waygraph run --blocks "login then nav-cart" --data '{...}'` |
 | Headed execute | `waygraph run --blocks shopFlow --non-headless --video` |
 | Explore | `waygraph auto` / `waygraph auto --cli` |
 | Path-find | `waygraph auto --blocks LoginPage OrderComplete` |
+| Run `--cli` as a background session | `waygraph auto --cli --detach` -> `{sessionId, socketPath}` |
+| Drive a detached session (no TTY) | `waygraph auto send <sessionId> "<pick>"` -> JSON state |
+| Read a detached session's state | `waygraph auto status <sessionId>` (no side effects) |
+| Reattach a terminal to a detached session | `waygraph auto attach <sessionId>` |
+| Read the live page (aria, small/default) | `waygraph auto dom <sessionId>` |
+| Read the live page (raw DOM, bounded) | `waygraph auto dom <sessionId> --mode full` |
+| Scope either to one element | `waygraph auto dom <sessionId> --selector ".inventory_list"` |
+| Detached session with a real visible browser | `waygraph auto --cli --detach --non-headless` |
+| Read the session's Checkpoint/Block history | `waygraph auto trace <sessionId>` |
+| Whole-project nav-escape + inline-selector + orphan sweep | `waygraph check [project]` |
+| Graph crawl | `waygraph traverse [project] --parallel N --min-edge-coverage 80%` |
+| Coding-agent defs | `waygraph agent-dive --loop claude` |
+| One-shot temp-dir demo | `waygraph try demo` / `waygraph try auto` / `waygraph try auto:cli` |
 
 `--blocks` / positional accepts a Flow export, a `.flow.ts` path, or `"a then b"`.
 `auto <file.flow.ts>` **runs** that flow (same as `run`); bare `auto` still explores.
-`--auto-next` (alias `--autoplay`) = panel Auto-advance. `--auto-play-video` is **demo only**.
-`chain` remains a compat alias for `run --blocks` / `auto --blocks`.
+`--auto-next` (alias `--autoplay`) = panel Auto-advance. `--auto-play-video` is **demo
+only**. `chain` remains a compat alias for `run --blocks` / `auto --blocks`.
+
+Run `waygraph --help` (or any subcommand with no args) for the full flag reference kept
+in `src/cli.ts`'s own `usage()` - that's the source of truth for flags, this table is the
+scannable summary.
 
 ## Example
 
@@ -372,18 +951,13 @@ const result = await flow.run(context, mem);
 // result === { __state: "Submitted" }
 ```
 
-See `tests/define-flow.spec.ts` here, and `examples/saucedemo/tests/checkout-flow.spec.ts`
-(a real multi-Block flow against live saucedemo.com), for this running for real. The
-lower-level `connect()`/`runGraph()` still exist and are what `defineFlow` builds on -
-reach for them directly only if you need a shape `defineFlow`'s array can't express yet.
-
 ## Recipes
 
 ### Detect / drive the surviving tab after a run
 
 The default run closes the page it opened, and a page you hand in via `options.page`
-survives. For a flow that must BE the surviving tab after it returns (an interactive demo,
-a hand-back to a caller), ask for the page back explicitly:
+survives. For a flow that must BE the surviving tab after it returns (an interactive
+demo, a hand-back to a caller), ask for the page back explicitly:
 
 ```typescript
 const { result, page } = await registerFlow.run(context, mem, { closeOnFinish: false });
@@ -402,7 +976,7 @@ event armed before the click that is expected to open exactly one popup:
 let popup: Page | undefined;
 context.once("page", (p) => { popup = p; });
 await linkHandle.click();          // the block that causes the popup (e.g. the
-                                   // MailHog email's real verify link)
+                                    // MailHog email's real verify link)
 if (popup) {
   await popup.waitForLoadState();  // fully loaded before calling into the engine
   await verifyLinkFlow.run(context, mem, { page: popup, closeOnFinish: false });
@@ -431,9 +1005,9 @@ npm run build       # tsc -p tsconfig.build.json, emits dist/
 
 ### Blind-agent overlay gate (anti-blank)
 
-Every live modal (`#wg-panel`, `#wg-banner`, `#wg-auto-panel`) stamps
-`data-wg-ui` / `data-wg-modal` / `data-wg-ready="1"`. Do **not** claim the
-stepper works unless one of these passes:
+Every live modal (`#wg-panel`, `#wg-banner`, `#wg-auto-panel`, `#wg-todo-dock`) stamps
+`data-wg-ui` / `data-wg-modal` / `data-wg-ready="1"`. Do **not** claim the stepper works
+unless one of these passes:
 
 ```bash
 # Playwright helper (exported from waygraph)
@@ -446,32 +1020,46 @@ WAYGRAPH_PROVE_EXIT=1 WAYGRAPH_PROVE_SHOT=/tmp/wg.png \
 # stderr: WAYGRAPH_PROVE {"ok":true,"beacons":[...],"readyAttr":"1"}
 ```
 
-Tests: `tests/cli/overlay-beacon.spec.ts`. Helpers: `src/overlay-beacon.ts`.
+Tests: `tests/cli/overlay-beacon.spec.ts`. Helpers: `src/overlay-beacon.ts`. Rules for
+touching the stepper/overlay chrome itself: `src/CLI-STOMP-GUARD.md`.
 
 ## Layout
 
 ```
-package.json              the "waygraph" npm package itself (0.9.0+)
+package.json              the "waygraph" npm package itself
 src/
   types.ts                 Checkpoint, Instruction, Block, connect()
   mem-page.ts               MemKey, key(), MemPage
   trait.ts                   Trait (type + discoverable Trait.url/.text/.visible), runVerify()
-  engine.ts                   runGraph(), definePageBlock, defineMethodBlock, Engine, …
+  engine.ts                   runGraph(), definePageBlock, defineMethodBlock, Engine, ...
   graph.ts                     discoverGraph, orphans, paths
-  auto-explore.ts              waygraph auto menu
-  index.ts                     public barrel
+  auto-explore.ts               waygraph auto menu building
+  auto-explore-run.ts            waygraph auto interactive loop (headful + --cli)
+  highlights.ts                  stub/fixture/slide/todo-dock/device narration types + helpers
+  step-overlay.ts                 demo step overlay chrome (panel, ring, cursor)
+  overlay-beacon.ts                blind-agent overlay readiness beacons
+  traverse-run.ts                   waygraph traverse crawl (serial/parallel)
+  traverse-coverage.ts               traverse coverage report + CI gate
+  traverse-lease.ts                  traverse edge lease coordinator
+  blocks-select.ts                   shared --blocks glob/regex/bare grammar
+  agent-dive.ts                      waygraph agent-dive coding-agent scaffolding
+  cli.ts                             waygraph CLI entrypoint (all subcommands)
+  index.ts                           public barrel
 examples/saucedemo/         live Sauce Demo (Page + methods/ + Sel)
 templates/quickstart/       try demo / init template (mirrors sauce)
-docs/                       GitHub Pages static HTML
-typecheck/                 compile-time-only fixtures
+templates/scaffold/         offline init/create-waygraph scaffold template
+templates/agents/           waygraph agent-dive coding-agent definitions
+docs/                       GitHub Pages static HTML + docs/proposals/ RFCs
+openspec/                   spec-driven planning: specs/ (current), changes/ (in-flight),
+                            changes/archive/ (shipped)
 tests/                      runtime unit + integration tests (@playwright/test)
 tsconfig.json                base config
 tsconfig.build.json          emits to dist/
 ```
 
 In-package Sauce Demo: [`examples/saucedemo`](./examples/saucedemo). Other consumer
-experiments (e.g. zsign-app integration) may still live in a sibling workspace folder and
-depend on this package via `"waygraph": "file:../waygraph"` during local dev (see that
+experiments may still live in a sibling workspace folder and depend on this package via
+`"waygraph": "file:../waygraph"` during local dev (see that
 project's own `.npmrc` - `install-links=true` is required there, or npm will symlink
 instead of copy and pull this package's own `node_modules` in through the symlink, causing
 a duplicate-Playwright-installation error).