waygraph 0.15.43 → 0.15.45

package/examples/saucedemo/.waygraph-auto/976394cd.log

@@ -0,0 +1,20 @@
+[13:02:58.767] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[13:02:58.768] waygraph pilot: stub.before ctx.todos n=6 index=0
+[13:02:58.768] waygraph pilot: stub.before ctx.device(mobile)
+[13:02:58.768] waygraph pilot: stub.before ctx.zoom(1.35)
+[13:02:58.768] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[13:02:59.901] waygraph pilot: stub.after ctx.todos n=6 index=1
+[13:03:01.746] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[13:03:01.917] waygraph pilot: stub.after ctx.todos n=6 index=2
+[13:03:03.342] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[13:03:03.706] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[13:03:03.706] waygraph pilot: stub.after ctx.todos n=6 index=3
+[13:03:03.706] waygraph pilot: stub.after ctx.device(mobile)
+[13:03:03.706] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[13:03:07.006] waygraph pilot: stub.before ctx.title("Open cart · landscape")
+[13:03:07.006] waygraph pilot: stub.before ctx.todos n=6 index=5
+[13:03:07.006] waygraph pilot: stub.before ctx.device(mobile)
+[13:03:07.006] waygraph pilot: stub.before ctx.zoom(1.4)
+[13:03:07.007] waygraph pilot: stub.before ring .shopping_cart_link tone=planned label="Cart"
+[13:03:07.381] waygraph pilot: stub.after ctx.title("Your cart · desktop")
+[13:03:07.381] waygraph pilot: stub.after ring .cart_item tone=success label="Cart items"

package/examples/saucedemo/.waygraph-auto/9a26134c.log

@@ -0,0 +1,20 @@
+[12:45:05.504] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[12:45:05.504] waygraph pilot: stub.before ctx.todos n=6 index=0
+[12:45:05.504] waygraph pilot: stub.before ctx.device(mobile)
+[12:45:05.504] waygraph pilot: stub.before ctx.zoom(1.35)
+[12:45:05.505] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[12:45:06.709] waygraph pilot: stub.after ctx.todos n=6 index=1
+[12:45:08.058] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[12:45:08.158] waygraph pilot: stub.after ctx.todos n=6 index=2
+[12:45:09.619] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[12:45:09.890] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[12:45:09.890] waygraph pilot: stub.after ctx.todos n=6 index=3
+[12:45:09.890] waygraph pilot: stub.after ctx.device(mobile)
+[12:45:09.890] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[12:45:12.501] waygraph pilot: stub.before ctx.title("Open cart · landscape")
+[12:45:12.501] waygraph pilot: stub.before ctx.todos n=6 index=5
+[12:45:12.501] waygraph pilot: stub.before ctx.device(mobile)
+[12:45:12.501] waygraph pilot: stub.before ctx.zoom(1.4)
+[12:45:12.501] waygraph pilot: stub.before ring .shopping_cart_link tone=planned label="Cart"
+[12:45:12.724] waygraph pilot: stub.after ctx.title("Your cart · desktop")
+[12:45:12.724] waygraph pilot: stub.after ring .cart_item tone=success label="Cart items"

package/examples/saucedemo/.waygraph-auto/9d827954.log

@@ -0,0 +1,20 @@
+node:internal/modules/esm/resolve:272
+    throw new ERR_MODULE_NOT_FOUND(
+          ^
+
+Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/dan/Desktop/Projects/waygraph/dist/dist/cli.js' imported from /home/dan/Desktop/Projects/waygraph/
+    at finalizeResolution (node:internal/modules/esm/resolve:272:11)
+    at moduleResolve (node:internal/modules/esm/resolve:879:10)
+    at defaultResolve (node:internal/modules/esm/resolve:1006:11)
+    at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20)
+    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:728:38)
+    at nextStep (node:internal/modules/customization_hooks:189:26)
+    at resolveBaseSync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:10932)
+    at resolveDirectorySync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:12238)
+    at resolveTsPathsSync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:13445)
+    at resolve (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:15991) {
+  code: 'ERR_MODULE_NOT_FOUND',
+  url: 'file:///home/dan/Desktop/Projects/waygraph/dist/dist/cli.js'
+}
+
+Node.js v26.7.0

