waygraph 0.15.51 → 0.15.53

package/README.md

@@ -16,7 +16,14 @@ export const SubmitLoginBlock = defineMethodBlock<LoginPage, LoggedIn>({
 });
 
 // A Flow = Blocks in order.
-export const loginFlow = engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]);
+export const loginFlow = engine
+  .map()
+  .start()
+  .gotoPage(NavLoginBlock)
+  .method(FillUsernameBlock)
+  .method(FillPasswordBlock)
+  .method(SubmitLoginBlock)
+  .end();
 ```
 
 ## Try it in 60 seconds

package/dist/analysis/graph.d.ts

@@ -13,7 +13,7 @@ export interface WaygraphEdge {
     block: string;
     /** Path the Block was discovered in, relative to the project root. */
     file: string;
-    /** `"*"` for a NavBlock - reachable from anywhere, by design. */
+    /** `"*"` for a NavBlock - reachable from anywhere, unless it declares `from` (then one edge per tag). */
     from: string;
     to: string;
     kind: "nav" | "action";

package/dist/analysis/graph.js

@@ -53,21 +53,10 @@ function discoverBlocks(projectDir) {
 function discoverFlows(projectDir) {
     return walkDir(projectDir, /\.flow\.ts$/);
 }
-/** Block export ids listed inside any `defineFlow([...])` array in flow files. */
+/** Block export ids a flow file uses: every identifier outside its import lines (a Block can sit in the array or in a local like `const AddShown = AddBlock.stubAfter(...)`). */
 function extractFlowBlockRefs(flowSrc) {
-    const refs = [];
-    const re = /defineFlow(?:<[\s\S]*?>)?\s*\(\s*\[([\s\S]*?)\]\s*\)/g;
-    let m;
-    while ((m = re.exec(flowSrc)) !== null) {
-        for (const part of m[1].split(",")) {
-            const trimmed = part.trim().replace(/\/\/.*$/, "").trim();
-            const id = trimmed.split(/\s+/)[0];
-            if (!id || id === "start" || id === "end")
-                continue;
-            refs.push(id);
-        }
-    }
-    return refs;
+    const body = flowSrc.replace(/^\s*import[\s\S]*?;\s*$/gm, "").replace(/\/\/.*$/gm, "");
+    return body.match(/[A-Za-z_$][\w$]*/g) ?? [];
 }
 function exportNameToBlockName(exportName) {
     const base = exportName.replace(/Block$/, "");
@@ -420,7 +409,13 @@ export async function discoverGraph(projectDir, opts) {
                         const deepLink = !isPage ||
                             exported.__waygraphPageDeepLink === true;
                         if (deepLink) {
-                            edges.push({ block: blockName, file: relFile, from: "*", to, kind: "nav" });
+                            // `from: [...]` on the Nav = only those Checkpoints; otherwise reachable from anywhere.
+                            const navFrom = exported.__waygraphNavFrom;
+                            for (const from of navFrom ?? ["*"]) {
+                                if (from !== "*")
+                                    nodeTags.add(from);
+                                edges.push({ block: blockName, file: relFile, from, to, kind: "nav" });
+                            }
                         }
                     }
                     catch {

package/dist/analysis/map-check.d.ts

@@ -1,9 +1,9 @@
-export interface MapViolation {
+interface MapViolation {
     file: string;
     block: string;
     reason: string;
 }
-export interface MapNode {
+interface MapNode {
     block: string;
     checkpoint: string | undefined;
     file: string;
@@ -16,3 +16,4 @@ export interface MapCheckResult {
     violations: MapViolation[];
 }
 export declare function checkMap(projectDir: string): Promise<MapCheckResult>;
+export {};

package/dist/analysis/practices-check.d.ts

@@ -11,4 +11,3 @@ export interface PracticeCheckOptions {
 }
 export declare function collectPracticeWarnings(projectDir: string, walkDir: (dir: string, re: RegExp) => string[], opts?: PracticeCheckOptions): PracticeWarning[];
 export declare function practiceKindLabel(kind: PracticeKind): string;
-export declare function formatPracticeWarnings(projectDir: string, warnings: PracticeWarning[]): string[];

package/dist/analysis/practices-check.js

@@ -193,16 +193,3 @@ export function practiceKindLabel(kind) {
         }
     }
 }
-export function formatPracticeWarnings(projectDir, warnings) {
-    const lines = [];
-    for (const w of warnings) {
-        lines.push(`waygraph practices: ${w.file} (${practiceKindLabel(w.kind)}) — ${w.detail}`);
-    }
-    if (warnings.length === 0) {
-        lines.push(`waygraph practices: no bad-practice patterns under ${projectDir}`);
-    }
-    else {
-        lines.push(`waygraph practices: ${warnings.length} bad-practice warning${warnings.length === 1 ? "" : "s"}`);
-    }
-    return lines;
-}

package/dist/auto-session/session.d.ts

@@ -16,7 +16,7 @@ export declare class AutoSession {
     private library;
     private readonly mem;
     private readonly engine;
-    private readonly browser;
+    private readonly closeBrowser;
     private readonly context;
     private page;
     private readonly startUrl;

package/dist/auto-session/session.js

@@ -9,7 +9,8 @@ import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from
 import { runStubPhase } from "../highlights.js";
 import { verboseLog } from "./verbose-log.js";
 import { findBlockPathDetailed } from "../analysis/graph.js";
-import { chromiumExecutablePath } from "../browser-path.js";
+import { configuredExtensions } from "../config.js";
+import { chromiumExecutablePath, launchContext } from "../browser.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup
  * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a
@@ -26,7 +27,7 @@ export class AutoSession {
     library;
     mem;
     engine;
-    browser;
+    closeBrowser;
     context;
     page;
     startUrl;
@@ -38,7 +39,7 @@ export class AutoSession {
     knownInteractionSelectors;
     headless;
     lastOverlayInfo = null;
-    constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
+    constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
         this.projectDir = projectDir;
         this.inject = inject;
         this.blocksSelect = blocksSelect;
@@ -46,7 +47,7 @@ export class AutoSession {
         this.library = library;
         this.mem = mem;
         this.engine = engine;
-        this.browser = browser;
+        this.closeBrowser = closeBrowser;
         this.context = context;
         this.page = page;
         this.startUrl = startUrl;
@@ -85,13 +86,17 @@ export class AutoSession {
         };
         if (executablePath)
             launchOpts.executablePath = executablePath;
-        const browser = await chromium.launch(launchOpts);
         const contextOpts = {
             viewport: headless ? { width: 1280, height: 720 } : null,
         };
         if (baseURL)
             contextOpts.baseURL = baseURL;
-        const context = await browser.newContext(contextOpts);
+        const { close: closeBrowser, context } = await launchContext({
+            launcher: chromium,
+            launch: launchOpts,
+            context: contextOpts,
+            extensions: await configuredExtensions(init.projectDir),
+        });
         await installPersistentPilotOverlay(context);
         const page = await context.newPage();
         instrumentPilotActions(page, headless ? 0 : 450);
@@ -103,7 +108,7 @@ export class AutoSession {
             await page.goto("about:blank").catch(() => { });
         }
         const knownInteractionSelectors = collectKnownInteractionSelectors(init.projectDir, library, init.inject);
-        const session = new AutoSession(init.projectDir, init.inject, init.blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, init.sessionId, knownInteractionSelectors, headless);
+        const session = new AutoSession(init.projectDir, init.inject, init.blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, init.sessionId, knownInteractionSelectors, headless);
         page.on("load", () => {
             void session.repaintOverlayAfterNavigation();
         });
@@ -709,6 +714,6 @@ export class AutoSession {
     }
     async close() {
         await this.context.close();
-        await this.browser.close();
+        await this.closeBrowser();
     }
 }

package/dist/blocks-select.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Shared `--blocks` select grammar (RFC Phase C).
+ *
+ * - `/pattern/`  -> regex on relative file path OR block name
+ * - has `*`/`**` -> glob on relative file path (POSIX-ish)
+ * - otherwise    -> bare token (flow export / checkpoint / block name) — caller decides
+ */
 export type BlocksSelectKind = "regex" | "glob" | "bare";
 export interface BlocksSelect {
     kind: BlocksSelectKind;
@@ -16,7 +23,3 @@ export declare function matchBlocksSelect(select: BlocksSelect, opts: {
     relFile: string;
     blockName?: string;
 }): boolean;
-export declare function filterByBlocksSelect<T extends {
-    file: string;
-    block?: string;
-}>(items: T[], select: BlocksSelect | undefined, projectDir: string): T[];

package/dist/blocks-select.js

@@ -5,7 +5,6 @@
  * - has `*`/`**` -> glob on relative file path (POSIX-ish)
  * - otherwise    -> bare token (flow export / checkpoint / block name) — caller decides
  */
-import { relative } from "node:path";
 /** True when the token is file-select (glob/regex), not a bare flow/checkpoint name. */
 export function isFileSelectToken(token) {
     if (!token)
@@ -70,16 +69,3 @@ export function matchBlocksSelect(select, opts) {
         return true;
     return false;
 }
-export function filterByBlocksSelect(items, select, projectDir) {
-    if (!select)
-        return items;
-    return items.filter((it) => {
-        const relFile = it.file.startsWith(projectDir)
-            ? relative(projectDir, it.file)
-            : it.file;
-        return matchBlocksSelect(select, {
-            relFile: relFile.replace(/\\/g, "/"),
-            ...(it.block !== undefined ? { blockName: it.block } : {}),
-        });
-    });
-}

package/dist/browser.d.ts

@@ -0,0 +1,27 @@
+import type { Browser, BrowserContext, BrowserContextOptions, BrowserType, LaunchOptions } from "@playwright/test";
+/**
+ * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
+ * falls back to Playwright's bundled Chromium with a one-time warning instead of failing the run.
+ */
+export declare function chromiumExecutablePath(): string | undefined;
+/** Unpacked extension directories, as resolved by `resolveExtensions` - also what `WAYGRAPH_EXTENSIONS` carries to child processes. */
+export declare function extensionPathsFromEnv(): string[];
+export interface LaunchedContext {
+    /** Null for a persistent (extension) context. */
+    browser: Browser | null;
+    context: BrowserContext;
+    /** Closes the context and the browser (and the throwaway profile when extensions are loaded). */
+    close(): Promise<void>;
+}
+/**
+ * Launches a browser and its first context. With `extensions` it uses a persistent context, the only
+ * way Chromium loads extensions: new headless (`channel: "chromium"`; the default headless shell
+ * ignores them) and Playwright's own Chromium (branded Chrome 137+ ignores `--load-extension`).
+ * Extensions are not active in extra contexts made with `browser.newContext()`.
+ */
+export declare function launchContext(opts: {
+    launcher: BrowserType;
+    launch: LaunchOptions;
+    context?: BrowserContextOptions;
+    extensions?: readonly string[];
+}): Promise<LaunchedContext>;

package/dist/browser.js

@@ -0,0 +1,62 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+let warned = false;
+/**
+ * CHROME_PATH / CHROMIUM_PATH, if set and the file exists. A stale path (browser uninstalled)
+ * falls back to Playwright's bundled Chromium with a one-time warning instead of failing the run.
+ */
+export function chromiumExecutablePath() {
+    const path = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    if (!path)
+        return undefined;
+    if (existsSync(path))
+        return path;
+    if (!warned) {
+        warned = true;
+        console.error(`waygraph: CHROME_PATH/CHROMIUM_PATH "${path}" does not exist - using Playwright's bundled Chromium`);
+    }
+    return undefined;
+}
+/** Unpacked extension directories, as resolved by `resolveExtensions` - also what `WAYGRAPH_EXTENSIONS` carries to child processes. */
+export function extensionPathsFromEnv() {
+    return (process.env.WAYGRAPH_EXTENSIONS ?? "").split(",").filter(Boolean);
+}
+/**
+ * Launches a browser and its first context. With `extensions` it uses a persistent context, the only
+ * way Chromium loads extensions: new headless (`channel: "chromium"`; the default headless shell
+ * ignores them) and Playwright's own Chromium (branded Chrome 137+ ignores `--load-extension`).
+ * Extensions are not active in extra contexts made with `browser.newContext()`.
+ */
+export async function launchContext(opts) {
+    const extensions = opts.extensions ?? [];
+    if (extensions.length === 0) {
+        const browser = await opts.launcher.launch(opts.launch);
+        const context = await browser.newContext(opts.context);
+        return { browser, context, close: () => browser.close() };
+    }
+    if (opts.launcher.name() !== "chromium")
+        throw new Error("waygraph: extensions only work in Chromium");
+    const list = extensions.join(",");
+    const { executablePath: _ignored, ...launch } = opts.launch;
+    const profile = mkdtempSync(join(tmpdir(), "waygraph-profile-"));
+    const context = await opts.launcher.launchPersistentContext(profile, {
+        ...launch,
+        ...opts.context,
+        ...(launch.headless === false ? {} : { channel: "chromium" }),
+        args: [...(launch.args ?? []), `--disable-extensions-except=${list}`, `--load-extension=${list}`],
+    });
+    // An extension's background worker registers its page hooks, so wait for it before the first navigation.
+    const hasWorker = extensions.some((dir) => JSON.parse(readFileSync(join(dir, "manifest.json"), "utf-8")).background?.service_worker !== undefined);
+    if (hasWorker && context.serviceWorkers().length === 0) {
+        await context.waitForEvent("serviceworker", { timeout: 10_000 }).catch(() => undefined);
+    }
+    return {
+        browser: context.browser(),
+        context,
+        close: async () => {
+            await context.close();
+            rmSync(profile, { recursive: true, force: true });
+        },
+    };
+}

