@docsxai/engine 0.2.0

package/dist/cli-shared.d.ts

@@ -0,0 +1,5 @@
+export declare function parseFlags(args: string[]): {
+    positionals: string[];
+    flags: Map<string, string | true>;
+};
+export declare function listFlowFiles(projectDir: string): Promise<string[]>;

package/dist/cli-shared.js

@@ -0,0 +1,45 @@
+// Shared CLI leaf — the helpers more than one command cluster reaches for. Kept dependency-free of
+// the command clusters (and of cli.ts) so it can be imported anywhere without a cycle: the clusters
+// import from here; this file imports only from the engine's lower-level modules.
+//   • parseFlags    — the argv → { positionals, flags } parser every command opens with
+//   • listFlowFiles — enumerate the workspace's flows/*.flow.yaml (run / lint / flow-tree)
+import { promises as fs } from "node:fs";
+import { resolveWorkspacePath } from "./workspace.js";
+export function parseFlags(args) {
+    const positionals = [];
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags.set(key, next);
+                i++;
+            }
+            else {
+                flags.set(key, true);
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { positionals, flags };
+}
+export async function listFlowFiles(projectDir) {
+    const dir = resolveWorkspacePath(projectDir, "flows");
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        throw new Error(`workspace ${projectDir} has no flows/ directory (expected ${dir}). ` +
+            `Is this a docsxai workspace? Create one with \`docsxai init <workspace-dir>\`, ` +
+            `then add flows via \`docsxai calibrate\` or by writing flows/<name>.flow.yaml.`);
+    }
+    return entries
+        .filter((e) => e.endsWith(".flow.yaml"))
+        .sort()
+        .map((e) => resolveWorkspacePath(projectDir, "flows", e));
+}

package/dist/cli-usage.d.ts