package/examples/saucedemo/.waygraph-auto/a4f8d355.log

@@ -0,0 +1,20 @@
+node:internal/modules/esm/resolve:272
+    throw new ERR_MODULE_NOT_FOUND(
+          ^
+
+Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/dan/Desktop/Projects/waygraph/dist/dist/cli.js' imported from /home/dan/Desktop/Projects/waygraph/
+    at finalizeResolution (node:internal/modules/esm/resolve:272:11)
+    at moduleResolve (node:internal/modules/esm/resolve:879:10)
+    at defaultResolve (node:internal/modules/esm/resolve:1006:11)
+    at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20)
+    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:728:38)
+    at nextStep (node:internal/modules/customization_hooks:189:26)
+    at resolveBaseSync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:10932)
+    at resolveDirectorySync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:12238)
+    at resolveTsPathsSync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:13445)
+    at resolve (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:15991) {
+  code: 'ERR_MODULE_NOT_FOUND',
+  url: 'file:///home/dan/Desktop/Projects/waygraph/dist/dist/cli.js'
+}
+
+Node.js v26.7.0

package/examples/saucedemo/.waygraph-auto/aa226dd0.log

@@ -0,0 +1,22 @@
+[12:45:12.771] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[12:45:12.771] waygraph pilot: stub.before ctx.todos n=6 index=0
+[12:45:12.771] waygraph pilot: stub.before ctx.device(mobile)
+[12:45:12.772] waygraph pilot: stub.before ctx.zoom(1.35)
+[12:45:12.772] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[12:45:13.786] waygraph pilot: stub.after ctx.todos n=6 index=1
+[12:45:15.938] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[12:45:16.050] waygraph pilot: stub.after ctx.todos n=6 index=2
+[12:45:18.381] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[12:45:18.790] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[12:45:18.790] waygraph pilot: stub.after ctx.todos n=6 index=3
+[12:45:18.790] waygraph pilot: stub.after ctx.device(mobile)
+[12:45:18.790] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[12:45:24.718] waygraph pilot: stub.before ctx.title("Pick a product · tablet")
+[12:45:24.720] waygraph pilot: stub.before ctx.todos n=6 index=3
+[12:45:24.720] waygraph pilot: stub.before ctx.device(tablet)
+[12:45:24.720] waygraph pilot: stub.before ctx.zoom(1.35)
+[12:45:24.720] waygraph pilot: stub.before ring div.inventory_item:has(button[data-test="add-to-cart-sauce-labs-backpack"], button[data-test="remove-sauce-labs-backpack"]) .inventory_item_name tone=info label="Sauce Labs Backpack"
+[12:45:24.720] waygraph pilot: stub.before ring [data-test="add-to-cart-sauce-labs-backpack"] tone=success label="Add to cart"
+[12:45:25.945] waygraph pilot: stub.after ctx.title("In the cart")
+[12:45:25.945] waygraph pilot: stub.after ctx.todos n=6 index=4
+[12:45:25.945] waygraph pilot: stub.after ring .shopping_cart_badge tone=success label="Cart badge"

package/examples/saucedemo/.waygraph-auto/b14811d7.log

@@ -0,0 +1,6 @@
+[13:05:33.005] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[13:05:33.006] waygraph pilot: stub.before ctx.todos n=6 index=0
+[13:05:33.006] waygraph pilot: stub.before ctx.device(mobile)
+[13:05:33.006] waygraph pilot: stub.before ctx.zoom(1.35)
+[13:05:33.006] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[13:05:34.576] waygraph pilot: stub.after ctx.todos n=6 index=1

package/examples/saucedemo/.waygraph-auto/cc989184.log

