waygraph 0.15.9 → 0.15.11

package/README.md

@@ -920,6 +920,7 @@ really a Nav/Page/Assert/Method from this package's own factories.
 | 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`) |
+| Print a packaged agent skill to stdout | `npx waygraph --skill` (list) / `--skill-pilot` / `--skill-pilot-blind` / `--skill-convention` |
 | Add waygraph to an existing repo | `npm install waygraph @playwright/test` |
 
 **Scaffold is not hidden inside waygraph alone** - the offline starter also ships as
@@ -1034,6 +1035,7 @@ Flows are files (0.10.5+):
 | Waygraph Map enforcement (verbatim url-vs-folder, exits 1 on a violation) | `waygraph map [project]` |
 | Graph crawl | `waygraph traverse [project] --parallel N --min-edge-coverage 80%` |
 | Coding-agent defs | `waygraph agent-dive --loop claude` |
+| Print packaged skills | `waygraph --skill` / `--skill-pilot` / `--skill-pilot-blind` / `--skill-convention` |
 | 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"`.

package/dist/agent-dive.d.ts

@@ -19,6 +19,17 @@ export declare function loadAgentSpecs(): AgentSpec[];
  * body frontmatter shape `parseAgentSpec` already parses.
  */
 export declare function loadSkillSpecs(): AgentSpec[];
+/** CLI flag -> packaged skill file stem (under templates/skills/). */
+export declare const SKILL_FLAG_MAP: {
+    readonly "--skill-pilot": "waygraph-pilot";
+    readonly "--skill-pilot-blind": "waygraph-blind-pilot";
+    readonly "--skill-convention": "waygraph-convention";
+};
+export type SkillFlag = keyof typeof SKILL_FLAG_MAP;
+/** Raw skill markdown (frontmatter + body), as shipped in the package. */
+export declare function readSkillMarkdown(stem: string): string;
+/** Print `--skill` index (available flags + one-line descriptions). */
+export declare function printSkillIndex(): void;
 export interface AgentDiveOptions {
     loop: AgentDiveLoop;
     projectDir: string;

package/dist/agent-dive.js

@@ -85,6 +85,34 @@ export function loadSkillSpecs() {
         .sort()
         .map((f) => parseAgentSpec(join(dir, f)));
 }
+/** CLI flag -> packaged skill file stem (under templates/skills/). */
+export const SKILL_FLAG_MAP = {
+    "--skill-pilot": "waygraph-pilot",
+    "--skill-pilot-blind": "waygraph-blind-pilot",
+    "--skill-convention": "waygraph-convention",
+};
+/** Raw skill markdown (frontmatter + body), as shipped in the package. */
+export function readSkillMarkdown(stem) {
+    const path = join(skillsTemplateDir(), `${stem}.skill.md`);
+    if (!existsSync(path)) {
+        throw new Error(`waygraph: skill template missing at ${path}`);
+    }
+    const raw = readFileSync(path, "utf-8");
+    return raw.endsWith("\n") ? raw : raw + "\n";
+}
+/** Print `--skill` index (available flags + one-line descriptions). */
+export function printSkillIndex() {
+    const skills = loadSkillSpecs();
+    const byName = new Map(skills.map((s) => [s.name, s]));
+    console.log("waygraph skills (print full text with the matching flag):\n");
+    for (const [flag, stem] of Object.entries(SKILL_FLAG_MAP)) {
+        const spec = byName.get(stem);
+        const desc = spec?.description ?? stem;
+        console.log(`  npx waygraph ${flag}`);
+        console.log(`    ${desc}\n`);
+    }
+    console.log("Also: npx waygraph agent-dive --loop claude  # write .claude/skills/*/SKILL.md");
+}
 function writeFileLogged(path, content, kind) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, content.endsWith("\n") ? content : content + "\n");

package/dist/cli.d.ts

@@ -8,6 +8,7 @@
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
+ * Skills: --skill / --skill-pilot / --skill-pilot-blind / --skill-convention
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.

package/dist/cli.js