@@ -0,0 +1 @@
+export declare const USAGE = "docsxai \u2014 deterministic execution CLI\n\nUsage:\n  docsxai init <workspace-dir> [--app-url <url>] [--auth manual-capture|none] [--role <name>] [--ttl <dur>]\n                                 [--capture-trigger console|button] [--auth-cookie <name>] [--ignore-https-errors]\n                                 [--persist tmp] [--force]\n  docsxai calibrate <workspace-dir> --from <flow.md|.yaml> [--name <flow>]\n  docsxai inspect <workspace-dir> [--url <url>] [--selector <css>] [--cdp <endpoint>] [--wait <ms>] [--wait-for <css>] [--headed] [--role <role>]\n  docsxai run <workspace-dir> [--flow <name>] [--base-url <url>] [--headed] [--ignore-https-errors] [--stop-after <step-id>] [--start-from <step-id>] [--cdp <endpoint>] [--pause] [--concurrency <N>]\n  docsxai lint <workspace-dir> [--flow <name>] [--format text|json]\n  docsxai flow-tree <workspace-dir> [--format text|json]\n  docsxai diagnose <workspace-dir> --flow <name> --step <step-id> [--cdp <endpoint>] [--format text|json]\n  docsxai doctor [<workspace-dir>]\n  docsxai style <workspace-dir> [--check] [--format text|json]\n  docsxai zip <workspace-dir> [--out <output.zip>] [--include-viewer]\n  docsxai baseline <workspace-dir> [--out <dir>]\n  docsxai diff <workspace-dir> [--against <dir>] [--format json|md|text] [--fail-on warn|fail]\n  docsxai export adf <workspace-dir> [--flow <name>] [--mode single|page-tree] [--title <text>] [--out <dir>]\n  docsxai export playwright <workspace-dir> [--flow <name>] [--out <dir>]\n  docsxai plugins <list|info|sync> <workspace-dir> [<namespace>] [--format text|json]\n  docsxai login --backend-url <url>\n  docsxai push <workspace-dir> [--kind calibrate|run|edit] [--author <name>]\n  docsxai pull <workspace-dir> [--rev <id>]\n  docsxai render <workspace-dir>\n  docsxai capture-auth <workspace-dir> [--base-url <url>] [--role <role>] [--auth-cookie <name>] [--cdp <endpoint>] [--fresh] [--headless] [--ignore-https-errors]\n  docsxai --help\n\nNotes:\n  \u2022 A *workspace* (created by `init`) holds flows/<flow>.flow.yaml, docs/, auth/strategy.yaml, .auth/, .viewer/,\n    and a .docsxai.json config. Put it OUTSIDE the app's source repo \u2014 docsxai documents a running app from\n    outside and never writes into the app repo.\n  \u2022 run / capture-auth read app_url + ignore_https_errors from .docsxai.json if you don't pass the flags.\n  \u2022 run launches Chromium; if no browser binary is present, install one:  npx playwright-core install chromium\n    (source checkout: pnpm -C packages/engine exec playwright-core install chromium)\n  \u2022 --ignore-https-errors accepts self-signed/invalid TLS (e.g. an app's local HTTPS dev cert)\n  \u2022 run --stop-after <step-id> runs only a prefix of the flow (up to & incl. that step); --pause keeps the\n    (headed) browser open at the last step run \u2014 so you can inspect the live state mid-flow when calibrating\n    (pair with --flow <name>). For waiting on a slow backend op, give a step a wait_for of the form\n    { selector: $x, timeout_ms: 180000 } \u2014 a per-step override of the default ~30s selector-wait timeout.\n  \u2022 run --concurrency <N> runs up to N flows in parallel (each its own Chromium session, isolated; default 1).\n    Useful when several flows share a long preamble \u2014 total wall time = max(per-flow), not sum. Force-clamped\n    to 1 when --pause / --stop-after / --start-from / --cdp is set. The target app must tolerate multiple sessions from one user.\n  \u2022 run --start-from <step-id> --flow <name> SKIPS every step before <step-id> and starts execution there \u2014\n    the inverse of --stop-after. Pair with --cdp to attach to a Chrome that's already in the post-prior-steps\n    state (e.g. left over from a paused previous run) and iterate on the new tail step in seconds rather\n    than re-walking the whole extends chain. New annotations MERGE into the existing annotations.json by\n    step id; the prior steps' annotations and screenshots are preserved.\n  \u2022 run --cdp <endpoint> attaches to a running Chrome (start it with --remote-debugging-port=N) instead of\n    launching one. docsxai won't close that Chrome. When --cdp is set, the cached storageState is NOT\n    loaded into the context \u2014 the operator's Chrome owns its auth state. Useful with --start-from for the\n    sub-3-sec iteration loop on long-async flows.\n  \u2022 capture-auth runs the role's auth strategy (MVP: manual-capture \u2014 a headed, instrumented browser the\n    engineer logs into; window.__docsxai.capture() or an injected button snapshots the session) and caches\n    it to <workspace-dir>/.auth/<role>.json for subsequent `run`s. It prints the captured cookie jar so you\n    can identify the app's real auth/session cookie.\n  \u2022 capture-auth keeps a persistent Chrome profile at <workspace>/.auth/chrome-profile/ (gitignored) \u2014 re-running\n    it reuses the login (just trigger capture again). Use --fresh for a clean profile (forces a fresh login).\n  \u2022 --cdp <endpoint> makes capture-auth *attach to an already-running Chrome* (start it with\n    --remote-debugging-port=N --disable-web-security --user-data-dir=<dir>) instead of launching a fresh one \u2014\n    use this to capture from the same Chrome the engineer is already logged into (and that Claude in Chrome is\n    driving for discovery), so they don't log in twice. docsxai won't close that Chrome. (--cdp ignores --fresh.)\n  \u2022 auth_cookie (set via `init --auth-cookie`, `capture-auth --auth-cookie`, or hand-edited into\n    auth/strategy.yaml) names that cookie; when set, the cached session's expiry tracks *that* cookie's\n    expiry rather than the `ttl` guess (an interactive SSO login leaves ephemeral IdP scratch cookies, so\n    `min(cookie.expires)` \u2248 now \u2014 don't rely on it). If unset/unfound, `ttl` (or a 1h default) is used.\n  \u2022 inspect opens the app in a headless (or --headed) browser *with the cached session loaded* and prints the\n    page's [data-testid] elements (or, with --selector, matching elements' HTML) \u2014 for pinning locators when\n    hand-authoring a flow-file (the captured session can't be replayed in a browser the agent's MCP controls\n    because the auth cookie is usually httpOnly; inspect does the storageState\u2192Playwright bridge for you). On a\n    slow SPA, settle before the snapshot with --wait <ms> (default 800) or --wait-for '<css>'. --cdp <endpoint>\n    attaches to an already-running Chrome (e.g. the one from capture-auth --cdp) instead of launching one.\n  \u2022 calibrate takes a *structured flow-guide* (a flow-file in YAML, or a .md with a yaml fenced block) and\n    writes flows/<name>.flow.yaml + a default docs/style.yaml. Loose-prose descriptions / live element-picking\n    need the host agent \u2014 that's the /docsxai:calibrate *skill* (see the plugin), which then refines/produces\n    the flow-file; this CLI command covers only the deterministic structured-input case.\n  \u2022 lint runs pure-static checks across the workspace's flow-files \u2014 no Playwright, no live page. Rules:\n    R001 (deep extends chain), R002 (annotation anchored to a likely-unmounting click/navigate target \u2014\n    suggest annotation.target override), R003 (wait_for with no timeout_ms on a long-async-looking step),\n    R004 (bare [data-*=\u2026] selector \u2014 may have hidden duplicates; suggest :visible / :has-text qualifier).\n    Exit 1 if any warning/error; 0 otherwise. --format json emits machine-readable output for tooling.\n  \u2022 flow-tree prints the workspace's extends graph (root flows + their descendants), plus any orphans\n    (flows whose extends parent isn't in the workspace) and resolution issues (cycles / step-id collisions\n    across the merge). Pure-static, ~no I/O beyond reading the flow files. Exit 1 if any issues.\n  \u2022 diagnose gathers halt context for a specific step (the step's selector/wait_for/success, the halt\n    screenshot if one exists, and \u2014 with --cdp \u2014 a live actionable() probe of the target on the running\n    page) and prints recommendations (selector / wait_for / success / annotation_target / split_step /\n    investigate). The engine never patches the flow-file itself \u2014 that's the agent's explicit opt-in\n    action. --format json emits machine-readable output for an agent to act on. Pair with\n    --start-from <step-id> --cdp on a follow-up run to validate the fix in seconds.\n  \u2022 doctor health-checks the environment + workspace: Node >= 20, Chromium presence, .docsxai.json\n    found + parseable (cwd or the arg), flow-file parses, auth descriptor + cached-session freshness,\n    backend reachability (when backend_url is set), the plugin declarations (same inspection as\n    `plugins list` \u2014 no plugin code is executed), viewer-bin resolution (which of the three layers\n    hit), and DOCSX_* env sanity. \u2713/\u2717 rows with a one-line fix per failure; \u2212 rows are informational\n    and never fail. Exit 1 if any \u2717.\n  \u2022 style initialises docs/style.yaml + derived docs/style.json if absent (otherwise validates the\n    existing YAML against the schema and rederives the JSON). --check additionally scans every\n    docs/<flow>/<step>.md user-facing write-up for jargon leaks against the style's pruning_rules\n    (e.g. VERIFY / WAIT / data-testid leaking into user-facing prose). The engine never re-shapes\n    prose itself (LLM-agnostic) \u2014 the agent does that at calibration time; this command is the\n    enforcement layer for the semantic-reshape exit criterion. --format json emits machine-readable\n    output for tooling.\n  \u2022 zip packages the workspace's doc pack into a single archive for hand-off. Includes flows/, docs/,\n    .docsxai.json, auth/strategy.yaml (env-var names only, no creds), README.md. Excludes .auth/\n    (operator-local session state), **/halts/ (debug screenshots), .viewer/ by default (re-renderable\n    from the doc pack; pass --include-viewer to bundle it). Defaults output to <workspace-name>.zip\n    in the current dir; override with --out <path>. Zips in-process (no system 'zip' binary needed)\n    and deterministically \u2014 sorted entries, fixed mtime, fixed compression \u2014 so the same doc pack\n    always produces a byte-identical archive.\n  \u2022 baseline snapshots the doc pack \u2014 flows/, docs/<flow>/*.md, annotations.json, screenshots/, and\n    docs/locators.yaml \u2014 into <ws>/.baseline/ (or --out <dir>). Commit the baseline: it's the \"before\"\n    that diff compares against in CI.\n  \u2022 diff compares the workspace against a baseline (default <ws>/.baseline/, or --against <dir>) and\n    emits a deterministic drift report: per flow, step field deltas (id-keyed), annotation moves,\n    screenshot pixel diffs (changed-pixel count / % / changed-region bbox; dimension changes flagged\n    distinctly), prose line-change counts, and locator changes. --format md is PR-comment-ready.\n    --fail-on warn|fail exits 1 when the report severity is at/above the threshold (screenshot\n    severity: \u22651% changed pixels = warn, \u22655% = fail; structural changes = warn).\n  \u2022 export playwright emits one self-contained Playwright .spec.ts per flow (extends resolved) into\n    <ws>/.export/tests/ (or --out <dir>) \u2014 locators as consts, steps as page actions, success criteria\n    as expect() assertions, environment as test.use(); optional steps are try/catch-wrapped. Generated\n    files say so in a header: regenerate, don't hand-edit.\n  \u2022 render builds the static viewer by spawning the docsxai-viewer bin, resolved in order: the\n    DOCSX_VIEWER_BIN env var (path to the viewer's bin script), the @docsxai/viewer\n    package installed next to the engine, then `docsxai-viewer` on PATH.\n  \u2022 login validates a bearer token against a backend URL \u2014 hits /v1/health, /v1/workspaces. Reads\n    the token from DOCSX_TOKEN env var. Prints what the backend sees if the call succeeds,\n    or a clear error if not. Stateless: doesn't store anything; configure the env var in your shell.\n  \u2022 push serialises the workspace's doc pack (flows + annotations + screenshots + style + locators)\n    and POSTs it as a new revision against the backend named in .docsxai.json (backend_url +\n    optionally backend_workspace_id / backend_project_id; created on first push if absent and\n    persisted to the config). --kind defaults to \"calibrate\"; --author defaults to the OS user.\n  \u2022 pull fetches a revision's artifacts back into the workspace files (default: HEAD). Useful for\n    syncing with a different operator's edits or rolling back to a named revision.";