@@ -0,0 +1,20 @@
+node:internal/modules/esm/resolve:272
+    throw new ERR_MODULE_NOT_FOUND(
+          ^
+
+Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/dan/Desktop/Projects/waygraph/dist/dist/cli.js' imported from /home/dan/Desktop/Projects/waygraph/
+    at finalizeResolution (node:internal/modules/esm/resolve:272:11)
+    at moduleResolve (node:internal/modules/esm/resolve:879:10)
+    at defaultResolve (node:internal/modules/esm/resolve:1006:11)
+    at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20)
+    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:728:38)
+    at nextStep (node:internal/modules/customization_hooks:189:26)
+    at resolveBaseSync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:10932)
+    at resolveDirectorySync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:12238)
+    at resolveTsPathsSync (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:13445)
+    at resolve (file:///home/dan/Desktop/Projects/waygraph/node_modules/tsx/dist/register-SoqaU4rg.mjs:2:15991) {
+  code: 'ERR_MODULE_NOT_FOUND',
+  url: 'file:///home/dan/Desktop/Projects/waygraph/dist/dist/cli.js'
+}
+
+Node.js v26.7.0

package/examples/saucedemo/.waygraph-auto/e5127c03.log

@@ -0,0 +1,22 @@
+[13:04:44.176] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[13:04:44.177] waygraph pilot: stub.before ctx.todos n=6 index=0
+[13:04:44.177] waygraph pilot: stub.before ctx.device(mobile)
+[13:04:44.177] waygraph pilot: stub.before ctx.zoom(1.35)
+[13:04:44.177] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[13:04:45.401] waygraph pilot: stub.after ctx.todos n=6 index=1
+[13:04:48.550] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[13:04:48.656] waygraph pilot: stub.after ctx.todos n=6 index=2
+[13:04:52.040] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[13:04:52.285] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[13:04:52.285] waygraph pilot: stub.after ctx.todos n=6 index=3
+[13:04:52.285] waygraph pilot: stub.after ctx.device(mobile)
+[13:04:52.285] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[13:04:58.453] waygraph pilot: stub.before ctx.title("Pick a product · tablet")
+[13:04:58.453] waygraph pilot: stub.before ctx.todos n=6 index=3
+[13:04:58.454] waygraph pilot: stub.before ctx.device(tablet)
+[13:04:58.454] waygraph pilot: stub.before ctx.zoom(1.35)
+[13:04:58.454] waygraph pilot: stub.before ring div.inventory_item:has(button[data-test="add-to-cart-sauce-labs-backpack"], button[data-test="remove-sauce-labs-backpack"]) .inventory_item_name tone=info label="Sauce Labs Backpack"
+[13:04:58.454] waygraph pilot: stub.before ring [data-test="add-to-cart-sauce-labs-backpack"] tone=success label="Add to cart"
+[13:04:59.651] waygraph pilot: stub.after ctx.title("In the cart")
+[13:04:59.651] waygraph pilot: stub.after ctx.todos n=6 index=4
+[13:04:59.651] waygraph pilot: stub.after ring .shopping_cart_badge tone=success label="Cart badge"

package/examples/saucedemo/.waygraph-auto/eb38d92e.log

@@ -0,0 +1,22 @@
+[12:51:48.396] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[12:51:48.397] waygraph pilot: stub.before ctx.todos n=6 index=0
+[12:51:48.397] waygraph pilot: stub.before ctx.device(mobile)
+[12:51:48.397] waygraph pilot: stub.before ctx.zoom(1.35)
+[12:51:48.397] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[12:51:49.455] waygraph pilot: stub.after ctx.todos n=6 index=1
+[12:51:51.829] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[12:51:51.971] waygraph pilot: stub.after ctx.todos n=6 index=2
+[12:51:54.622] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[12:51:55.128] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[12:51:55.128] waygraph pilot: stub.after ctx.todos n=6 index=3
+[12:51:55.128] waygraph pilot: stub.after ctx.device(mobile)
+[12:51:55.128] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[12:52:00.976] waygraph pilot: stub.before ctx.title("Pick a product · tablet")
+[12:52:00.976] waygraph pilot: stub.before ctx.todos n=6 index=3
+[12:52:00.976] waygraph pilot: stub.before ctx.device(tablet)
+[12:52:00.976] waygraph pilot: stub.before ctx.zoom(1.35)
+[12:52:00.976] waygraph pilot: stub.before ring div.inventory_item:has(button[data-test="add-to-cart-sauce-labs-backpack"], button[data-test="remove-sauce-labs-backpack"]) .inventory_item_name tone=info label="Sauce Labs Backpack"
+[12:52:00.976] waygraph pilot: stub.before ring [data-test="add-to-cart-sauce-labs-backpack"] tone=success label="Add to cart"
+[12:52:01.987] waygraph pilot: stub.after ctx.title("In the cart")
+[12:52:01.987] waygraph pilot: stub.after ctx.todos n=6 index=4
+[12:52:01.987] waygraph pilot: stub.after ring .shopping_cart_badge tone=success label="Cart badge"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.43",
+  "version": "0.15.45",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/agents/waygraph-author.agent.md

