waygraph 0.15.11 → 0.15.15

package/examples/saucedemo/.waygraph-auto/5bd8fedf.log

@@ -0,0 +1,4 @@
+(node:1438409) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1438409) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/5dde8331.log

@@ -0,0 +1,4 @@
+(node:1424575) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1424575) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/7efa646f.log

@@ -0,0 +1,4 @@
+(node:1424626) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1424626) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

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

@@ -0,0 +1,4 @@
+(node:1434346) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1434346) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

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

@@ -0,0 +1,4 @@
+(node:1434366) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1434366) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

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

@@ -0,0 +1,4 @@
+(node:1429810) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1429810) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.11",
+  "version": "0.15.15",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -35,7 +35,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "node bin/waygraph typecheck .",
     "test": "playwright test",
     "docs:preview": "python3 -m http.server 4173 --directory docs",
     "example:saucedemo:install": "npm --prefix examples/saucedemo install",

package/templates/scaffold/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "waygraph typecheck .",
     "test": "playwright test",
     "fixture": "node scripts/fixture-server.mjs",
     "list": "waygraph list",

package/templates/skills/waygraph-blind-pilot.skill.md

@@ -4,16 +4,29 @@ description: Cold-start a waygraph project against a real site with zero existin
 ---
 
 Blind Pilot is the same session mechanism as `waygraph-pilot`, minus the requirement of any
-pre-existing Blocks. `auto --cli --detach` tolerates a project with zero `.block.ts` files -
-`auto click/type/goto/press/upload` act on the real page before any Block exists to cover it.
+pre-existing Blocks. A project with zero `.block.ts` files still gets a live session —
+`browser click/type/goto/press/upload` act on the real page before any Block exists to cover it.
 This package generates **no Block content for you** - you write real `.block.ts`/`*Sel`/
 mem-key files by hand as you go. That's the whole point: turn one-off exploration into
 permanent, reusable, typed coverage instead of leaving nothing behind.
 
+## Session lifecycle (list first)
+
+```
+waygraph browser                         # show browser subcommands
+waygraph browser sessions                # list live sessions (cwd)
+waygraph browser start [--goto <url>]    # new headful session (about:blank by default)
+waygraph browser attach <sessionId>      # terminal picker on existing session
+waygraph browser stop <sessionId|--all>  # shut down when done
+```
+
+`browser start` always opens a **new** session. Check `browser sessions` before starting another.
+Session control works as `browser …` or `auto …` with the same `<sessionId>`.
+
 ## The real loop
 