@@ -8,6 +8,7 @@
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
+ * Skills: --skill / --skill-pilot / --skill-pilot-blind / --skill-convention
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
@@ -22,7 +23,7 @@ import { checkMap } from "./map-check.js";
 import { runAutoExplore } from "./auto-explore-run.js";
 import { pilotStart } from "./pilot.js";
 import { spawnDetachedSession, requestSession, runAttachLoop, runAutoServeCommand, } from "./auto-session-ipc.js";
-import { runAgentDive } from "./agent-dive.js";
+import { runAgentDive, printSkillIndex, readSkillMarkdown, SKILL_FLAG_MAP, } from "./agent-dive.js";
 import { runTraverse } from "./traverse-run.js";
 import { parseMinEdgeCoverage } from "./traverse-coverage.js";
 import { isFileSelectToken, parseBlocksSelect, } from "./blocks-select.js";
@@ -7266,6 +7267,12 @@ Also:
                  try auto:cli / --cli      Terminal menu instead
                  try auto --headed         Same as try auto (compat)
 
+Skills (print packaged skill markdown to stdout - for agents / paste):
+  waygraph --skill                         List available skills
+  waygraph --skill-pilot                   Drive an existing Block graph
+  waygraph --skill-pilot-blind             Cold-start: raw ops + author Blocks
+  waygraph --skill-convention              Block/Map authoring conventions
+
 Examples:
   waygraph list                                          # file → export map
   waygraph run src/flows/shop.flow.ts --data '{...}'