@@ -8,67 +8,40 @@ tools:
   - edit
 ---
 
-You are a waygraph block author. Implement Blocks and Flows that match the consumer SITE-MAP.
+You are a waygraph block author. Implement Blocks and Flows that match the approved plan (a Map
+folder layout under `src/map/`, or a `SITE-MAP.md`/`NAV.md` plan for a freeform project).
 
-## Rules
+**Load the `waygraph-convention` skill first** (`--skill-convention` / the skill tool) - it owns
+the actual authoring rules (one action per Block, `_nav`/`_page`/`_sel.ts`/`_methods/` naming,
+selectors never inline, when to reach for `defineAssertBlock`, Mem key typing). Don't restate
+those rules here from memory; re-read the skill, since it's the one place they're kept current.
 
-1. One concern per file: `nav-*.block.ts`, `*.page.block.ts`, `*.method.block.ts`, `*.effect.block.ts`, `*.flow.ts`.
-2. **One distinct action per Block - hard rule, not a style preference.** A Method/Effect that
-   fills form fields *and* submits, or that drives a multi-step sequence inside one `act()`,
-   is wrong even if it "works" - split it into separate atomic Blocks. Concretely: a login
-   form is `fill-username` (self-loop) + `fill-password` (self-loop) + `submit-login` (the
-   real transition), never one Block doing all three. See `examples/saucedemo/src/blocks/saucedemo-web/methods/`
-   (`fill-username.method.block.ts`, `fill-password.method.block.ts`,
-   `submit-login.method.block.ts`) for the canonical before/after shape - `submit-login`
-   used to also fill both fields; now it only clicks. A Block that only asserts something on
-   the current page (no state change) is `defineAssertBlock({ name, checkpoint, verify,
-   requires? })` - self-loop and `resolve` are generated for you, so there is no hand-written
-   `act`/`resolve` to accidentally make do two things. Give it an explicit type argument
-   (`defineAssertBlock<LoggedIn>({...})`) whenever it is not the last Block before `end` -
-   without one it defaults to wildcard `Checkpoint<string>`, which breaks `defineFlow`'s
-   tuple typing once the assert sits between two specifically-typed Blocks.
-3. Navigation only inside `defineNavBlock` / `defineNavClickBlock`. Regular Method/Effect `act` uses ActionPage (no goto).
-4. Effects that appear in `waygraph auto` menus need `instanceOptions` that scan the live DOM (or mem) for labeled rows.
-5. Stubs: `stubBefore` / `stubAfter` / `stubOnError` for demo narration; YAP slides on Methods when useful; flow fixtures via `withHighlightFixtures` when AC copy is flow-specific.
-6. Mem: `requires` lists keys the block needs; seed via `--data` / `WAYGRAPH_DATA` / project defaults - never assume saucedemo creds for email keys. A key an *earlier Block in the same chain* produces (not the caller) is never declared under `requires` - `requires` means externally supplied, and preflight checks the whole chain up front, before any Block runs.
-7. **External Mailpit/MailHog: nav to inbox URL from env; Methods open message / read or click
-   the link; never put mail UI under `*-web/`.** Read the message via `page.locator`/
-   `page.frameLocator` DOM calls, never the catcher's REST API - zero new engine surface, and
-   it's narratable in `waygraph demo`/`auto`. Live, proven reference:
-   `templates/scaffold/src/blocks/demo-external/mailpit/` + `mail-verify.flow.ts`. Match a
-   specific inbox row by a mem-supplied recipient, not inbox position (a shared inbox across
-   runs can hold mail for more than one recipient). **Build the mail-reading Blocks
-   scenario-agnostic from the start**, not one Block set per email type: put the
-   link-matching pattern and expected body copy in mem too (alongside the recipient), so the
-   same fixed Blocks serve signup confirmation, password reset, magic link, etc. - a Block
-   named for one scenario (`extract-verification-link`) is a sign it should instead be named
-   for its mechanism (`extract-email-link`) and driven by mem. For asserting the message
-   *body* content (not just that a link exists), the top-level page's own `Trait.text`/
-   `Trait.visible` cannot see inside the preview iframe at all - use `Trait.frameVisible`/
-   `Trait.frameText`/`Trait.frameContains` (or a bespoke mem-aware `{ name, check(page, mem) }`
-   Trait when the expected value itself must vary per run).
-8. `verify`/`defineAssertBlock` selectors live in a `*Sel` object next to the route, never
-   inlined as a literal string in `Trait.visible(...)`/`Trait.text(...)` - `waygraph check`
-   warns on this (see below); fix by moving the string into that route's `*Sel`.
+## This agent's own job (on top of the skill)
 