-1. `auto goto <sessionId> <url>` / `auto click` / `auto type` to explore the real page.
-2. `auto dom <sessionId> --mode full --selector <sel>` to read real structure before writing
+1. `browser goto <sessionId> <url>` / `browser click` / `browser type` to explore the real page.
+2. `browser dom <sessionId> --mode full --selector <sel>` to read real structure before writing
    a selector - never guess a selector, confirm it against the real DOM first. `--mode aria`
    is faster for a first pass but can show stale/hidden responsive-duplicate content in some
    real apps (confirmed live: a hidden `lg:hidden` panel's heading text showed up in an aria
@@ -24,19 +37,20 @@ permanent, reusable, typed coverage instead of leaving nothing behind.
    then `Nav`/`Page`/`Method` Blocks, following `templates/scaffold`'s own folder convention
    (`(group)/<page-slug>/page.block.ts` + `nav.block.ts` + `methods/*.block.ts` + one `*.sel.ts`)
    so the result becomes part of the Waygraph Map, not a scattered one-off file.
-4. `auto reload <sessionId>` to pick up the newly-written Block(s) without restarting.
-5. Optionally narrate for a headful watcher: `auto highlight <sessionId> '{"rings":[...],"todos":[...]}'`
-6. Run the new Block for real via `auto send` - prove it works before moving to the next
+4. `browser reload <sessionId>` to pick up the newly-written Block(s) without restarting.
+5. Optionally narrate for a headful watcher: `browser highlight <sessionId> '{"rings":[...],"todos":[...]}'`
+   Raw ops show **`Running (no Block): …`** in the bottom-left toast; Block runs show **`Running (Block): …`**.
+6. Run the new Block for real via `browser send` - prove it works before moving to the next
    pattern, exactly like any other real Block.
-6. Ask the user a clarifying question only when something genuinely can't be resolved from
+7. Ask the user a clarifying question only when something genuinely can't be resolved from
    the DOM alone (is this instance local or published? does a downstream integration exist?)
-   - don't ask about things `auto dom` can just answer.
+   - don't ask about things `browser dom` can just answer.
 
 ## Real gotchas specific to cold-start authoring
 
 - **`discoverGraph`'s per-file import errors are mostly silent.** A malformed newly-written
   Block file can simply vanish from the graph with no error printed anywhere obvious - if a
-  Block you just wrote doesn't show up after `auto reload`, check `waygraph graph`'s own
+  Block you just wrote doesn't show up after `browser reload`, check `waygraph graph`'s own
   `skipped` list and the file's syntax directly, don't assume it just needs more time.
 - **`defineAssertBlock` needs no `<In, Out>` generic to type-check** (`checkpoint: "X"` alone
   is enough for TypeScript to infer it) - but older/naive static-graph discovery logic may
@@ -47,9 +61,9 @@ permanent, reusable, typed coverage instead of leaving nothing behind.
 - **A `<p>`/text-based selector often needs scoping**, not just a class name - a sibling
   "chat list item" and "message preview" frequently share the exact same CSS classes in real
   apps, distinguished only by DOM position (first vs second child of a specific wrapper).
-  Confirm via `auto dom --mode full` before assuming a class alone is unique enough.
+  Confirm via `browser dom --mode full` before assuming a class alone is unique enough.
 - **Confirm a selector count, not just its first match**, when building anything the menu
-  will expand into multiple live rows (an `instanceOptions`-driven Block) - `auto dom`'s
+  will expand into multiple live rows (an `instanceOptions`-driven Block) - `browser dom`'s
   default read can silently show only one match even when several exist; check the real
   page count (e.g. via a scoped debug script) before assuming a plain `.first()` is safe
   long-term. A `.first()`-shaped Block is a legitimate STARTING point for a page that only
@@ -57,6 +71,7 @@ permanent, reusable, typed coverage instead of leaving nothing behind.
   `defineEffectBlock` (see the `waygraph-pilot` skill and
   `examples/saucedemo/.../nav-item-detail.block.ts` for the real pattern) once a second real
   row genuinely exists to pick between, not before.
-- **Prefer the real Pilot overlay over ad hoc status output** when driving a
-  `--non-headless` session someone might be watching - it auto-updates on every menu build,
-  point a human at the badge/panel instead of re-inventing status reporting.
+- **Prefer the real Pilot overlay over ad hoc status output** when driving a headful session
+  someone might be watching - badge/panel on `about:blank` and after every navigation; raw
+  ops toast **`Running (no Block): …`**. Point a human at the badge instead of re-inventing
+  status reporting.

package/templates/skills/waygraph-convention.skill.md

@@ -24,6 +24,14 @@ against a live site, use `--skill-pilot-blind`.
    an explicit type argument when it sits between two specifically-typed Blocks in a Flow.
 5. **`requires` = externally supplied.** A key an earlier Block in the same chain produces
    is never listed under `requires` - preflight checks the whole chain up front.
+6. **Keep Checkpoints typed — never `Checkpoint<string>`.** Block helpers take concrete
+   Checkpoint types from `src/states/` (e.g. `defineMethodBlock<LoginPage, LoginPage>`).
+   Wildcard `Checkpoint<string>` compiles but kills graph honesty; `waygraph check` / `waygraph typecheck` warn.
+   Same for `defineAssertBlock({…})` without an explicit type arg — use
+   `defineAssertBlock<YourCheckpoint>({…})`.
+7. **One input/action per Method Block.** No block that `.fill()`s two fields or `.fill()` + `.click()` in one
+   `act()` — split like saucedemo login (`fill-username`, `fill-password`, `submit-login`). Opt out per file:
+   `// waygraph-ignore: multi-input` or `// waygraph-ignore-practices`.
 
 ## Block kinds (file convention)
 
@@ -84,7 +92,9 @@ the site's `*-web/` tree. Browser-driven (DOM / iframe Traits), not the catcher'
 ## Verify before you call it done
 
 ```bash
-npx waygraph check .          # orphans + nav-escape + inline-selector warnings
+npx waygraph check .          # orphans + nav-escape + inline-selector + bad-practice warnings
+npx waygraph typecheck .      # tsc --noEmit + bad-practice warnings (npm run typecheck)
+npx waygraph check --no-practices .   # skip bad-practice scan only
 npx waygraph map .            # exit 1 if src/map/ folder path != real static url
 npx waygraph validate .       # every .flow.ts loads
 npx waygraph graph .          # nodes/edges/skipped/orphans - counts should make sense

package/templates/skills/waygraph-pilot.skill.md

@@ -9,10 +9,37 @@ the reasoning agent. Every multi-step decision (which Block to run next, when a
 `reach` vs `send`, when to fall back to raw primitives) is yours to make, turn by turn, by
 reading each `auto status`/`auto send` response.
 
+## auto vs browser vs pilot (do not conflate them)
+
+| Layer | Command | What it is |
+|-------|---------|------------|
+| **auto** | `waygraph auto` | Interactive explore (picker / `--cli` menu). **Not** a persistent agent browser. |
+| **browser** | `waygraph browser start` | New persistent Playwright session — **headful by default**, **about:blank by default**. `waygraph browser` prints subcommands; `browser sessions` lists live ones. |
+| **pilot** | `waygraph pilot start` | Bootstrap only: `browser start` + whole-project `graph` + starting `snapshot` in one JSON payload. Does not plan or act. |
+
+Session control (`send`, `status`, `highlight`, `dom`, …) works on **`auto`**, **`browser`**, and **`pilot`** — same socket, same session id:
+
+```
+waygraph browser send <sessionId> "<pick>"     # same as auto send / pilot send
+```
+
+**Session lifecycle — list first, then attach or start:**
+
+```
+waygraph browser sessions [project]          # what's live right now
+waygraph browser attach <sessionId>          # terminal picker on an existing session
+waygraph browser stop <sessionId|--all>      # shut one down when done
+waygraph pilot attach <sessionId>          # graph + snapshot for an existing session
+```
+
+`browser start` / `pilot start` always open a **new** session. Check `browser sessions` before starting another.
+
 ## Starting a session
 
 ```
 waygraph pilot start                      # bootstraps: {sessionId, socketPath, headless, graph, snapshot}
+waygraph browser start [--inject path] [--goto <url>] [--cli]  # new browser session; --cli opens terminal picker
+waygraph pilot start [--cli]              # --cli opens terminal picker after bootstrap JSON
 waygraph auto status <sessionId>          # re-read the live menu, no side effects
 waygraph auto send <sessionId> "<pick>"   # run exactly one Block (by menu index or name)
 waygraph auto reach <sessionId> <Checkpoint>  # path-find + run a whole route in one call
@@ -23,6 +50,47 @@ waygraph auto highlight <sessionId> '<json>'  # paint rings/todos on the live pa
 just what's reachable from here - use it to plan several steps ahead before you start
 sending picks.
 
+## Bad practices (`waygraph check` / `waygraph typecheck`)
+
+Run `waygraph typecheck .` (or `npm run typecheck`) — runs `tsc --noEmit` then bad-practice warnings.
+`waygraph check` includes the same practice scan plus nav/orphan/selector hygiene.
+Use `--no-practices` on either command to skip the practice scan.
+
+Patterns warned (does not fail `check`; fails `typecheck` only when `tsc` fails):
+
+- **`Checkpoint<string>` in Block generics** — e.g. `defineMethodBlock<Checkpoint<string>, …>` instead of a project Checkpoint type from `src/states/`.
+- **`defineAssertBlock({…})` without an explicit type arg** — use `defineAssertBlock<YourCheckpoint>({…})` so `defineFlow` typing stays honest.
+- **Multiple `.fill()` in one Method** — split into one Block per input (fill-username, fill-password, …).
+- **`.fill()` + `.click()` in one Method** — split fill and submit into separate Blocks.
+
+Opt out per file: `// waygraph-ignore-practices` or `// waygraph-ignore: multi-input, combined-action`.
+
+Fix these before adding more Blocks; wildcard Checkpoints hide real graph edges from the type checker.
+
+## Coverage gaps on the live page (`auto console`)
+
+After `auto status` / `auto send`, read `waygraph auto console <sessionId>` — the session warns once per page load about:
+
+- **Unmapped hrefs** — same-origin `<a href>` paths with no `defineNavBlock` URL.
+- **Unmapped buttons** — visible `button` / `[role=button]` / submit inputs with no Method or NavClick selector in the Block library.
+
+Example warnings:
+
+```
+[waygraph] unmapped nav link on this page: /settings - no NavBlock covers this URL; add defineNavBlock
+[waygraph] unmapped button on this page: #save-draft - no Method/NavClick Block selector matches; consider defineMethodBlock or defineNavClickBlock
+```
+
+When you see these, author the missing Block — do not keep clicking raw primitives.
+
+## Session reachability (multi-pane / wrong cwd)
+
+Session ids are registered globally under `/tmp/waygraph-auto/` as well as `<project>/.waygraph-auto/`. If `auto status` says unreachable:
+
+1. Run `waygraph pilot sessions` from the project that started the browser — reuse the id, do not spawn again.
+2. Or `waygraph pilot attach <sessionId>` for graph + snapshot without a new browser.
+3. Stale metadata (crashed pid) is pruned automatically — start fresh only when the pid is actually gone.
+
 ## Highlight fixtures (Pilot supports them — use `auto highlight`)
 
 **Yes, Pilot paints rings/todos/zoom/device on the live page.** That is what
@@ -73,7 +141,7 @@ Supported fields (demo parity):
 - `clear`: true drops rings/todos/focus/zoom badge
 
 - `tone`: all demo tones - `planned` | `auto` | `info` | `warning` | `danger` | `success` | `orange` (aliases like `error`/`blue`/`green` work too)
-- Bottom-left toast shows `Highlighting: …` (same strip as `Running (Dom): …`)
+- Bottom-left toast shows `Highlighting: …` (same strip as `Running (no Block): …` for raw ops)
 - Missing selectors are listed in the JSON response (`missing`) - not a hard failure
 - Does not replace `auto send` - paint, then run the real Block
 
@@ -100,9 +168,8 @@ only ever be as good as the project's own Block coverage: if two Checkpoints sha
 and nothing in their `verify` arrays tells them apart, `resync` will confidently report the
 wrong one. This is a coverage gap in the project's Blocks, not a `resync` bug - if you hit
 one, fix the ambiguity (add a second, concrete `Trait.visible` condition that's only true in
-one of the two states - see `AppHomePageBlock`/`InPoolPageBlock` in a real veciro-waygraph
-example of exactly this: the same `/app` route, split by presence of a "Join Pool" vs
-"Leave pool" button).
+one of the two states — e.g. the same route with different visible buttons that distinguish
+pool membership vs home).
 
 ## Rule 3: mem is intent, Checkpoint is reality - never blur them