package/dist/cli/flags.js

@@ -2,7 +2,7 @@
 import { basename, relative, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { walkDir } from "./discover.js";
-import { resolveBaseUrl } from "../config.js";
+import { loadWaygraphConfig, resolveBaseUrl } from "../config.js";
 function takeFlagValue(argv, i, a, flag) {
     if (a.startsWith(flag + "=")) {
         return { value: a.slice(flag.length + 1), nextI: i };
@@ -323,6 +323,8 @@ export { resolveBaseUrl };
  * Call after applyRunFlags so explicit flags already won.
  */
 export async function applyDemoDefaults(projectDir) {
+    // Config first: its defaults (headed, autoNext, pace...) must land before the demo defaults below fill the same variables.
+    await loadWaygraphConfig(projectDir);
     if (process.env.WAYGRAPH_STEP === undefined)
         process.env.WAYGRAPH_STEP = "1";
     if (process.env.WAYGRAPH_STEP === "1" && process.env.WAYGRAPH_HEADED === undefined) {

package/dist/cli/run-chain.js

@@ -1,4 +1,5 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { configuredExtensions } from "../config.js";
 import { expandSpecFlowFiles, resolveBaseUrl } from "./flags.js";
 import { join } from "node:path";
 import { rmSync, writeFileSync } from "node:fs";
@@ -45,6 +46,9 @@ export async function runChain(projectDir, spec) {
         if (resolved)
             process.env.WAYGRAPH_BASE_URL = resolved;
     }
+    const extensions = await configuredExtensions(projectDir);
+    if (extensions.length > 0)
+        process.env.WAYGRAPH_EXTENSIONS = extensions.join(",");
     const tsxEsm = import.meta.resolve("tsx/esm");
     const scriptPath = join(projectDir, `.waygraph-chain-${process.pid}.mjs`);
     writeFileSync(scriptPath, CHAIN_RUNNER_BOOTSTRAP);

package/dist/cli/usage.js

@@ -156,7 +156,9 @@ Primary (less is more):
                  --ff-disabled             Dispute: expand FF (alias --no-ff); blitz kept on those inners
                  --auto-play-video         Unattended + recorded: --auto-next + --video (+ step); headless
                  --auto-play-video-head    Same, but keep the browser visible (--non-headless)
-                 --video [dir]             Record .webm (demo: headless unless --non-headless)
+                 --video [dir]             Record .webm (demo: headless unless --non-headless);
+                                           default folder ~/Downloads/waygraph-videos/<project>,
+                                           or video.dir in the config / WAYGRAPH_VIDEO_DIR
                  --video-viewport WxH       Recording size (default demo: 1920x1080)
                  --title / --base-url
   waygraph run   [--blocks <flow|file|spec>]  Execute (no overlay unless --step)
@@ -184,6 +186,20 @@ Primary (less is more):
                                            has a trace - test report opens it.
 
 Also:
+  --config <name|file>   (any command) use another config instead of waygraph.config.ts, e.g.
+                 waygraph test --config staging   (config/waygraph.staging.config.ts)
+  --env <mode>   (any command) load .env.<mode> / .env.<mode>.local on top of .env, e.g.
+                 waygraph test --env staging   (default: NODE_ENV, else development)
+  waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff] [--skills]
+                                           Compare a project with the scaffold in this waygraph:
+                                           lists new and differing files and a stale waygraph
+                                           dependency. Dry run unless --apply; only the paths you
+                                           name are copied, differing files only with --overwrite.
+                                           --skills refreshes .agents/skills to this waygraph's.
+  waygraph extensions install [project] [--update]
+                                           Download the browser extensions listed in
+                                           waygraph.config.* (extensions: ["hoppscotch"]) into
+                                           the user cache; runs also fetch them on first use.
   waygraph list | nav | validate | check | typecheck | graph | init <name>
                  check/typecheck --no-practices  Skip bad-practice warnings
   waygraph map   [project]                 Waygraph Map convention enforcement: every static

package/dist/cli.js

@@ -15,6 +15,8 @@
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
  */
 import { SKILL_FLAG_MAP, printSkillIndex, readSkillMarkdown } from "./commands/agent-dive-scaffold.js";
+import { takeEnvFlag } from "./env-file.js";
+import { takeConfigFlag } from "./config.js";
 import { usage } from "./cli/usage.js";
 import { listCase, navCase } from "./commands/list.js";
 import { checkCase, typecheckCase, validateCase } from "./commands/check.js";
@@ -25,9 +27,13 @@ import { traverseCase } from "./commands/traverse.js";
 import { agentDiveCase } from "./commands/agent-dive.js";
 import { autoServeCase, sessionCase } from "./commands/session.js";
 import { tryCase } from "./commands/try.js";
+import { upgradeCase } from "./commands/upgrade.js";
+import { extensionsCase } from "./commands/extensions.js";
 import { mapCase } from "./commands/map.js";
-const args = process.argv.slice(2);
+const args = takeConfigFlag(takeEnvFlag(process.argv.slice(2)));
 const command = args[0];
+if (command)
+    process.env.WAYGRAPH_COMMAND = command;
 async function main() {
     if (!command || command === "--help" || command === "-h") {
         usage();
@@ -97,6 +103,12 @@ async function main() {
         case "map":
             await mapCase(args);
             break;
+        case "upgrade":
+            await upgradeCase(args);
+            break;
+        case "extensions":
+            await extensionsCase(args);
+            break;
         default:
             console.error(`waygraph: unknown command "${command}"`);
             process.exit(1);

package/dist/commands/agent-dive-scaffold.d.ts

@@ -1,24 +1,4 @@
 export type AgentDiveLoop = "claude" | "opencode" | "cursor" | "vscode";
-export interface AgentSpec {
-    name: string;
-    description: string;
-    model?: string;
-    color?: string;
-    tools: string[];
-    instructions: string;
-}
-/** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
-export declare function parseAgentSpec(filePath: string): AgentSpec;
-export declare function loadAgentSpecs(): AgentSpec[];
-/**
- * Claude Code Skills (`.claude/skills/<name>/SKILL.md`) - a different
- * mechanism than the agent persona files above: loadable instructions
- * triggered by task shape, not a persona. Claude-Code-specific (no
- * equivalent in the opencode/cursor/vscode loops), additive to the
- * `claude` loop only. Reuses the same `name: .../description: ...` +
- * 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";
@@ -28,6 +8,11 @@ export declare const SKILL_FLAG_MAP: {
 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;
+/** Every packaged skill as `.agents/skills/<name>/SKILL.md` (relative path + markdown), the cross-agent skills folder. */
+export declare function agentSkillFiles(): {
+    rel: string;
+    text: string;
+}[];
 /** Print `--skill` index (available flags + one-line descriptions). */
 export declare function printSkillIndex(): void;
 export interface AgentDiveOptions {

package/dist/commands/agent-dive-scaffold.js

@@ -16,7 +16,7 @@ function skillsTemplateDir() {
     return join(packageRoot(), "templates", "skills");
 }
 /** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
-export function parseAgentSpec(filePath) {
+function parseAgentSpec(filePath) {
     const raw = readFileSync(filePath, "utf-8");
     if (!raw.startsWith("---\n")) {
         throw new Error(`agent-dive: missing frontmatter in ${filePath}`);
@@ -58,7 +58,7 @@ export function parseAgentSpec(filePath) {
         instructions: body,
     };
 }
-export function loadAgentSpecs() {
+function loadAgentSpecs() {
     const dir = agentsTemplateDir();
     if (!existsSync(dir)) {
         throw new Error(`agent-dive: templates missing at ${dir}`);
@@ -76,7 +76,7 @@ export function loadAgentSpecs() {
  * `claude` loop only. Reuses the same `name: .../description: ...` +
  * body frontmatter shape `parseAgentSpec` already parses.
  */
-export function loadSkillSpecs() {
+function loadSkillSpecs() {
     const dir = skillsTemplateDir();
     if (!existsSync(dir))
         return [];
@@ -100,6 +100,13 @@ export function readSkillMarkdown(stem) {
     const raw = readFileSync(path, "utf-8");
     return raw.endsWith("\n") ? raw : raw + "\n";
 }
+/** Every packaged skill as `.agents/skills/<name>/SKILL.md` (relative path + markdown), the cross-agent skills folder. */
+export function agentSkillFiles() {
+    return Object.values(SKILL_FLAG_MAP).map((stem) => ({
+        rel: join(".agents", "skills", stem, "SKILL.md"),
+        text: readSkillMarkdown(stem),
+    }));
+}
 /** Print `--skill` index (available flags + one-line descriptions). */
 export function printSkillIndex() {
     const skills = loadSkillSpecs();

package/dist/commands/extensions.d.ts

@@ -0,0 +1 @@
+export declare function extensionsCase(args: string[]): Promise<void>;

package/dist/commands/extensions.js

@@ -0,0 +1,22 @@
+import { resolve } from "node:path";
+import { loadWaygraphConfig } from "../config.js";
+import { extensionInfo, resolveExtension } from "../extensions.js";
+export async function extensionsCase(args) {
+    const update = args.includes("--update");
+    const rest = args.slice(2).filter((a) => a !== "--update");
+    if (args[1] !== "install") {
+        console.error("usage: waygraph extensions install [project] [--update]");
+        process.exit(1);
+    }
+    const proj = resolve(rest[0] ?? process.cwd());
+    const specs = (await loadWaygraphConfig(proj))?.extensions ?? [];
+    if (specs.length === 0) {
+        console.log("waygraph extensions: no `extensions` in waygraph.config.* - nothing to install");
+        return;
+    }
+    for (const spec of specs) {
+        const dir = await resolveExtension(spec, proj, { update });
+        const { name, version } = extensionInfo(dir);
+        console.log(`waygraph extensions: ${name} ${version} -> ${dir}`);
+    }
+}

package/dist/commands/init.js

@@ -1,8 +1,34 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { packageRoot } from "../cli/util.js";
-import { basename, join, relative, resolve } from "node:path";
+import { agentSkillFiles } from "./agent-dive-scaffold.js";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
+/**
+ * Running from a checkout (not an installed package), npm doesn't have this build's code, so a plain `^version` would install an
+ * older waygraph and break the scaffold's types. Pack this checkout into the project and depend on that file instead.
+ */
+function packLocalBuild(targetDir) {
+    const root = packageRoot();
+    if (root.split(sep).includes("node_modules"))
+        return undefined;
+    const dir = join(targetDir, ".waygraph-local");
+    mkdirSync(dir, { recursive: true });
+    const packed = spawnSync("npm", ["pack", "--pack-destination", dir, "--silent"], {
+        cwd: root,
+        encoding: "utf-8",
+        shell: process.platform === "win32",
+    });
+    const file = packed.stdout?.trim().split("\n").pop();
+    if (packed.status !== 0 || !file) {
+        console.error("waygraph init: could not pack this checkout; the project will depend on the published waygraph");
+        rmSync(dir, { recursive: true, force: true });
+        return undefined;
+    }
+    writeFileSync(join(targetDir, ".gitignore"), readFileSync(join(targetDir, ".gitignore"), "utf-8") + ".waygraph-local/\n");
+    return `file:.waygraph-local/${file}`;
+}
 function initCommand(projectName) {
     if (!projectName) {
         console.error("waygraph init: missing <project-name>, e.g. waygraph init my-app");
@@ -34,9 +60,20 @@ function initCommand(projectName) {
     // Demo pages open via file://; the absolute path is only known once copied, so it's filled in here.
     const appBaseUrl = pathToFileURL(join(targetDir, "src", "map", "(app_base)", "index.html")).href;
     const packageJsonPath = join(targetDir, "package.json");
-    writeFileSync(packageJsonPath, readFileSync(packageJsonPath, "utf-8").replaceAll("__PROJECT_NAME__", pkgName));
-    const playwrightConfigPath = join(targetDir, "playwright.config.ts");
-    writeFileSync(playwrightConfigPath, readFileSync(playwrightConfigPath, "utf-8").replaceAll("__APP_BASE_URL__", appBaseUrl));
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8").replaceAll("__PROJECT_NAME__", pkgName));
+    // Pin the project to the waygraph that created it - a stale range here installs an old engine.
+    const ownVersion = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf-8")).version;
+    const local = packLocalBuild(targetDir);
+    pkg.dependencies.waygraph = local ?? `^${ownVersion}`;
+    if (local)
+        console.log(`(running from a waygraph checkout: depending on its local build, ${local})`);
+    writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + "\n");
+    const configPath = join(targetDir, "config", "waygraph.config.ts");
+    writeFileSync(configPath, readFileSync(configPath, "utf-8").replaceAll("__APP_BASE_URL__", appBaseUrl));
+    for (const { rel, text } of agentSkillFiles()) {
+        mkdirSync(dirname(join(targetDir, rel)), { recursive: true });
+        writeFileSync(join(targetDir, rel), text);
+    }
     console.log(`Scaffolded ${pkgName}/`);
     console.log("");
     console.log(`  cd ${relative(process.cwd(), targetDir) || pkgName}`);
@@ -48,8 +85,9 @@ function initCommand(projectName) {
     console.log("  waygraph typecheck   # tsc --noEmit + bad-practice warnings (use --no-practices to skip)");
     console.log("  waygraph auto        # interactive explore (headed panel)");
     console.log("  waygraph auto --cli  # same menus in the terminal");
-    console.log("  waygraph demo --blocks exampleFlow");
+    console.log("  waygraph demo --blocks homeHelloFlow");
     console.log("  waygraph graph       # static state graph JSON");
+    console.log("  .agents/skills/      # waygraph skills for coding agents (waygraph agent-dive adds agent personas)");
     console.log("");
     console.log("  Layout: see STRUCTURE.md (or https://deviate-dv8.github.io/waygraph/scaffold.html)");
 }

package/dist/commands/test.js

@@ -1,7 +1,9 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { configuredExtensions } from "../config.js";
 import { runInherited } from "../cli/util.js";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
+import { packageRoot } from "../cli/util.js";
 export async function testCase(args) {
     const rest = args.slice(1);
     const proj = process.cwd();
@@ -23,11 +25,23 @@ export async function testCase(args) {
         process.exitCode = await runPw(["show-trace", ...rest.slice(1)]);
         return;
     }
+    const extensions = await configuredExtensions(proj);
+    if (extensions.length > 0)
+        process.env.WAYGRAPH_EXTENSIONS = extensions.join(",");
+    // No playwright.config in the project: waygraph builds one from config/waygraph.config.ts.
+    const hasOwnConfig = ["ts", "mts", "js", "mjs", "cjs"].some((e) => existsSync(join(proj, `playwright.config.${e}`)));
+    if (hasOwnConfig) {
+        console.error("waygraph: playwright.config is deprecated - move its settings into config/waygraph.config.ts");
+    }
+    else {
+        process.env.WAYGRAPH_PROJECT_DIR = proj;
+    }
+    const configArgs = hasOwnConfig ? [] : ["-c", join(packageRoot(), "dist", "playwright.config.js")];
     const wantsUi = rest[0] === "ui" || rest.includes("--ui");
     const forwarded = rest[0] === "ui" ? rest.slice(1) : rest;
     const pwArgs = wantsUi && !forwarded.includes("--ui")
-        ? ["test", "--ui", ...forwarded]
-        : ["test", ...forwarded];
+        ? ["test", ...configArgs, "--ui", ...forwarded]
+        : ["test", ...configArgs, ...forwarded];
     process.exitCode = await runPw(pwArgs);
     return;
 }