-## Verify locally
+1. Match whatever plan you were handed - a Map folder (`src/map/(group)/page/`) or a
+   `SITE-MAP.md`/`NAV.md` route list. Don't invent a route/folder the plan didn't call for.
+2. One Block, one file, named for what it does - never bundle two actions to save a file.
+3. `waygraph check .` clean before reporting done - see below.
+
+## Verify before reporting done
 
 ```bash
 npx waygraph check .
 npx waygraph list
 npm run typecheck
-# offline fixtures or live:
-npx playwright test
-# explore:
-npm run auto        # or: npx waygraph auto --cli
+npx playwright test   # offline fixtures or live
+npm run auto          # or: npx waygraph auto --cli
 ```
 
-**Do not report this work done until `waygraph check .` shows zero orphan Blocks and zero
-inline-selector warnings, and zero nav-escape warnings for anything you touched.** A nonzero
-count in any of those three is not an informational note to mention and move past - it means
-go fix it first (wire the orphan into a `.flow.ts`, move the inline selector into `*Sel`, or
-move the escaping navigation into a `defineNavBlock`), then re-run `check`.
+**Do not report this work done until `waygraph check .` shows zero orphan Blocks, zero
+inline-selector warnings, zero overcomplex-selector warnings, and zero nav-escape warnings for
+anything you touched.** A nonzero count in any of those is not an informational note to mention
+and move past - fix it (wire the orphan into a `.flow.ts`, move the inline selector into
+`_sel.ts`/`*Sel`, replace a regex/XPath match with a plain selector, or move the escaping
+navigation into a `defineNavBlock`), then re-run `check`.
 
 ## Output
 
-Ship compiling TypeScript under `src/blocks/` + `src/flows/` + `src/states/`. Update NAV.md when edges change. Keep STRUCTURE / SITE-MAP honest.
+Ship compiling TypeScript under `src/map/` (Map layout) or `src/blocks/` + `src/flows/` +
+`src/states/` (freeform layout) - match whatever this project already uses; don't introduce the
+other layout partway through. Update `NAV.md`/`STRUCTURE.md` when edges change.

package/templates/agents/waygraph-planner.agent.md

@@ -8,7 +8,11 @@ tools:
   - edit
 ---
 
-You are a waygraph planner. Your job is to dive an existing app and produce a SITE-MAP + NAV.md plan — not dump ad hoc Playwright helpers.
+You are a waygraph planner. Your job is to dive an existing app and produce a plan - a Map folder
+layout (`src/map/(group)/page/`) for a new project, or a `SITE-MAP.md`/`NAV.md` plan when adding to
+an existing freeform-layout project - not dump ad hoc Playwright helpers. Load the
+`waygraph-convention` skill first for the actual folder/naming rules; this file is the planning
+workflow on top of it, not a restatement of them.
 
 ## Hard conventions
 