package/dist/cli-usage.js

@@ -0,0 +1,137 @@
+// `docsxai` CLI help text. Split out of cli.ts so the dispatch barrel and every command cluster
+// can share the one authoritative USAGE string (commands print it on a missing-arg bail; the
+// barrel prints it for --help / unknown-command). Text only — no imports, the truest leaf.
+export const USAGE = `docsxai — deterministic execution CLI
+
+Usage:
+  docsxai init <workspace-dir> [--app-url <url>] [--auth manual-capture|none] [--role <name>] [--ttl <dur>]
+                                 [--capture-trigger console|button] [--auth-cookie <name>] [--ignore-https-errors]
+                                 [--persist tmp] [--force]
+  docsxai calibrate <workspace-dir> --from <flow.md|.yaml> [--name <flow>]
+  docsxai inspect <workspace-dir> [--url <url>] [--selector <css>] [--cdp <endpoint>] [--wait <ms>] [--wait-for <css>] [--headed] [--role <role>]
+  docsxai run <workspace-dir> [--flow <name>] [--base-url <url>] [--headed] [--ignore-https-errors] [--stop-after <step-id>] [--start-from <step-id>] [--cdp <endpoint>] [--pause] [--concurrency <N>]
+  docsxai lint <workspace-dir> [--flow <name>] [--format text|json]
+  docsxai flow-tree <workspace-dir> [--format text|json]
+  docsxai diagnose <workspace-dir> --flow <name> --step <step-id> [--cdp <endpoint>] [--format text|json]
+  docsxai doctor [<workspace-dir>]
+  docsxai style <workspace-dir> [--check] [--format text|json]
+  docsxai zip <workspace-dir> [--out <output.zip>] [--include-viewer]
+  docsxai baseline <workspace-dir> [--out <dir>]
+  docsxai diff <workspace-dir> [--against <dir>] [--format json|md|text] [--fail-on warn|fail]
+  docsxai export adf <workspace-dir> [--flow <name>] [--mode single|page-tree] [--title <text>] [--out <dir>]
+  docsxai export playwright <workspace-dir> [--flow <name>] [--out <dir>]
+  docsxai plugins <list|info|sync> <workspace-dir> [<namespace>] [--format text|json]
+  docsxai login --backend-url <url>
+  docsxai push <workspace-dir> [--kind calibrate|run|edit] [--author <name>]
+  docsxai pull <workspace-dir> [--rev <id>]
+  docsxai render <workspace-dir>
+  docsxai capture-auth <workspace-dir> [--base-url <url>] [--role <role>] [--auth-cookie <name>] [--cdp <endpoint>] [--fresh] [--headless] [--ignore-https-errors]
+  docsxai --help
+
+Notes:
+  • A *workspace* (created by \`init\`) holds flows/<flow>.flow.yaml, docs/, auth/strategy.yaml, .auth/, .viewer/,
+    and a .docsxai.json config. Put it OUTSIDE the app's source repo — docsxai documents a running app from
+    outside and never writes into the app repo.
+  • run / capture-auth read app_url + ignore_https_errors from .docsxai.json if you don't pass the flags.
+  • run launches Chromium; if no browser binary is present, install one:  npx playwright-core install chromium
+    (source checkout: pnpm -C packages/engine exec playwright-core install chromium)
+  • --ignore-https-errors accepts self-signed/invalid TLS (e.g. an app's local HTTPS dev cert)
+  • run --stop-after <step-id> runs only a prefix of the flow (up to & incl. that step); --pause keeps the
+    (headed) browser open at the last step run — so you can inspect the live state mid-flow when calibrating
+    (pair with --flow <name>). For waiting on a slow backend op, give a step a wait_for of the form
+    { selector: $x, timeout_ms: 180000 } — a per-step override of the default ~30s selector-wait timeout.
+  • run --concurrency <N> runs up to N flows in parallel (each its own Chromium session, isolated; default 1).
+    Useful when several flows share a long preamble — total wall time = max(per-flow), not sum. Force-clamped
+    to 1 when --pause / --stop-after / --start-from / --cdp is set. The target app must tolerate multiple sessions from one user.
+  • run --start-from <step-id> --flow <name> SKIPS every step before <step-id> and starts execution there —
+    the inverse of --stop-after. Pair with --cdp to attach to a Chrome that's already in the post-prior-steps
+    state (e.g. left over from a paused previous run) and iterate on the new tail step in seconds rather
+    than re-walking the whole extends chain. New annotations MERGE into the existing annotations.json by
+    step id; the prior steps' annotations and screenshots are preserved.
+  • run --cdp <endpoint> attaches to a running Chrome (start it with --remote-debugging-port=N) instead of
+    launching one. docsxai won't close that Chrome. When --cdp is set, the cached storageState is NOT
+    loaded into the context — the operator's Chrome owns its auth state. Useful with --start-from for the
+    sub-3-sec iteration loop on long-async flows.
+  • capture-auth runs the role's auth strategy (MVP: manual-capture — a headed, instrumented browser the
+    engineer logs into; window.__docsxai.capture() or an injected button snapshots the session) and caches
+    it to <workspace-dir>/.auth/<role>.json for subsequent \`run\`s. It prints the captured cookie jar so you
+    can identify the app's real auth/session cookie.
+  • capture-auth keeps a persistent Chrome profile at <workspace>/.auth/chrome-profile/ (gitignored) — re-running
+    it reuses the login (just trigger capture again). Use --fresh for a clean profile (forces a fresh login).
+  • --cdp <endpoint> makes capture-auth *attach to an already-running Chrome* (start it with
+    --remote-debugging-port=N --disable-web-security --user-data-dir=<dir>) instead of launching a fresh one —
+    use this to capture from the same Chrome the engineer is already logged into (and that Claude in Chrome is
+    driving for discovery), so they don't log in twice. docsxai won't close that Chrome. (--cdp ignores --fresh.)
+  • auth_cookie (set via \`init --auth-cookie\`, \`capture-auth --auth-cookie\`, or hand-edited into
+    auth/strategy.yaml) names that cookie; when set, the cached session's expiry tracks *that* cookie's
+    expiry rather than the \`ttl\` guess (an interactive SSO login leaves ephemeral IdP scratch cookies, so
+    \`min(cookie.expires)\` ≈ now — don't rely on it). If unset/unfound, \`ttl\` (or a 1h default) is used.
+  • inspect opens the app in a headless (or --headed) browser *with the cached session loaded* and prints the
+    page's [data-testid] elements (or, with --selector, matching elements' HTML) — for pinning locators when
+    hand-authoring a flow-file (the captured session can't be replayed in a browser the agent's MCP controls
+    because the auth cookie is usually httpOnly; inspect does the storageState→Playwright bridge for you). On a
+    slow SPA, settle before the snapshot with --wait <ms> (default 800) or --wait-for '<css>'. --cdp <endpoint>
+    attaches to an already-running Chrome (e.g. the one from capture-auth --cdp) instead of launching one.
+  • calibrate takes a *structured flow-guide* (a flow-file in YAML, or a .md with a yaml fenced block) and
+    writes flows/<name>.flow.yaml + a default docs/style.yaml. Loose-prose descriptions / live element-picking
+    need the host agent — that's the /docsxai:calibrate *skill* (see the plugin), which then refines/produces
+    the flow-file; this CLI command covers only the deterministic structured-input case.
+  • lint runs pure-static checks across the workspace's flow-files — no Playwright, no live page. Rules:
+    R001 (deep extends chain), R002 (annotation anchored to a likely-unmounting click/navigate target —
+    suggest annotation.target override), R003 (wait_for with no timeout_ms on a long-async-looking step),
+    R004 (bare [data-*=…] selector — may have hidden duplicates; suggest :visible / :has-text qualifier).
+    Exit 1 if any warning/error; 0 otherwise. --format json emits machine-readable output for tooling.
+  • flow-tree prints the workspace's extends graph (root flows + their descendants), plus any orphans
+    (flows whose extends parent isn't in the workspace) and resolution issues (cycles / step-id collisions
+    across the merge). Pure-static, ~no I/O beyond reading the flow files. Exit 1 if any issues.
+  • diagnose gathers halt context for a specific step (the step's selector/wait_for/success, the halt
+    screenshot if one exists, and — with --cdp — a live actionable() probe of the target on the running
+    page) and prints recommendations (selector / wait_for / success / annotation_target / split_step /
+    investigate). The engine never patches the flow-file itself — that's the agent's explicit opt-in
+    action. --format json emits machine-readable output for an agent to act on. Pair with
+    --start-from <step-id> --cdp on a follow-up run to validate the fix in seconds.
+  • doctor health-checks the environment + workspace: Node >= 20, Chromium presence, .docsxai.json
+    found + parseable (cwd or the arg), flow-file parses, auth descriptor + cached-session freshness,
+    backend reachability (when backend_url is set), the plugin declarations (same inspection as
+    \`plugins list\` — no plugin code is executed), viewer-bin resolution (which of the three layers
+    hit), and DOCSX_* env sanity. ✓/✗ rows with a one-line fix per failure; − rows are informational
+    and never fail. Exit 1 if any ✗.
+  • style initialises docs/style.yaml + derived docs/style.json if absent (otherwise validates the
+    existing YAML against the schema and rederives the JSON). --check additionally scans every
+    docs/<flow>/<step>.md user-facing write-up for jargon leaks against the style's pruning_rules
+    (e.g. VERIFY / WAIT / data-testid leaking into user-facing prose). The engine never re-shapes
+    prose itself (LLM-agnostic) — the agent does that at calibration time; this command is the
+    enforcement layer for the semantic-reshape exit criterion. --format json emits machine-readable
+    output for tooling.
+  • zip packages the workspace's doc pack into a single archive for hand-off. Includes flows/, docs/,
+    .docsxai.json, auth/strategy.yaml (env-var names only, no creds), README.md. Excludes .auth/
+    (operator-local session state), **/halts/ (debug screenshots), .viewer/ by default (re-renderable
+    from the doc pack; pass --include-viewer to bundle it). Defaults output to <workspace-name>.zip
+    in the current dir; override with --out <path>. Zips in-process (no system 'zip' binary needed)
+    and deterministically — sorted entries, fixed mtime, fixed compression — so the same doc pack
+    always produces a byte-identical archive.
+  • baseline snapshots the doc pack — flows/, docs/<flow>/*.md, annotations.json, screenshots/, and
+    docs/locators.yaml — into <ws>/.baseline/ (or --out <dir>). Commit the baseline: it's the "before"
+    that diff compares against in CI.
+  • diff compares the workspace against a baseline (default <ws>/.baseline/, or --against <dir>) and
+    emits a deterministic drift report: per flow, step field deltas (id-keyed), annotation moves,
+    screenshot pixel diffs (changed-pixel count / % / changed-region bbox; dimension changes flagged
+    distinctly), prose line-change counts, and locator changes. --format md is PR-comment-ready.
+    --fail-on warn|fail exits 1 when the report severity is at/above the threshold (screenshot
+    severity: ≥1% changed pixels = warn, ≥5% = fail; structural changes = warn).
+  • export playwright emits one self-contained Playwright .spec.ts per flow (extends resolved) into
+    <ws>/.export/tests/ (or --out <dir>) — locators as consts, steps as page actions, success criteria
+    as expect() assertions, environment as test.use(); optional steps are try/catch-wrapped. Generated
+    files say so in a header: regenerate, don't hand-edit.
+  • render builds the static viewer by spawning the docsxai-viewer bin, resolved in order: the
+    DOCSX_VIEWER_BIN env var (path to the viewer's bin script), the @docsxai/viewer
+    package installed next to the engine, then \`docsxai-viewer\` on PATH.
+  • login validates a bearer token against a backend URL — hits /v1/health, /v1/workspaces. Reads
+    the token from DOCSX_TOKEN env var. Prints what the backend sees if the call succeeds,
+    or a clear error if not. Stateless: doesn't store anything; configure the env var in your shell.
+  • push serialises the workspace's doc pack (flows + annotations + screenshots + style + locators)
+    and POSTs it as a new revision against the backend named in .docsxai.json (backend_url +
+    optionally backend_workspace_id / backend_project_id; created on first push if absent and
+    persisted to the config). --kind defaults to "calibrate"; --author defaults to the OS user.
+  • pull fetches a revision's artifacts back into the workspace files (default: HEAD). Useful for
+    syncing with a different operator's edits or rolling back to a named revision.`;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// `docsxai` — the deterministic CLI. The plugin's commands wrap this; calibration runs in an agent
+// context and is exposed by the plugin, not here.
+//
+// Barrel / dispatch: the command bodies live in flat siblings, grouped by cohesion. This file parses
+// argv, routes the subcommand to its handler, and re-exports `main` so `./cli.js` callers (the bin,
+// the colocated tests) are unchanged. The clusters import shared helpers from cli-shared.ts (a leaf)
+// and the help text from cli-usage.ts — no cluster imports back from here, so there's no cycle.
+//   • cli-usage.ts             — the USAGE help-text constant
+//   • cli-shared.ts            — parseFlags + listFlowFiles (the shared leaf)
+//   • cli-commands-session.ts  — init / capture-auth / calibrate / run (live-browser + scaffolding)
+//   • cli-commands-authoring.ts — inspect / lint / flow-tree / diagnose / style (calibration aids)
+//   • cli-commands-docpack.ts  — render / zip / export / baseline / diff (doc-pack ops)
+//   • cli-commands-backend.ts  — login / push / pull / plugins (backend + sync)
+import { pathToFileURL } from "node:url";
+import { runDoctor } from "./doctor.js";
+import { USAGE } from "./cli-usage.js";
+import { cmdCalibrate, cmdCaptureAuth, cmdInit, cmdRun } from "./cli-commands-session.js";
+import { cmdDiagnose, cmdFlowTree, cmdInspect, cmdLint, cmdStyle, } from "./cli-commands-authoring.js";
+import { cmdBaseline, cmdDiff, cmdExport, cmdRender, cmdZip } from "./cli-commands-docpack.js";
+import { cmdLogin, cmdPlugins, cmdPull, cmdPush } from "./cli-commands-backend.js";
+export async function main(argv) {
+    const [cmd, ...rest] = argv;
+    switch (cmd) {
+        case undefined:
+        case "--help":
+        case "-h":
+        case "help":
+            process.stdout.write(USAGE + "\n");
+            return 0;
+        case "init":
+            return cmdInit(rest);
+        case "calibrate":
+            return cmdCalibrate(rest);
+        case "inspect":
+            return cmdInspect(rest);
+        case "run":
+            return cmdRun(rest);
+        case "render":
+            return cmdRender(rest);
+        case "capture-auth":
+            return cmdCaptureAuth(rest);
+        case "lint":
+            return cmdLint(rest);
+        case "flow-tree":
+            return cmdFlowTree(rest);
+        case "diagnose":
+            return cmdDiagnose(rest);
+        case "doctor":
+            return runDoctor(rest);
+        case "style":
+            return cmdStyle(rest);
+        case "zip":
+            return cmdZip(rest);
+        case "baseline":
+            return cmdBaseline(rest);
+        case "diff":
+            return cmdDiff(rest);
+        case "export":
+            return cmdExport(rest);
+        case "plugins":
+            return cmdPlugins(rest);
+        case "login":
+            return cmdLogin(rest);
+        case "push":
+            return cmdPush(rest);
+        case "pull":
+            return cmdPull(rest);
+        default:
+            process.stderr.write(`unknown command: ${cmd}\n\n${USAGE}\n`);
+            return 2;
+    }
+}
+// Run as the bin entry, but not when imported (e.g. in tests).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    void main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/dist/diagnose.d.ts