@@ -7295,6 +7302,15 @@ async function main() {
     if (!command || command === "--help" || command === "-h") {
         usage();
     }
+    if (command === "--skill") {
+        printSkillIndex();
+        process.exit(0);
+    }
+    if (command && command in SKILL_FLAG_MAP) {
+        const stem = SKILL_FLAG_MAP[command];
+        process.stdout.write(readSkillMarkdown(stem));
+        process.exit(0);
+    }
     switch (command) {
         case "list": {
             const proj = resolve(args[1] ?? process.cwd());

package/package.json

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

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

@@ -0,0 +1,109 @@
+---
+name: waygraph-convention
+description: Author or review waygraph Blocks/Flows under the consumer + Waygraph Map conventions - use when writing new Blocks, migrating folder layout, or answering "how should this project be organized," not when driving an already-built session (use waygraph-pilot / waygraph-blind-pilot for that).
+---
+
+Waygraph convention is how Blocks are *shaped and placed*, not how a live session is
+driven. Print this skill, then write or rearrange files so `waygraph check` / `waygraph map`
+stay clean. For operating an existing graph, use `--skill-pilot`. For cold-start authoring
+against a live site, use `--skill-pilot-blind`.
+
+## Hard rules (not style preferences)
+
+1. **One distinct action per Block.** Fill and submit are two Blocks. A login form is
+   `fill-username` (self-loop) + `fill-password` (self-loop) + `submit-login` (transition),
+   never one Method that "fills and logs in." Same split for checkout fields. Canonical
+   shape: `examples/saucedemo/src/blocks/saucedemo-web/methods/`.
+2. **Navigation only inside Nav.** `page.goto` / NavBlock `click` live in
+   `defineNavBlock` / `defineNavClickBlock` only. Method/Effect `act` uses ActionPage
+   (no goto) even when the app changes URL as a side effect of a button click.
+3. **Selectors in `*Sel`, never inline.** DOM strings live in a `*Sel` next to the page
+   (static + `(id) => …`). Mem keys store values, not selectors. `waygraph check` warns on
+   inline selector literals in `Trait.visible` / `Trait.text`.
+4. **Assert-only = `defineAssertBlock`.** Self-loop, no hand-written `act`/`resolve`. Pass
+   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.
+
+## Block kinds (file convention)
+
+| Kind | File | Helper | `page.goto`? |
+|------|------|--------|--------------|
+| Page | `*.page.block.ts` / `_page.block.ts` | `definePageBlock` | Optional deep-link |
+| Nav | `nav-*.block.ts` / `_nav.block.ts` | `defineNavBlock` / `defineNavClickBlock` | Yes (`url` XOR `click`) |
+| Effect | `*.effect.block.ts` in `methods/` / `_methods/` | `defineEffectBlock` | No |
+| Method | `*.method.block.ts` in `methods/` / `_methods/` | `defineMethodBlock` | No |
+| Assert | with Method/Effect peers | `defineAssertBlock` | No |
+
+Effects that appear in `waygraph auto` menus need `instanceOptions` that scan the live DOM
+(or mem) for labeled rows.
+
+## Two layouts (same Block kinds)
+
+**Freeform ("manual mode")** - still valid; real consumers depend on it:
+
+```text
+src/blocks/<site>/                 # THIS FOLDER IS URL "/"
+  nav-login.block.ts
+  methods/fill-username.method.block.ts
+  inventory/                       # /inventory.html
+    inventory.page.block.ts
+    methods/add-to-cart.effect.block.ts
+```
+
+Folders mirror real app routes (Next.js `app/` page routes). Do **not** invent parallel
+families like `root/`, `landing/`, or `shell/nav/` that are not real URLs. `/` lives at the
+namespace root.
+
+**Waygraph Map** - forced convention when `src/map/` exists:
+
+```text
+src/map/
+  (app_base)/                      # organizational group only - never part of a Checkpoint tag
+    dashboard/                     # must verbatim-match the real URL path (/dashboard)
+      _page.block.ts
+      _nav.block.ts
+      _sel.ts
+      _methods/click-widget.block.ts
+  (external)/                      # cross-origin (mailpit, etc.) - same shape
+    docs/
+      _page.block.ts
+      _nav.block.ts
+      _sel.ts
+```
+
+- `(group)` parentheses and leading-underscore segments (`_methods/`, `_page…`) are
+  **not** URL segments. `waygraph map` excludes them when checking folder-vs-URL.
+- A bare non-underscore folder always means a real child Checkpoint/URL segment.
+- Prefer `map()` over a hand-assembled `defineFlow([start, ...])` when wiring Map Blocks -
+  it rejects Blocks that didn't come from a real factory (no silent teleporting).
+
+Mail / external tools: under `*-external/<tool>/` or `map/(external)/<tool>/`, never under
+the site's `*-web/` tree. Browser-driven (DOM / iframe Traits), not the catcher's REST API.
+
+## Verify before you call it done
+
+```bash
+npx waygraph check .          # orphans + nav-escape + inline-selector warnings
+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
+npm run typecheck             # when the consumer has it
+```
+
+`waygraph check` should report zero nav warnings. Orphan Blocks (not in any `.flow.ts`)
+are still runnable in Pilot's live menu - orphan status only blocks
+`auto --blocks <From> <To>` pathfinding.
+
+## Related skills (print via CLI)
+
+```bash
+npx waygraph --skill                 # list
+npx waygraph --skill-pilot           # drive an existing Block graph
+npx waygraph --skill-pilot-blind     # cold-start: raw ops + author Blocks as you go
+npx waygraph --skill-convention      # this file
+```
+
+Worked freeform example: `examples/saucedemo/docs/CONVENTION.md`.
+Map design history: `openspec/changes/waygraph-map/`.
+Agent personas (author/planner/healer): `npx waygraph agent-dive --loop claude`.

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

@@ -1,6 +1,6 @@
 ---
 name: waygraph-pilot
-description: Drive an existing waygraph Block graph as a real agent - use when a task needs to operate a web app that already has waygraph Blocks written for it (login, checkout, matching, chat, admin flows, etc.), not when writing new Blocks from scratch.
+description: Drive an existing waygraph Block graph as a real agent - use when a task needs to operate a web app that already has waygraph Blocks written for it (login, checkout, matching, chat, admin flows, etc.), not when writing new Blocks from scratch. Includes how to paint demo-parity fixture highlights in Pilot via `auto highlight` (pilot:watch / --non-headless).
 ---
 
 Waygraph Pilot is not a planner you call and get an answer from - `pilot start` only
@@ -23,15 +23,42 @@ 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.
 
-## Highlight fixtures (agent-sent narration)
+## Highlight fixtures (Pilot supports them — use `auto highlight`)
 
-Block `stubBefore` / `withHighlightFixtures` only paint in `waygraph demo`. In Pilot they
-land in `auto trace` as metadata but do **not** draw on the page. When a human is watching
-a headful session (or you want to narrate intent before a send), paint yourself with the
-same fixture surface:
+**Yes, Pilot paints rings/todos/zoom/device on the live page.** That is what
+`waygraph auto highlight` is for. It works on headful `pilot start --non-headless`
+(consumer `pilot:watch`) and on headless sessions alike. Same fixture surface as
+`waygraph demo` (rings, todos, focus veil, zoom badge, device viewport) — proven in
+`tests/cli/auto-session.spec.ts` ("auto highlight: paints agent fixture rings…").
+
+**Do not claim Pilot "doesn't support fixture highlights."** That is wrong. The only
+thing that differs from demo is *who* triggers the paint:
+
+| Mode | Who paints | How |
+|------|------------|-----|
+| `waygraph demo` | Engine, automatically | Block `stubBefore` / `stubAfter` / `withHighlightFixtures` run each step |
+| Pilot / `auto --detach` | **You (the agent)** | `waygraph auto highlight <sessionId> '<json>'` before (or between) sends |
+
+Block-authored `stubBefore` / `withHighlightFixtures` still exist on Blocks in Pilot —
+they show up in `auto trace` as metadata — but they do **not** auto-draw. You re-express
+the same intent with `auto highlight` (copy selectors/labels from the Block stubs or from
+`auto dom`). Paint, then `auto send` the real Block. Clear when done.
 
 ```
+# Headful watch session (rings visible to a human audience):
+waygraph pilot start --non-headless
+# → note sessionId from the bootstrap JSON
+
 waygraph auto highlight <sessionId> '{"rings":[{"selector":"#user-name","label":"Username","tone":"planned","focus":true},{"selector":"#password","label":"Password","tone":"info","detail":"secret"}],"todos":["Fill username","Fill password","Submit"],"todoIndex":0,"zoom":1.5,"holdMs":0}'
+waygraph auto send <sessionId> fill-username
+waygraph auto highlight <sessionId> '{"rings":[{"selector":"#password","label":"Password","tone":"planned","focus":true}],"todoIndex":1,"holdMs":0}'
+waygraph auto send <sessionId> fill-password
+waygraph auto highlight <sessionId> '{"clear":true}'
+```
+
+More shapes:
+
+```
 waygraph auto highlight <sessionId> '{"device":"mobile","rings":[{"selector":".inventory_item:last-child","label":"Last item","zoom":1.6,"focus":true}],"holdMs":30000}'
 waygraph auto highlight <sessionId> '{"clear":true}'
 ```

package/examples/saucedemo/.waygraph-auto/03710cfc.json

@@ -1,8 +0,0 @@
-{
-  "sessionId": "03710cfc",
-  "socketPath": "/tmp/waygraph-auto/03710cfc.sock",
-  "pid": 255515,
-  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
-  "startedAt": "2026-09-21T09:37:58.750Z",
-  "headless": false
-}

package/examples/saucedemo/.waygraph-auto/605d965b.json

@@ -1,8 +0,0 @@
-{
-  "sessionId": "605d965b",
-  "socketPath": "/tmp/waygraph-auto/605d965b.sock",
-  "pid": 247729,
-  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
-  "startedAt": "2026-09-21T09:34:04.318Z",
-  "headless": false
-}

package/examples/saucedemo/.waygraph-auto/6b667734.json

@@ -1,8 +0,0 @@
-{
-  "sessionId": "6b667734",
-  "socketPath": "/tmp/waygraph-auto/6b667734.sock",
-  "pid": 245167,
-  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
-  "startedAt": "2026-09-21T09:33:13.876Z",
-  "headless": false
-}