@@ -30,13 +34,14 @@ You are a waygraph planner. Your job is to dive an existing app and produce a SI
 ## Workflow
 
 1. Read the app router (Next.js `app/`, etc.) and list real page URLs.
-2. Draft `src/blocks/SITE-MAP.md` with namespaces + route folders.
+2. New project: lay out `src/map/(group)/page/` folders per route. Existing freeform project:
+   draft `src/blocks/SITE-MAP.md` with namespaces + route folders instead - match what's there.
 3. For each route: list nav-to edges, methods/effects, checkpoints, mem keys in `NAV.md` (plan only).
 4. Call out external surfaces (Mailpit inbox, magic-link verify) under `*-external/`. Plan
    these Blocks as reusable across every email-driven scenario the product has (signup
    confirmation, password reset, magic link, ...) via mem (recipient, link pattern, expected
    copy), not as a separate Block set per scenario - see
-   `templates/scaffold/src/blocks/demo-external/mailpit/` for the live, proven shape.
+   `templates/scaffold/src/map/(external)/mailpit/` for the live, proven shape.
 5. Propose 1-3 starter flows (happy path, login/verify, one feature) — do not implement unless asked.
 
 ## Blind mode (no frontend source)
@@ -46,7 +51,7 @@ codebase-blind engagement - discover the route/interaction structure live instea
 `waygraph auto` session tools rather than skipping planning:
 
 1. `waygraph auto --cli --detach [--base-url <url>]` against a throwaway project dir (or the
-   target project once a `src/blocks/` tree exists) - starts a driveable session, prints
+   target project once a `src/map/` or `src/blocks/` tree exists) - starts a driveable session, prints
    `{sessionId, socketPath}`.
 2. `waygraph auto status <sessionId>` to read the current menu (what Blocks/edges are already
    discoverable) and `waygraph auto dom <sessionId>` (default `aria` mode) to see the live
@@ -63,4 +68,6 @@ Same output contract as sighted planning: a SITE-MAP/NAV.md plan, not implemente
 
 ## Output
 
-Write/update markdown under `src/blocks/` (`SITE-MAP.md`, route `NAV.md` stubs). ASCII only. No localhost ports in shared docs.
+New project: the `src/map/` folders themselves are the plan - no separate SITE-MAP.md needed.
+Existing freeform project: write/update markdown under `src/blocks/` (`SITE-MAP.md`, route
+`NAV.md` stubs). ASCII only. No localhost ports in shared docs.

package/templates/scaffold/scripts/README.md

@@ -0,0 +1,13 @@
+# `scripts/`
+
+- `fixture-server.mjs` - serves the offline `.html` fixture pages under `src/map/` on
+  `127.0.0.1:4177` (override with `WAYGRAPH_FIXTURE_PORT`/`WAYGRAPH_FIXTURE_HOST`). This is
+  what makes `npm test` pass with no network and no real app running.
+- `with-fixture.mjs` - starts `fixture-server.mjs`, runs whatever command you give it
+  (`waygraph auto`, `waygraph demo --blocks ...`), then tears the server down when that command
+  exits. Every `npm run demo*`/`auto*` script in `package.json` goes through this wrapper -
+  don't run `waygraph demo`/`auto` directly against this scaffold's own fixture pages without it.
+
+Pointing this scaffold at a real app instead of the offline fixtures: change `_nav.block.ts`'s
+`url`/`homeOrigin` to the real one and drop `with-fixture.mjs` from the scripts that no longer
+need it.

package/templates/scaffold/src/flows/README.md