@@ -0,0 +1,50 @@
+import type { BoundingBox, FlowFile, Step } from "./doc-pack.js";
+import type { ActionableState, BrowserDriver } from "./flow-runtime.js";
+export type DiagnoseRecommendationKind = "selector" | "wait_for" | "success" | "annotation_target" | "split_step" | "investigate";
+export interface DiagnoseRecommendation {
+    kind: DiagnoseRecommendationKind;
+    rationale: string;
+    suggestion: string;
+}
+export interface DiagnoseLiveProbe {
+    cdpEndpoint: string;
+    url: string;
+    actionable: ActionableState;
+    bbox: BoundingBox | null;
+}
+export interface DiagnoseReport {
+    workspace: string;
+    flow: string;
+    step: {
+        id: string;
+        action: Step["action"];
+        target?: string;
+        resolvedSelector?: string;
+        wait_for?: unknown;
+        success?: unknown;
+    };
+    halt: {
+        screenshotRelPath?: string;
+        screenshotAbsPath?: string;
+    };
+    live?: DiagnoseLiveProbe;
+    recommendations: DiagnoseRecommendation[];
+}
+/** Map an `ActionableState` to concrete recommendations for the agent. */
+export declare function recommendFromActionable(state: ActionableState): DiagnoseRecommendation[];
+/** Static recommendations from the flow-file shape alone (no live probe). */
+export declare function recommendStatic(step: Step, halt: {
+    screenshotRelPath?: string;
+}): DiagnoseRecommendation[];
+/** Build the full report. `liveProbe` is invoked lazily (only if a driver is supplied). */
+export declare function buildDiagnoseReport(opts: {
+    workspace: string;
+    flow: FlowFile;
+    step: Step;
+    resolvedSelector?: string;
+    haltScreenshotAbsPath?: string;
+    liveProbe?: () => Promise<DiagnoseLiveProbe>;
+}): Promise<DiagnoseReport>;
+/** Live-probe helper that uses any driver implementing the runtime's `BrowserDriver` interface. */
+export declare function probeLive(driver: BrowserDriver, selector: string, cdpEndpoint: string): Promise<DiagnoseLiveProbe>;
+export declare function formatReportText(r: DiagnoseReport): string;

