@docsxai/engine 0.2.0 → 0.2.1-rc.1

package/dist/auth/webauthn.d.ts

@@ -17,64 +17,64 @@ export declare const WebauthnOptions: z.ZodEffects<z.ZodObject<{
         selector: z.ZodString;
         value_env: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
+        action: "click" | "fill";
         selector: string;
-        action: "fill" | "click";
         value_env?: string | undefined;
     }, {
+        action: "click" | "fill";
         selector: string;
-        action: "fill" | "click";
         value_env?: string | undefined;
     }>, "many">>;
 }, "strict", z.ZodTypeAny, {
-    timeout_ms: number;
     login_url: string;
+    trigger_selector: string;
+    username_selector?: string | undefined;
+    success_selector?: string | undefined;
+    url_matches?: string | undefined;
+    timeout_ms: number;
     ignore_https_errors: boolean;
     pre_steps: {
+        action: "click" | "fill";
         selector: string;
-        action: "fill" | "click";
         value_env?: string | undefined;
     }[];
-    trigger_selector: string;
-    url_matches?: string | undefined;
-    username_selector?: string | undefined;
-    success_selector?: string | undefined;
 }, {
     login_url: string;
     trigger_selector: string;
-    timeout_ms?: number | undefined;
-    url_matches?: string | undefined;
-    ignore_https_errors?: boolean | undefined;
     username_selector?: string | undefined;
     success_selector?: string | undefined;
+    url_matches?: string | undefined;
+    timeout_ms?: number | undefined;
+    ignore_https_errors?: boolean | undefined;
     pre_steps?: {
+        action: "click" | "fill";
         selector: string;
-        action: "fill" | "click";
         value_env?: string | undefined;
     }[] | undefined;
 }>, {
-    timeout_ms: number;
     login_url: string;
+    trigger_selector: string;
+    username_selector?: string | undefined;
+    success_selector?: string | undefined;
+    url_matches?: string | undefined;
+    timeout_ms: number;
     ignore_https_errors: boolean;
     pre_steps: {
+        action: "click" | "fill";
         selector: string;
-        action: "fill" | "click";
         value_env?: string | undefined;
     }[];
-    trigger_selector: string;
-    url_matches?: string | undefined;
-    username_selector?: string | undefined;
-    success_selector?: string | undefined;
 }, {
     login_url: string;
     trigger_selector: string;
-    timeout_ms?: number | undefined;
-    url_matches?: string | undefined;
-    ignore_https_errors?: boolean | undefined;
     username_selector?: string | undefined;
     success_selector?: string | undefined;
+    url_matches?: string | undefined;
+    timeout_ms?: number | undefined;
+    ignore_https_errors?: boolean | undefined;
     pre_steps?: {
+        action: "click" | "fill";
         selector: string;
-        action: "fill" | "click";
         value_env?: string | undefined;
     }[] | undefined;
 }>;

package/dist/backend-client-contracts.d.ts

@@ -41,8 +41,8 @@ export interface BlobRef {
 }
 export declare class BackendClientError extends Error {
     readonly status?: number | undefined;
-    readonly body?: unknown | undefined;
-    constructor(message: string, status?: number | undefined, body?: unknown | undefined);
+    readonly body?: unknown;
+    constructor(message: string, status?: number | undefined, body?: unknown);
 }
 export interface BackendClientOptions {
     baseUrl: string;

package/dist/calibrate.d.ts

@@ -1,7 +1,7 @@
 import { type FlowFile } from "./doc-pack.js";
 export declare class CalibrateError extends Error {
-    readonly cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
 }
 /**
  * Extract a flow-file from a structured flow-guide. Accepts: the YAML of a flow-file directly, or a Markdown

package/dist/cli-commands-session.js

@@ -149,6 +149,7 @@ export async function cmdRun(args) {
                 resolveLocator: (n) => flow.locators[n],
                 ...(stopAfter ? { stopAfter } : {}),
                 ...(startFrom ? { startFrom } : {}),
+                ...(wsCfg?.annotations?.obstacles === true ? { obstacles: true } : {}),
             });
             await fs.mkdir(resolveWorkspacePath(projectDir, "docs", flow.name), { recursive: true });
             // Flow names come from the flow-files — resolve the write target symlink-aware.

package/dist/cli-usage.d.ts

@@ -1 +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.";
+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 >= 26, 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

@@ -90,7 +90,7 @@ Notes:
     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
+  • doctor health-checks the environment + workspace: Node >= 26, 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