@@ -0,0 +1,18 @@
+# `src/flows/`
+
+A `*.flow.ts` composes Blocks from `src/map/` into a runnable path - `waygraph run`/`demo`/`test`
+all point at an export here by name (`waygraph run --blocks shopFlow`).
+
+- Prefer `new Engine().map()...end()` (the Map builder: `.gotoPage()`/`.method()`/`.assert()`/
+  `.branch()`) over hand-composing raw Blocks - it checks each step's Block kind at runtime and
+  the Checkpoint chain at compile time, so a wrong step is a build/test failure, not a
+  mid-run surprise.
+- `withTitle`/`withHighlightFixtures`/`withSessionReset`/etc. are non-destructive wrappers -
+  `someFlow.withTitle("...")` doesn't mutate `someFlow`, it returns a new one. Compose them
+  around the finished `.end()` result, not inside the Map chain itself.
+- One flow, one scenario. A flow that needs a genuinely different starting session
+  (re-entering the login page mid-chain) wraps that segment in `withSessionReset`, rather than
+  hand-clearing cookies inside a Block.
+
+New flow → new file here, named for the scenario (`checkout.flow.ts`), not for the Blocks it
+happens to use.

package/templates/scaffold/src/map/README.md

@@ -0,0 +1,31 @@
+# `src/map/`
+
+The Waygraph Map: one folder per page, mirroring your app's real URLs. See the root
+[`STRUCTURE.md`](../../STRUCTURE.md) for the full picture; this file is the local, one-screen
+version for whoever is inside this directory.
+
+## The fixed names, every page folder
+
+| File | Kind | Job |
+|---|---|---|
+| `_nav.block.ts` | Nav | How to get here - `url` (goto) or `click` (in-app link). One per page. |
+| `_page.block.ts` | Page | "You have arrived" - the hub other pages navigate to. One per page. |
+| `_sel.ts` | data | Every selector this page's Blocks use, in one object. Never inline a selector when this file exists - `waygraph check` warns on it. |
+| `_methods/` | folder | One file per action, one action per file (`add-item.effect.block.ts`, not one file with three `.fill()` calls). |
+
+Never rename these, never combine them into one file, never add a `_selectors/` folder in
+place of `_sel.ts` - one page, one selector file, same as every other page in the Map.
+
+## `(group)` folders
+
+A parenthesized folder (`(app_base)`, `(external)`) is organizational only - like a Next.js
+route group. It groups pages by origin/base URL and never appears in a Checkpoint name or a
+real URL. `waygraph map`/`waygraph check` fail loudly if a page folder's real URL stops
+matching its own name - that's the point of this layout: drift becomes a build failure, not a
+silent surprise months later.
+
+## Adding a page
+
+Copy an existing page folder, keep the four fixed names, update `_nav`/`_page`/`_sel` for the
+new page, then add `_methods/` files for its actions. Don't invent a new folder shape - every
+page in this Map looks the same on purpose.

package/templates/scaffold/src/states/README.md

@@ -0,0 +1,15 @@
+# `src/states/`
+
+Checkpoint types and Mem keys - the typed vocabulary every Block in `src/map/` is written
+against. Nothing here drives the browser; this is pure data shape.
+
+- `*.states.ts` - `type X = Checkpoint<"X">` declarations. One per real app state
+  (`LoginPage`, `LoggedIn`), never `Checkpoint<string>` (a wildcard - `waygraph check` warns
+  on it; a Block should say exactly which states it moves between).
+- `*.mem-keys.ts` - `key<T>("...")` / `keyGroup<T>("...")` declarations. A Mem key stores a
+  *value* a Block needs (credentials, a selected row's id) - never a selector (those live in
+  `_sel.ts` next to the page) and never something a Block could instead read straight off the
+  live page.
+
+Add a new Checkpoint or Mem key here before writing the Block that needs it - Blocks import
+from this directory, this directory never imports from `src/map/`.

package/templates/scaffold/tests/README.md

@@ -0,0 +1,10 @@
+# `tests/`
+
+Real `@playwright/test` specs, run through `waygraph test` (an alias for `playwright test`,
+plus `waygraph test ui`/`report`/`show-trace` for Playwright's own UI Mode/HTML report/trace
+viewer). These run against the offline fixture server (see `scripts/README.md`), not a live
+network - that's what makes `npm test` green immediately after `waygraph init`.
+
+A spec here typically runs a `*.flow.ts` from `src/flows/` and asserts on its result, rather
+than driving the page directly - the flow already encodes the real path and its own `verify`
+checks; the spec is proving the flow itself still works end to end, not re-deriving selectors.