package/dist/diagnose.js

@@ -0,0 +1,168 @@
+// Halt diagnosis — gather the context a calibration agent needs to propose a recalibration diff.
+// Pure data + recommendations; the engine never patches the flow-file itself (that's an explicit
+// opt-in action by the agent / human, never ambient). The agent reads the report, walks the live
+// page (typically via browxai), picks a fix, and edits the flow-file. `docsxai run --start-from
+// <step-id> --cdp <endpoint>` then validates the edit in seconds.
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+/** Map an `ActionableState` to concrete recommendations for the agent. */
+export function recommendFromActionable(state) {
+    switch (state) {
+        case "actionable":
+            return [
+                {
+                    kind: "investigate",
+                    rationale: "The current target is actionable on the live page right now.",
+                    suggestion: "Drift may be intermittent (race condition) or in the `success` criterion. Consider adding `wait_for: network_idle` or `element_stable`; re-check the `success` clause against the live target state.",
+                },
+            ];
+        case "not-found":
+            return [
+                {
+                    kind: "selector",
+                    rationale: "Selector matches 0 elements on the live page — the element was renamed, moved, or removed.",
+                    suggestion: "Re-discover the element via the calibration loop (browxai's `find()`, or `docsxai inspect`). Pick a new canonical locator and commit it as the step's `target` (or update the named entry in the flow's `locators:` block).",
+                },
+            ];
+        case "multiple-matches":
+            return [
+                {
+                    kind: "selector",
+                    rationale: "Selector matches multiple DOM nodes — strict-mode violation territory; one of them is likely a hidden duplicate.",
+                    suggestion: "Scope the selector: append `:visible`, use `:nth-match(<sel>, 1)`, or add a stable qualifier (parent class, `:has-text(...)`). Avoid silently picking one — the duplicate signal usually means the locator isn't specific enough.",
+                },
+            ];
+        case "disabled":
+            return [
+                {
+                    kind: "investigate",
+                    rationale: "Selector resolves to a single visible element that is `disabled`.",
+                    suggestion: "Check whether the action is appropriate for the target state — sometimes a UI element is intentionally disabled (clip-driven inputs, gated controls). The doc may need to describe the disabled-state behaviour rather than trying to act on the element. If unexpected, the disabled state itself is a product-side question.",
+                },
+            ];
+        case "detached":
+            return [
+                {
+                    kind: "annotation_target",
+                    rationale: "Selector resolved but the element isn't attached to the DOM any more — usually unmounted by the action itself (the step's action transitions the UI, and the original target is gone in the post-action state).",
+                    suggestion: "Set the annotation's `target` to a different element that survives the transition (an element in the resulting state). The action's `target` stays the same; only the annotation anchor moves.",
+                },
+            ];
+        case "not-visible":
+            return [
+                {
+                    kind: "wait_for",
+                    rationale: "Selector resolves to a single element but it's hidden (`display: none` / `visibility: hidden` / zero-size).",
+                    suggestion: "Add (or strengthen) `wait_for: { selector: <sel>, timeout_ms: <ms> }` to give the element time to become visible. If it's permanently hidden, the locator probably moved — re-discover.",
+                },
+            ];
+        case "off-screen":
+            return [
+                {
+                    kind: "split_step",
+                    rationale: "Selector resolves to a CSS-visible element but it's outside the viewport, and Playwright's auto-scroll didn't reach it.",
+                    suggestion: "Insert a scroll-into-view step before the action (or pick a parent element that's in the viewport). Off-screen elements inside `overflow: auto` containers are usually fine — this state means the page scroll is the issue, not a scroller.",
+                },
+            ];
+        case "covered":
+            return [
+                {
+                    kind: "split_step",
+                    rationale: "Another element receives clicks at this element's center — likely a modal, overlay, or tooltip covering the target.",
+                    suggestion: "Insert a step to dismiss the covering element (close button, click outside, ESC key), then act on the original target.",
+                },
+            ];
+    }
+}
+/** Static recommendations from the flow-file shape alone (no live probe). */
+export function recommendStatic(step, halt) {
+    const recs = [];
+    if (halt.screenshotRelPath) {
+        recs.push({
+            kind: "investigate",
+            rationale: `A halt screenshot exists at \`${halt.screenshotRelPath}\` — read it first; on most halts the visual state shows the issue immediately.`,
+            suggestion: "Open the screenshot; compare the visual state to what the step expects.",
+        });
+    }
+    const success = step.success;
+    if (success && typeof success === "object" && success !== null && "text_contains" in success) {
+        recs.push({
+            kind: "success",
+            rationale: "Success criterion uses `text_contains` — fragile against UI copy changes / localisation drift.",
+            suggestion: "Verify the expected text still appears in the post-action state. If the text changed, update it; if the text shifted to a different element, change the success selector. Where stable, a structural criterion (visible/hidden element, url_matches) is more drift-resistant.",
+        });
+    }
+    return recs;
+}
+/** Build the full report. `liveProbe` is invoked lazily (only if a driver is supplied). */
+export async function buildDiagnoseReport(opts) {
+    const haltExists = opts.haltScreenshotAbsPath
+        ? await fs
+            .access(opts.haltScreenshotAbsPath)
+            .then(() => true)
+            .catch(() => false)
+        : false;
+    const haltRel = haltExists
+        ? path.relative(opts.workspace, opts.haltScreenshotAbsPath)
+        : undefined;
+    const live = opts.liveProbe ? await opts.liveProbe() : undefined;
+    const recommendations = [
+        ...recommendStatic(opts.step, { screenshotRelPath: haltRel }),
+        ...(live ? recommendFromActionable(live.actionable) : []),
+    ];
+    return {
+        workspace: opts.workspace,
+        flow: opts.flow.name,
+        step: {
+            id: opts.step.id,
+            action: opts.step.action,
+            ...(opts.step.target ? { target: opts.step.target } : {}),
+            ...(opts.resolvedSelector ? { resolvedSelector: opts.resolvedSelector } : {}),
+            ...(opts.step.wait_for !== undefined ? { wait_for: opts.step.wait_for } : {}),
+            ...(opts.step.success !== undefined ? { success: opts.step.success } : {}),
+        },
+        halt: {
+            ...(haltRel ? { screenshotRelPath: haltRel } : {}),
+            ...(haltExists ? { screenshotAbsPath: opts.haltScreenshotAbsPath } : {}),
+        },
+        ...(live ? { live } : {}),
+        recommendations,
+    };
+}
+/** Live-probe helper that uses any driver implementing the runtime's `BrowserDriver` interface. */
+export async function probeLive(driver, selector, cdpEndpoint) {
+    const url = await driver.currentUrl();
+    const actionable = await driver.actionable(selector);
+    const bbox = await driver.boundingBox(selector, 500).catch(() => null);
+    return { cdpEndpoint, url, actionable, bbox };
+}
+export function formatReportText(r) {
+    let out = `diagnose: flow=${r.flow} step=${r.step.id}\n\n`;
+    out += `Current step:\n`;
+    out += `  action: ${r.step.action}\n`;
+    if (r.step.target)
+        out += `  target: ${r.step.target}${r.step.resolvedSelector && r.step.resolvedSelector !== r.step.target ? ` (resolved: ${r.step.resolvedSelector})` : ""}\n`;
+    if (r.step.wait_for !== undefined)
+        out += `  wait_for: ${JSON.stringify(r.step.wait_for)}\n`;
+    if (r.step.success !== undefined)
+        out += `  success: ${JSON.stringify(r.step.success)}\n`;
+    out += `\n`;
+    if (r.halt.screenshotRelPath) {
+        out += `Halt artifacts:\n  screenshot: ${r.halt.screenshotRelPath}\n\n`;
+    }
+    else {
+        out += `Halt artifacts:\n  (no halt screenshot found at the expected path — run hasn't halted on this step recently, or screenshots are disabled)\n\n`;
+    }
+    if (r.live) {
+        out += `Live probe (via ${r.live.cdpEndpoint}):\n`;
+        out += `  url: ${r.live.url}\n`;
+        out += `  actionable: ${r.live.actionable}\n`;
+        out += `  bbox: ${r.live.bbox ? JSON.stringify(r.live.bbox) : "null"}\n\n`;
+    }
+    out += `Recommendations (${r.recommendations.length}):\n`;
+    for (const rec of r.recommendations) {
+        out += `  [${rec.kind}] ${rec.rationale}\n`;
+        out += `    → ${rec.suggestion}\n`;
+    }
+    return out;
+}

package/dist/diff-compute.d.ts

@@ -0,0 +1,13 @@
+import { type DriftPolicy, type DriftRegion, type DriftReport, type PngDiffResult } from "./diff-types.js";
+/**
+ * Exact-RGBA pixel diff between two PNG buffers. Dimension mismatch is reported distinctly (no
+ * pixel comparison is meaningful across sizes). `ignoreRegions` rectangles are excluded from the
+ * comparison; `pct` is changed pixels over the FULL image area, rounded to 4 decimals.
+ */
+export declare function diffPngBuffers(aPng: Buffer, bPng: Buffer, ignoreRegions?: DriftRegion[]): PngDiffResult;
+/**
+ * Diff two doc-pack directories (each a workspace-shaped tree: `flows/` + `docs/`). `aDir` is the
+ * baseline ("before"), `bDir` the candidate ("after"). Pure file → JSON transform; deterministic
+ * (no timestamps); never writes.
+ */
+export declare function diffDocPacks(aDir: string, bDir: string, options?: DriftPolicy): Promise<DriftReport>;