Skip to content

Changelog

All notable changes to this project. Format loosely follows Keep a Changelog; this project adheres to Semantic Versioning.

  • run errors that stopped with no next step now end with one. --cdp with a matrix flow says to drop --cdp or pick a flow without a matrix, and an unknown --variant says to drop it or pick a listed one. The --start-from usage error no longer calls itself a calibration aid.
  • Warnings read warning: everywhere. Three messages said warning, (run with a relative path and no app_url, pull with an unknown artifact, and an ignored config or auth file). They now use the same warning: prefix as the rest.
  • doctor says less about Node. The passing row is ok: node: v26.1.0. A failing row says v24.0.0, needs 26 or newer and the fix is install Node 26 or newer (https://nodejs.org), the same words the start-up message uses.
  • pack --check says when the browser build changed. When the committed manifest and the rebuilt pack both name a browser build and the names differ, the drift report adds one line naming both builds and telling you to rebuild the pack on the new build. The exit code follows the pixel comparison as before. A manifest with no build never triggers it. Third step of browser-build-pin.md. Surface item PACK-23, experimental.
  • diff says when the browser build changed. When both workspaces name one browser build each in annotations.json and the names differ, the text and markdown reports start with one line naming both builds, and the JSON report gains an optional browser_build ({ a, b }). Severity and exit codes are unchanged. Surface item PACK-24, experimental.
  • The pack manifest records the browser build. docsxai pack writes an optional top-level browser_build into manifest.json when every source annotations.json names the same build, and leaves it out when none does or they disagree. Validator, JSON Schema and docs/pack-manifest.md know the key. Second step of browser-build-pin.md. Surface item PACK-22, experimental.
  • docsxai render prints only the path to open. The success line was render: open <index> plus a parenthetical about halos and hovering; it is now render: open <index>. The viewer page explains its own halos.

Prerelease, published under the next dist-tag. 0.2.0 stays latest. Over 0.3.0-rc.3 it adds everything 0.3.0-rc.4 added (that tag was never published), the add-flow command, automatic caption placement at every width, themed burns at 2x, a hardened backend and a security pass.

  • annotations.json records the browser build. docsxai run writes an optional browser_build key (Chromium <version>, as the browser reports it) next to device_scale_factor. Older files have none and nothing treats a missing key as a mismatch. This is the first step of browser-build-pin.md; comparing builds in diff and pack --check follows. Surface item PACK-21, experimental.
  • CI recipe: viewer preview per pull request. docs/ci-recipes.md shows a workflow that renders the viewer, deploys .viewer/ under a per-pull-request name (Netlify, with a Cloudflare Pages swap) and links it in a pull request comment.
  • run --verify-determinism prints a next step. Under the first difference, the text report adds a try: line and the markdown report a Try: bullet: what to pin for that kind of difference (a changed image region, a size change, a time or id key, a text or binary file, a file in one run only). The JSON report keeps its shape.
  • Drift-gate GitHub Action. action.yml at the repo root installs a pinned docsxai, replays a workspace, diffs it against the committed baseline, writes the report to the job summary and comments it on the pull request. Inputs: workspace, version, base-url, baseline, fail-on, comment. Recipe in docs/ci-recipes.md.
  • Landing page rewrite: one purpose stated once (screenshot docs that never go stale), the stale prerelease version and unreleased-feature notes removed, five cards instead of six, shorter step text. Site meta description matches.
  • Contributor scripts: scripts/pre-gate.mjs runs prettier, eslint, per-package typecheck, single-file tests and the dash guard on changed files, and scripts/new-wt.sh creates a sibling worktree with an offline install.
  • scripts/layout-audit.mjs --engine chromium|webkit|firefox. Default chromium, exit 2 on any other value. Firefox has no mobile emulation, so below 768 px it gets touch without the mobile viewport. Centre pairs take an optional maxViewport, and hidden or 1 px clipped boxes no longer count as findings.
  • docsxai doctor says when an emitted site needs npm install. A workspace with a site/ folder that has no astro installed gets one informational site row (never a failure) with next: cd <dir> && npm install, then npm run build. A workspace with no site folder, or astro installed, prints the same output as before, and --format json carries the row with the usual keys.
  • Public copy lint: packages/engine/test/public-copy-lint.test.ts. Fails on environment-variable-like tokens, internal hostnames, private IPs, /srv paths and ticket or spec ids (DOC-, CLI-, PACK- and kin) in the landing and getting-started pages, llms.txt, the viewer's emitted UI (en and es) and the string literals of CLI and MCP errors and help, read with the TypeScript parser. Documented DOCSX_* names are allowed in CLI and MCP messages only. A second pass over mirrored docs, this changelog and package READMEs reports secret names, hosting providers, server paths and docs/ai-context pointers without failing
  • Screenshots in the emitted Starlight site open full size on tap. Each AnnotatedShot image is a link to its own file that the new ShotLightbox component turns into a button: a tap, Enter or Space opens the image at its native size in a full-screen dialog that pans and pinch-zooms. Close, Escape, a tap beside the image and a drag down on touch close it, focus stays inside while it is open and goes back to the image after. A small "Enlarge" hint shows on touch and narrow screens. Without JS the link opens the PNG. The labels are in English and Spanish, colours come from Starlight's theme, and the fade runs only without reduced motion. Sites get one more file, src/components/ShotLightbox.astro
  • First run in three commands: docsxai init <dir> --example, run, render --open. init --example makes a workspace for example.com with no login and writes the README's hello flow to flows/hello.flow.yaml; it exits 2 with --app-url, --auth, --role, --ttl, --capture-trigger or --auth-cookie. render --open opens .viewer/index.html in the default browser (open, xdg-open or Explorer, started without a shell) and prints the path instead where none can be opened. docsxai with no argument, the README and the quickstart lead with these three commands. Without the new flags, init and render print what they printed before
  • docsxai doctor --format json. One document with schema (docsxai/doctor@1), version, ok, checks (name, ok, info, detail, next) and next; every key is always present. Exit codes are the same as the text output
  • docsxai --version and -v print the installed version. They print docsxai <version> and exit 0, from the engine bin and the docsxai meta-package bin; docsxai-viewer --version prints docsxai-viewer <version>
  • One npm i -g docsxai reaches every output. docsxai render <workspace> --lang <locale> builds the viewer in that language (es gives Spanish). docsxai site <workspace> [--out <dir>] [--build] [--title <text>] [--accent <hex>] [--lang <locale>] [--flow <name>] writes the Astro Starlight docs site, with the same flags and exit codes as the viewer's site. The docsxai package now ships a docsxai-viewer bin that runs the viewer's own CLI, so the command is on your path after a global install. Existing commands are unchanged.
  • docsxai run --device-scale-factor <1-4> captures at 2x or more. Also read from DOCSX_DEVICE_SCALE_FACTOR when the flag is absent; default 1 leaves output byte-identical. annotations.json gets device_scale_factor above 1, its boxes and obstacles are in the PNG's device pixels, and docsxai burn takes its pixel ratio from the file
  • scripts/burn-trackxai.mjs --dpr burns 2x captures; the viewer burn takes pixelRatio. Raws in device pixels (ratio from --dpr, the sidecar's device_scale_factor, or PNG width over file-name width) burn with display_width in CSS px, so scale: "auto" gives 2.33 at 2560 px and 2.23 at 780 px. The phone header, bottom nav and floating button bands, side margins, text floors and the pixel text search scale with the ratio, and manifest entries keep width and height in CSS px and add png_width and png_height
  • docsxai-viewer <command> --help and -h print that command's usage. build, burn, site and pack show their usage lines and flag notes and exit 0, as docsxai help <command> does; docsxai-viewer --help and -h print the full help and exit 0. An unknown flag still exits 2
  • scripts/burn-trackxai.mjs --webp writes a lossless WebP twin beside each new PNG. It runs cwebp -lossless -z 9, keeps a twin only when it is under 100 kB and smaller than the PNG, and prints a warning with both sizes when it drops one. Without cwebp on PATH it stops with an install hint
  • Landing page "What it makes" section. docsxai.dev shows two product shots after the hero: a trackxai capture raw and burned with a caption theme, and the lines docsxai run prints for a matrix flow. Each comes in dark and light, follows the site's theme, sends 2x files (780 px, shown at 390 CSS px) to phones and has a lossless WebP twin under 100 kB. The terminal shot is composed from the engine's output format and the real trackxai flow counts, not a recorded session, and prints shorter lines at 390. node scripts/landing-showcase.mjs --raw <dir> --out website/public/showcase redraws them with satori and resvg and writes the manifest the page reads
  • burn warns about caption characters the font can't draw. Captions in a script the burn font lacks (Chinese, Japanese, Korean, Arabic, Hebrew, Thai, Devanagari or emoji with the bundled Inter) used to burn as empty boxes with no warning. The burner now checks each drawn caption against the font's character map and prints a warning naming the annotation and the script, the burn report entry gets missing_glyphs with the script names, and docsxai burn --strict-glyphs (also on docsxai-viewer burn) exits 1 when any caption has one. The fix is a font for the script in burn.theme.font_fallback, see the next entry. Guide: docs/burn-theming.md, Characters the font can't draw
  • Burned captions in Arabic, Hebrew, Thai and Devanagari, right to left for Arabic and Hebrew. The viewer package ships Noto Sans Arabic, Hebrew, Thai and Devanagari Regular, subsetted to their scripts (259 kB together, SIL OFL 1.1), and the burner falls back to them for characters Inter lacks. burn.theme.font_fallback lists up to 8 more TTF or OTF files in the workspace, tried in order before the bundled ones, for Chinese, Japanese, Korean or any other script. A caption whose first letter is Arabic or Hebrew is set right to left and its badge takes the target's top-right corner. Satori gets only the fallbacks a burn's captions use, so Latin burns, themed or not, keep their bytes. The glyph check covers the whole chain and still warns for scripts nothing covers. A word wider than the line breaks between characters (dictionary words for Thai), never inside one. Guide: docs/burn-theming.md, Other scripts and Right to left
  • scripts/layout-audit.mjs --mode states checks that status lines never shift layout. For each element in the config's states list it loads the page once per state (idle, pending, slow, failed, done), runs that state's steps and fails when the element's top or height moves by more than 1 px. scripts/layout-audit.states.json covers the copy buttons and the screenshot error line.
  • No em or en dashes left in the repo. Comments in source and tests, config files, fixtures, scripts and Markdown code samples use commas, colons or full stops, and number ranges use a hyphen. Wording only; no behaviour changes. scripts/no-dash-repo.test.mjs scans every tracked text file and fails on a dash outside a short exception list (agent hooks, CI definitions, third-party licence text).
  • A committed design audit allowlist and the brand docs match what ships. A static design detector run on the built site went from 8,416 findings to 46, and docs/design-audit-allowlist.md lists the 46 that are detector noise, each with its evidence. Print colours now use the system Canvas and CanvasText colours so they no longer read as screen colours, the hero install command has an even inset, and three terse "No X." lines read as plain sentences. website/scripts/check-design-allowlist.test.mjs fails if the list loses a column or an entry lacks a reason or evidence. brand.css, docs/ui-rules.md and the old UX audit note were corrected, and five unused colour tokens were removed.
  • Plainer prose across docs, READMEs, skills and help text. Filler words and contrast closers ("rather than", "not just", "unlocks", "robust") are gone, and padded paragraphs are shorter. Wording only; commands, flags and behaviour are unchanged. Two guards, website/scripts/check-prose-cadence.test.mjs for Markdown and packages/engine/test/prose-cadence-strings.test.ts for string literals in package sources, fail when they come back.
  • The docs site looks plainer. Eyebrows, lane and diagram labels, step numbers, window titles, the sidebar group labels and the llms.txt link now use the sans font in sentence case with no letter-spacing. Mono stays on code, command snippets and the flow-file excerpt. The hero grid, the page and hero glows, the card, window and code-block shadows, the primary button gradient and the callout side stripe are gone, and the body font is the system sans stack instead of Inter (one font download fewer). The card marks read Execution, Step 1 and so on instead of // execution. A new site test, check-type-tells, fails when any of these come back.
  • CLI help and error text lost its em dashes. Help, errors, doctor rows, MCP descriptions and messages, the viewer's English and Spanish text, burn report text, the plugin and skill content and the site components use commas, colons or full stops. Flags, commands, keys and exit codes are unchanged, but a script that matches printed text may need the new wording. packages/engine/test/no-em-dash-strings.test.ts fails if one comes back in a string literal.
  • Viewer pages: plainer styling. kbd keys use the page's sans face, the error notice has a full border instead of a thick left stripe, and cards, badges and callouts lose their drop shadows (a card outlines on hover instead). Headings balance their wrap, and the copy, retry and close buttons have an :active state. The emitted AnnotatedShot.astro and Starlight config comments no longer carry an em dash. packages/viewer/test/viewer-ui-guard.test.ts fails if mono, side stripes, layout transitions or blurred shadows come back. packages/viewer/scripts/viewer-ui-matrix.mjs <viewer-dir> runs the width, theme and orientation checks and exits 1 on findings.
  • The raw capture sidecar schema is now docsxai/raw-capture-sidecar@1. Same shape and version as trackxai/raw-capture-sidecar@1. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs read both names, exit codes are unchanged, and a run that met the old name prints one plain line saying so (in report.md for the probe batch). Docs and examples use the new name. Any other schema string still fails with the file name in the message.
  • caption_style defaults to auto at every width. A themed burn used full for captures 900 px and wider; now a caption with no clear spot (clear of text, header, nav, other captions and badges) falls back to its numbered badge, on desktop too. Desktop captures with no clear spot now show their badge only; set caption_style: full to keep the old behaviour. An explicit full or badge still wins, and a burn with no theme is unchanged. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs no longer pick the style by width.
  • docsxai add-flow is the command to add a flow; calibrate is retired. calibrate is deprecated since 0.3.0 and will be removed in 0.5.0. Until then it prints docsxai: calibrate is deprecated since 0.3.0, use add-flow (calibrate will be removed in 0.5.0) on stderr once and runs add-flow with the same arguments and exit codes. Output lines now start with add-flow:. --help, the start screen, next: hints, the workspace README and the doc pages name add-flow, and docsxai help calibrate prints the add-flow help. The plugin skill is renamed to match: /docsxai:add-flow drives the agent, and /docsxai:calibrate stays as a short skill that points to it until 0.5.0. push --kind calibrate is a stored revision kind and stays.
  • Backend wiki-push settings moved to the operator (breaking). A stored wiki-push config with plugin_config.sources, a base_url or other url key on a host the operator didn't list, or a secret_env that isn't DOCSX_WEBHOOK_SECRET or DOCSX_WEBHOOK_SECRET_<SUFFIX> now fails: a PUT gets 400 naming the field, a stored config fails its runs with the same message, and deliveries signed under an old secret_env get 401. path: plugins in a workspace docsxai.config.json are ignored by the backend. To fix: put each publisher directory (absolute path) in DOCSX_BACKEND_PLUGIN_DIRS and drop plugin_config.sources, add each base_url origin to DOCSX_BACKEND_PUBLISHER_ORIGINS (https: only), list the variables a publisher may read in DOCSX_BACKEND_PUBLISHER_ENV (it used to see the whole backend environment), and rename a custom secret_env to DOCSX_WEBHOOK_SECRET_<SUFFIX>. Refresh tokens now expire 30 days after they're issued, set by DOCSX_OAUTH_REFRESH_TTL_DAYS; a client idle for longer runs docsxai login again. A bad value stops the server at start.
  • docsxai.dev tells one install story. The hero copies npm install -g docsxai@next and names 0.3.0-rc.3 once, Get started opens the Quickstart, and the Quickstart starts with the install step. The separate Install section is gone, the first-run steps use about half the words, and the site description, structured data and llms.txt match.
  • Burned captions follow the capture's pixel ratio. Without scale in burn.theme (no theme, or the clean, soft and high-contrast presets), the caption scale is the pixel ratio from device_scale_factor instead of 1, so a 2x capture's caption has the 1x capture's CSS size. 14 px text on a 2x capture read as 7 CSS px before. scale: "auto" never goes under the pixel ratio and caps at 4 times it. 1x burns keep their bytes. Burns of 2x captures change once, and pack --check against a pack built from them exits 1: rerun docsxai pack and commit, or set burn.theme.scale: 1 to keep the old size. An explicit scale number is used as written. In code captionScale takes the pixel ratio as its third argument instead of the CSS width, and the resolved theme's scale is null when no layer sets it.
  • The viewer loads step screenshots lazily after the first two and draws overlays only near the viewport. Step 3 onward gets loading="lazy" decoding="async", with width and height from the PNG as before, so a 500-step flow no longer fetches every screenshot on open. Halos, badges and callouts are drawn when a shot comes within a screen of the viewport, and a resize or rotation redraws only those, measuring every label of a frame in one batch. Printing still draws every loaded shot. scripts/layout-audit.mjs takes pageStates in its config (click, scroll to the bottom, wait for a selector), and scripts/layout-audit.states.json holds a lightbox state and a lazy-scroll state beside the copy-button states
  • Themed burns keep badges and captions off the edges, and lines off captions. A badge keeps 6 CSS px off every image edge, 12 off the sides of a desktop capture and 6 off a full-height page divider such as a sidebar's edge, and a desktop caption keeps 12 off the sides. A line never runs behind a caption or badge drawn before it: when no route crosses nothing, the burner takes a caption spot and line end that miss them. Burns without a theme keep their bytes. Guide: docs/burn-theming.md, Clean halo and badge.
  • docsxai doctor speaks the user's language and suggests the real next step. The first line is ok: version: docsxai <version>. The viewer row says found at <path> and the env row counts the variables you set, so a global install no longer shows a variable name or a lookup layer it set itself. When every check passes, the last line suggests init <workspace-dir> --example outside a workspace, calibrate with an empty flows/, run with nothing captured and render --open once there are annotations; it used to say run every time
  • Public copy trimmed. Removed internal pages and wording from public docs and CLI output. 5xx backend errors now say to try again and contact whoever runs the backend.
  • Themed burns route the line connector around text. When a caption is clear but its line crosses an obstacle, another halo, badge or caption, the burner moves the caption to the spot with the shortest straight line that crosses nothing (a clean hinted side wins), else draws the line with one right-angle elbow, else keeps the spot it had. caption_style: "auto" keeps a caption it can route. The burn report gains route (straight, elbow, none) and connector_crossings for line burns. Burns without a theme keep their bytes. Guide: docs/annotation-placement.md, Routing the line.
  • docsxai.dev serves /showcase/* with a one-year immutable Cache-Control. The landing images are hash-named, so the site config caches them like /_astro/*; a test checks the rule and that public/showcase holds only hash-named images plus manifest.json.
  • Landing hero flow diagram: the muted expect toast line meets 4.5:1 in both themes. .dxf-flow code.muted goes from opacity 0.6 to 0.85 (dark 4.35:1 and light 3.55:1 before, light bold part 2.84:1); check-flow-contrast.test.mjs computes the pairs.
  • Guide: themed caption packs. docs/themed-caption-packs.md (also on docsxai.dev) takes raw captures from docsxai run to hash-named PNGs, lossless WebP twins and a screens-pack manifest with a light and a dark tokens file, then covers sizes per width class (scale: "auto", display_width with narrow_below), connector_style and caption_style with the rule for the badge fallback and the legend it needs, reading the burn report and scripts/burn-probe.mjs, a no-overlap test a project can copy, and a worked example with a light and dark tokens pair from examples/burn-theme/.
  • scripts/burn-probe-batch.mjs checks a whole folder of raw captures. It burns every frame of a flat (<screen>.<locale>.<theme>.<width>.png) or rawcap (<flow>/<step>/<locale>.<theme>.<viewport>.png) folder with a tokens pair from examples/burn-theme/, writes the burned PNGs to <out>/previews/ and a report.md with one row per annotation (mode, side, connector length, caption over text and over the phone header and nav, connector crossing text, badge next to its target, OK or CHECK), CHECK rows first. Repo script, not in the npm packages. Guide: docs/burn-theming.md, Checking a whole capture folder.
  • Second example tokens pair and burn-probe-batch.mjs --project. examples/burn-theme/remotxai-light.tokens.json and remotxai-dark.tokens.json carry a teal docs look (17 px text, display_width 800, 390 under 900 px). --project trackxai|remotxai picks the probe's default tokens, and --tokens-dark and --tokens-light still override. Guide: docs/burn-theming.md.
  • Landing page first-run section. docsxai.dev gains a "First run" section after Install: init --app-url, doctor, calibrate through the Claude Code plugin with an example request, run, and render to open the viewer, each with a copy button and one line of expected output, then a link to the quickstart. The page now names the readable preset, the second display_width for narrow captures, --lang and pnpm setup for a pnpm global install.
  • Themed burns join callouts to targets with a thin line. With a burn.theme, the connector is one 2 px line (multiplied by scale) from the caption edge nearest the target to the target's edge, ending in a small dot. It replaces the triangle and stem, and the white outline over dark pixels. The line takes callout_border_color (ink without an outline) and switches to the callout's text or fill colour where that is under 3:1 against the pixels under it. The halo ring moves 3 px outside the target and the badge sits off its corner, so neither covers text in the target. Text found in the screenshot pixels joins the annotation's obstacles, and a caption that would cover text moves up to 176 px out, or docks along the top or bottom edge, with a longer line. A caption covers no text when any clear spot exists, trying a one-line wide box and one text step smaller first. Badges sit at the target's corner, off text. Portrait phone captures keep captions and badges off the header, bottom nav and floating button. New key caption_style (full, badge, auto): badge draws only the numbered badge and ring, auto falls back to it where no caption spot is clear, or where the connector would cross text, and marks it in the burn report. New key connector_style (token shape.connector): auto (default: the line with a theme, the triangle without), line, chevron (an open chevron at the target) or arrow (the triangle and stem as before). arrow_style still picks the side. Burns without a theme keep their bytes. Sample: node scripts/burn-trackxai-sample.mjs with the examples/burn-theme/trackxai-*.tokens.json pair. Guide: docs/burn-theming.md, Connectors.
  • Themed burns with connector_style: "arrow" paint the arrow and stem in the callout's fill on dark screenshots. With a burn.theme, a triangle connector over dark pixels is drawn solid in callout_background, so it reads as the callout's tail. The dark-ink-with-white-outline look stays where a tenth or more of the pixels under it match the fill, and for burns without a theme, which keep their bytes. A light connector on light pixels mirrors this with a dark callout fill.
  • Themed burns balance callout lines. With a burn.theme, a callout keeps the number of lines the plain wrap gives and narrows to the smallest width that holds them, so no line ends with one word left over. A one-letter word (Spanish a, y, o) and the list number stay with the word after them, and a path or URL wider than the line breaks after /, -, _, . or :. Burns without a theme wrap as before.
  • Plugin and vendored skill text matches the CLI. /docsxai:run names the flow variants and single flow forms of the summary line and the indented next: lines, /docsxai:render and calibrate say render has no language flag and point at docsxai-viewer build and site with --lang, /docsxai:doctor names --offline, /docsxai:login shows its login: ok. line, /docsxai:export notes that --out applies to adf too, /docsxai:pull lists matrix variant paths, and calibrate drops a pointer to a step that does not exist, adds wait_for: load, copy_by_locale, the two-width display_width form and an accurate init next-step list. diagnose covers a target hidden by an earlier hide step. The plugin tests now pin the MCP tool list, the burn.theme numbers, the --lang claims and the summary line wording against the source.
  • Docs: burn report keys route and connector_crossings, the --badge-only flag, and device_scale_factor as the burn pixel ratio are documented. The burn and annotation guides cover them, and AGENTS.md states the --testTimeout=30000 rule for test scripts.
  • User-facing copy drops internal wording. The backend's consent_required message says to ask whoever runs the server to turn on sign-in approval, and no longer names a server setting. docsxai --help, the MCP pull_pack description and the pull command say "someone else's edits" and "local session state". docsxai.dev no longer shows phase-plan pointers or release-milestone notes on the app-repo guide and the plugin pages, and the burn guides and examples/burn-theme/ describe the example tokens pairs without product names. File, script and --project names are unchanged.
  • Docs and site copy carry no em or en dashes. Every Markdown page, README, agent guide and release note was reworded with commas, colons and full stops, and a test now fails on a dash outside a code block.
  • Viewer footer and empty state copy. The footer says Rendered by <version>. and no longer tells readers to hard-reload (English and Spanish). The empty site says to build the site again instead of "re-emit". The screenshot error overlay keeps its message and Retry button in view on short screenshots (place-content: safe center).
  • Viewer step moves are announced every time. Pressing End on the last step, or Home on the first, repeats the same message. The live region now clears first, so a screen reader reads it again instead of staying silent.
  • Screen reader pass over the site and the viewer. Task-list checkboxes in the docs now carry their item text as a name. The viewer's back arrow keeps its space, the copied check mark is no longer read aloud, headings balance their lines and prose caps at 70ch. docsxai-viewer a11y-lint gains labelledby-heading, glyph-hidden and badge-space, and the site tests scan every built page for one h1, heading order and labelled controls.
  • Docs site UI pass. The skip link is 44px tall when focused, the footer credit links are 24px tall on desktop, the footer middots are hidden from screen readers and no longer fail contrast, and stacked tables on phones keep links and code inline inside a cell. Spacing in the site stylesheet sits on a 4px scale, three dead selectors are gone, and :active and :disabled states exist on the buttons. scripts/rendered-check.mjs checks contrast, target size, clipped text and horizontal scroll in a real browser, and website/scripts/check-ui-classes.test.mjs fails on layout-property transitions, missing control states, unbalanced headings, off-scale spacing, dead selectors, measure over 75ch, filled surfaces without a text colour and small skip or credit links.
  • docsxai init --example then run works again. example.com no longer has a heading, so the hello flow now points at its English paragraph (p[lang="en"]) with the copy "This is the page text". The keystone serves a page shaped like the live one. The missing-Chromium hint in doctor, run errors and --help no longer names the source-checkout command.
  • docsxai site --build names the folder when astro is missing. From a global install it printed cannot resolve the astro package, pass astroBin, .... It now writes the site, then says astro is not installed and to run npm install and npm run build in the site folder. The exit code is still 1.
  • Docs match the CLI again, and a test keeps them matched. The flow-tree sample showed [5 steps] and depth 1 where children print [+5 steps] and the chain is 2 deep, the lint sample had an old R004 hint, render, inspect and plugins sync samples dropped lines they print, the doctor sample counted 10 checks for 9, style on a bad path quoted the wrong message, and the runbook and viewer README said site warns on a missing docs/ folder when it exits 1. docs-cli-usage.test.ts reads every shell block in the README, package READMEs, plugin commands and skills, docs/*.md and the docs site against its usage line (arguments, required flags, enumerated values), holds the CLI reference synopsis to the real docsxai --help usage lines, and checks the public-surface CLI and ENV rows, the lint rule table and the doctor variable list against the code. docs-cli-transcripts.test.ts holds every sample output line in the CLI and plugins references to the line shapes the commands print. The viewer has the same usage check for docsxai-viewer.
  • docsxai.dev: flags keep their --, anchors stay in the column, every code block wraps. The landing hero showed an em dash before flow and fail-on because the Markdown processor's smart punctuation turned -- into an em dash; the site now renders punctuation as written (tests cover the config, the rendered text and the built pages). Heading anchor links kept their 44 px target but no longer hang past the right edge, which scrolled /reference/cli/ at 320 px and /guides/burn-theming/ at 360 px sideways. Transcript output and JSON, YAML and plain-text blocks wrap with indented continuation lines like command blocks (27 of 64 blocks on the CLI reference scrolled at 1280 px); the backend page's flow diagram keeps its columns and scrolls. Paragraphs stop at 75 characters from 800 px, so insets match at 721 to 799 px.
  • A screenshot that fails to load no longer moves the page. In the viewer and the Starlight site, the error line and its Retry button now sit inside the screenshot's box, and the box keeps its size when the file fails, so failing, retrying and loading again leave every step where it was. Before, the line was inserted under the image and a broken image could shrink to a line of text.
  • Copy buttons run one copy at a time. The viewer, the Starlight site and docsxai.dev ignore a click while a copy is still pending. On docsxai.dev the "Ctrl+C" fallback label has its own slot beside "Copy" and "Copied", so no state changes the button's size.
  • Viewer badges near the right or bottom edge stay inside the image. The clamp assumed a 22 px badge; the drawn badge is 38 x 26 px (22 px plus padding and border), so a badge on a target at the edge stuck out up to 16 px and could make a phone page scroll sideways. The clamp and the badge CSS now read the same constants
  • docsxai.dev fixes from the real-browser QA run (14 findings). Chromium now blurs the header and the "On this page" bar, wide tables stack as cards on phones, the menu button icon is centred and themed, the CLI reference blocks wrap, code blocks, tables and the hero transcript fade at the scroll edge, the landing keeps its theme switch and GitHub link on phones, the hero box fills its column, single-column pages have equal insets, logo and heading-anchor targets reach 44 px, landing links and note asides use the ember palette, and the sticky TOC bar scrolls away on landscape phones. check-site-qa.test.mjs pins the rules; website/layout-audit.json configures scripts/layout-audit.mjs for the five audited pages
  • renderBurn rejects a pixelRatio outside 1 to 4. 0 with scale: "auto" ended in Invalid typed array length: Infinity, and NaN or a negative ratio burned at a wrong size without a word; each now throws pixelRatio must be a number from 1 to 4.
  • scripts/burn-probe-batch.mjs burns 2x raw captures at their device scale. A frame whose sidecar has device_scale_factor, or whose PNG is exactly 2 to 4 times its file-name width, now burns, picks caption_style and checks phone chrome in device pixels; before, the probe drew every frame at 1x and graded 2x captures wrongly. An out-of-range device_scale_factor fails that frame.
  • docsxai-viewer build|burn|site read --flag=value, and reject an empty or repeated value. --flow=a was an unknown flag, --out "" and --max-overlap "" fell back to their defaults, and a second --out or --title silently won. --flow still repeats.
  • docsxai-viewer pack burns 2x captures at their device scale. A workspace annotations.json with device_scale_factor, or a raw capture sidecar with the same key, now reaches the burner as its pixel ratio, as burn already did; before, pack drew captions at 1x size on a 2x screenshot. A value outside 1 to 4 stops the pack and names the file.
  • docsxai run rejects an empty value for its value flags. --flow "", --variant "", --stop-after "", --start-from "" and --cdp "" were read as unset and ran every flow or variant; they now exit 2 with needs a value.
  • docsxai run --start-from no longer merges steps captured at another device scale. Earlier steps in an annotations.json recorded at a different --device-scale-factor (absent counts as 1) are dropped with a warning, since their boxes are in other pixels than the re-run steps and the file has one device_scale_factor.
  • Quickstart flow passes docsxai lint with exit 0. Its annotation names target: $nav_reports, so lint no longer warns R002 and exits 1 on the page's own example, and the sample run lines match what run prints (run: open-reports, starting).
  • Landing page fits 320 and 360 px phones and 200% text. The hero's run transcript wraps its last column under 34rem, where it scrolled sideways, and the feature cards drop to one column when 15rem is wider than the screen.
  • Spanish viewer and site text reviewed. Instructions now use tú imperatives ("Pulsa Ctrl+C", "Comprueba tu conexión") with one term per concept (captura, paso, flujo, anotación, ID), "registro de anotación" becomes "anotación", and a term table in ui-strings.test.ts pins them
  • docsxai run accepts file:// URLs again. The URL check added for --base-url and app_url refused file://, which broke runs against a local static site. run takes http://, https:// and file://; ftp:, javascript:, data:, mailto: and garbage still exit 2 (--base-url) or 1 (app_url). init --app-url and login --backend-url stay http(s) only.
  • Landing page and burn theming guide no longer name 0.3.0-rc.4 as the installable prerelease. The install note and the CLI card said docsxai@next is 0.3.0-rc.4, and the availability note on the burn theming guide said burn.theme is available from it through docsxai@next; next is 0.3.0-rc.3, as the README and Installation page say. They now name 0.3.0-rc.3 for next and say burn.theme is new in the next release. New tests load every burn block in docs/burn-theming.md and the burn-theme example through the real theme loader, validate the manifest in docs/pack-manifest.md, parse the flow files in the README, quickstart and flow-file reference, and check the docsxai commands and flags of the guides and example READMEs against docsxai --help.
  • Burn help and guides match the code. docsxai burn --help and docsxai-viewer burn --help say that --no-connector-outline skips reading the screenshot's pixels, so a themed line keeps the callout's outline colour and no text is estimated, and that burn.theme sets the look. The theming guide covers caption_style, the clean halo and badge and the phone chrome numbers, and gives the auto factor of a 780 px capture at the default display_width as 1.09 (it said 1.08). The landing page no longer says docsxai@next is 0.3.0-rc.4.
  • A side hint no longer pulls a short callout onto a neighbour. The bonus arrow_style or placement.side gives its side now outweighs at most a 2 px strip of content along the callout's width. A 60 px label on a phone screenshot used to keep its hinted side over 6 px of a neighbouring control. Callouts 200 px wide or more score as before.
  • plugins sync with three plugins on one namespace. It locked the last of them and named only the second as not locked. It now locks none of them and names every claimant.
  • Two flow files with one name:. run started both and let them overwrite one docs/<name>/, and lint and flow-tree kept only the last. All three now stop with exit 1 and name both files.
  • A value flag given with no value. init --app-url, inspect --url, lint --flow, export adf --out, zip --out, push --kind and pull --rev (and the other value flags of those commands, calibrate, diagnose, style, flow-tree, capture-auth and plugins) silently fell back to their default, so export adf --flow exported every flow. They now exit 2 with <flag> needs a value. inspect --wait soon and init --persist disk exit 2 too, where they used to wait 0 ms and scaffold into the given directory.
  • Matrix viewport names screenshots, halts and Windows device names. A viewport named screenshots or con made a variant directory that pull refuses and Windows cannot create. The flow-file parser now rejects screenshots, halts, con, prn, aux, nul, com1 to com9 and lpt1 to lpt9 as viewport names.
  • Session cache files. Roles a/b and a_b shared .auth/a_b.json, so one role ran with the other's session, and a role named backend-token overwrote the OAuth token file. A role with characters outside A-Za-z0-9_.-, and backend-token, now gets a hash suffix in its file name (an existing cache for such a role is re-captured once). The cache file is also written with mode 0600; it was group-readable under a default umask.
  • style on a path that does not exist. A mistyped workspace path got a new docs/style.yaml tree created under it and exit 0. style now exits 1 with <path> is not a directory and writes nothing.
  • push with a doc pack it cannot read. An invalid docs/style.json made push throw after it had created a backend workspace, a project and an unfinalized revision. It now reads the pack first, exits 1 naming the file, and touches the backend only when the pack reads. The .docsxai.json that records the backend ids is written atomically.
  • pull with an unknown artifact name in a revision. The names a backend listed went into the request path as they came, so ../../x reached another endpoint with the bearer token. pull now requests only flows, annotations, screenshots, style and locators, and prints a warning for any other name.
  • zip followed symlinks in its fixed entries. README.md, .docsxai.json, auth/strategy.yaml or docs/ linked to a file or directory outside the workspace went into the archive with the target's content; only entries found below a directory were checked. All entries get the check now. zip also creates the output directory only after it has something to write, and writes the archive atomically.
  • push read files behind symlinks. A flow file, annotations file, screenshot, style.yaml, style.json or locators.yaml that was a symlink to a file outside the workspace was read and sent to the backend. Those files are now left out of the pack.
  • pack --check --threshold "". An empty or blank threshold passed as 0 percent. It now exits 2 like any other value that is not a percentage of 0 or more.
  • docsxai-backend answers 400 to a request target the URL parser rejects. A request line such as GET // or GET //[ returned a 500 with Invalid URL; it now returns a JSON bad_request.
  • Webhook run history records the revision that ran and the runs that never started. A head revision that moved while the engine ran was recorded as the newer head, and a job whose payloads could not be laid out left no row. The row now names the revision the run executed against, and a failed materialization appends a failed run with the reason.
  • Webhook repo matching ignores case. A delivery whose owner/name differs only by case from the configured repo got a 404, because GitHub treats the name case-insensitively. Both stores now match it.
  • FsStore lists projects in creation order. It listed them, and picked the project for a webhook repo, in id order; MemoryStore used creation order. Both stores now agree.
  • Docs site at 390 px, round two. Shell commands in code blocks wrap with an indented continuation line, where they used to scroll sideways, and the copy button still copies one command. The "On this page" dropdown links are 44 px tall. The landing diagram's 10 px labels grow to 12 px once the panels stack.
  • Installation and Quickstart match the CLI. Installation describes doctor's ok:, fail: and next: lines. The Quickstart shows the starting line run prints for each flow, points at the flows/example.flow.yaml.sample that init writes and how calibrate --from turns it into a flow, uses http://localhost:3000, and says a callout opens on hover, tap or Tab.
  • docsxai doctor usage lists --offline. The Usage: line in docsxai --help, docsxai help doctor and the CLI reference now show docsxai doctor [<workspace-dir>] [--offline], the flag the handler already read. A new test pins the flags of every command against its usage text, its help screen and the flags its handler reads, so a flag added to one without the other fails the suite. The header comment of docsxai-viewer lists the flags its usage text shows.
  • Unknown and repeated flags. run --flwo x ran every flow, because a flag no command reads was ignored, and --flow a --flow b kept the last. init, calibrate, inspect, run, lint, flow-tree, diagnose, style, zip, baseline, diff, export, plugins, login, push, pull, render and capture-auth now exit 2 on a flag they do not take, with a did you mean when one is close, and on a flag given twice. burn and pack already did the first.
  • run --pause <workspace>. The flag took the workspace as its value, so run reported a missing workspace. Flags that take no value (--pause, --headed, --force, --check, --fresh, --headless, --ignore-https-errors, --include-viewer) no longer read the next argument, and --pause=yes exits 2.
  • Flow name that differs from its file name. flows/payment.flow.yaml with name: checkout ran fine, but extends: payment found nothing and the output went to docs/checkout/. lint now warns (R017) and names both. run is unchanged.
  • pull that failed partway. writeDocPack wrote flows, then annotations, then screenshots one file at a time, so a disk error or a path in the way left a workspace holding part of the new revision and part of the old. Every file is now staged next to its target first and renamed into place together; a failure while staging changes nothing and a failed rename puts the swapped files back.
  • export adf and export playwright followed symlinks. A flow file, step markdown file or screenshot that was a symlink to a file outside the workspace was read: its text went into projection.json, and its path into attachments.json for a publisher to upload. Those files are now left out, as zip and push do. A symlink to a file inside the workspace still works.
  • doctor with an unknown or repeated flag. doctor --ofline ignored the flag and probed app_url. It now exits 2 on a flag it does not take, with a did you mean when one is close, on --offline given twice, and on --offline=yes.
  • --cdp connection left open. Commands that attach to a running Chrome (run, inspect, diagnose, capture-auth) kept the CDP connection when setup failed after the connect (no context to create, no page to open, a refused binding), and close() dropped nothing. inspect --headed --cdp skipped the close altogether. The connection is now released on every exit path, once; a context that docsxai created in the attached Chrome is closed first, and the operator's own contexts and tabs are never touched. A capture-auth browser launched fresh is also closed when its first navigation fails.
  • run --concurrency lost results when one flow's cleanup threw. A browser that failed to close, or a --pause wait that threw, rejected the whole worker pool: run ended with an unhandled error and no summary while the other workers kept writing. A close failure is now a warning on stderr, the browser is closed even when the pause wait throws, and any other throw that escapes a flow is recorded as that flow's failure, so every flow still gets its line in the summary.
  • Ctrl-C and SIGTERM during render, burn or pack. The signal went to the viewer child and docsxai waited for it with no limit: a child that ignored the signal hung the command, a second Ctrl-C did nothing, and a child that exited 0 on the signal made docsxai exit 0 after printing interrupted. The child now gets SIGKILL 10 s after the first signal, a second signal ends docsxai at once with 130 or 143, and an exit 0 after a signal becomes 130 or 143.
  • run --start-from or --stop-after with a step id that does not exist. The browser launched first and the run then ended as a failed flow, exit 1 with a doctor hint. Both flags now check the id against the selected flows before anything launches, exit 2 and list the steps the flow has. --stop-after still runs when at least one selected flow has the step.
  • Viewer links and images for names with #, ? or %. docsxai render percent-encodes these characters in the screenshot, flow-card, thumbnail and previous/next flow URLs. A step id such as a#b used to point at a and show a broken image.
  • docsxai render --flow with repeated or unknown names. A flow named twice produced two pages and two index cards, and a name with no folder under docs/ produced an empty page with no message. Each flow now renders once, and an unknown name is skipped with a warning.
  • docsxai render with a directory named like a screenshot. A directory called <step>.png under screenshots/ crashed the copy. The step now shows the missing-screenshot state.
  • docsxai-viewer site with a damaged annotations.json. A file whose annotations is not a list, or a record whose step is not a string, crashed the emit. The site now warns with the same reasons render shows, skips the bad records and falls back to the screenshots. A directory named like a screenshot counts as a missing screenshot.
  • docsxai-viewer site builds with quotes, &, spaces, #, ? and % in names. A step id with " or & was written as a JSX string without escapes, so astro build failed to parse the page. A flow name with a space gave a page slug the sidebar did not link to, and an image named with #, ? or % could not be imported. Such values are now passed as JavaScript strings, flow pages and images use a slug of letters, digits and hyphens (a second flow with the same slug gets -2 and a warning), and the heading escapes *, _, [, ], & and ~. Flow and step titles on the page keep the original names.
  • docsxai-viewer site --build explains a build that never ran. A missing site directory was created as a side effect, and a build killed at the 10 minute limit or a process that could not start left site: astro build failed with nothing under it. Each case now prints its reason.
  • docsxai render and docsxai-viewer site warn about a missing docs/ folder. A mistyped path wrote an empty viewer or an empty site and exited 0 with no message. The empty page is still written, and the command now prints a warning naming the folder.
  • docsxai-viewer site --title with a blank value or a line break. An empty or whitespace title produced an empty site title, and a title with a line break or other control character broke the page front matter. A blank title now falls back to Documentation and control characters become spaces.
  • docsxai pack guard scans generated_for. The publish guard checked titles, captions, alt text and callout copy but not --generated-for, which lands in the public manifest. A token or email pasted there now stops the build like any other leak.
  • docsxai-viewer site with names that are not plain path parts. A step id such as ../../x or a flow name with : or \ was joined into the output paths, so an image could land outside src/assets/flows/. These flows and steps are now skipped with a warning, the same rule render applies.
  • docsxai-viewer site warns instead of staying silent. A --flow name the pack lacks, and a docs/style.json that is not valid JSON (its accent and logo were dropped without a word), now each produce a site: warning: line.
  • --lang with a language that has no text table warns. docsxai-viewer build --lang fr and docsxai-viewer site --lang fr wrote English pages and said nothing. They now print a warning that only en and es have tables; the output is unchanged.
  • docsxai-viewer build --flow <flow> renders the variants of a matrix flow. burn --flow already selected <flow>/<variant>, but build --flow login on a flow with only variant folders wrote an empty login page and none of the variants. build now selects them the same way, and a repeated --flow name burns once.
  • docsxai-viewer site says when it leaves matrix variants out. A flow that ran a matrix: block keeps its output in docs/<flow>/<variant>/, which render shows and the site does not read. A pack of only matrix flows produced an empty site with no message, and --flow <name> for one reported a missing annotations.json. Both now print a warning that names the variant folders.
  • docsxai-viewer site removes pages of flows that left the pack. Emitting into an existing site directory only added files, so a deleted flow or step kept its page and images, which Starlight still built and indexed for search. The emit now deletes files under src/content/docs/flows/ and src/assets/flows/ that it does not write; everything else in the directory stays.
  • docsxai pack names the bad field in a damaged annotations.json. A bounding_box with a string for x, a placement.side that is not a side, or a bad nudge, obstacles, arrow_style or index failed inside the burner with inputValue.trim is not a function or Cannot read properties of undefined. The pack now stops with the file, the record's position and the field, for the records of steps it reads.
  • Copyable capture commands quote odd names. The docsxai run --flow ... --start-from ... command that render and docsxai-viewer site offer for a missing screenshot was pasted as written, so a step id or flow name with a space, quote or $ split into several shell words or ran as code. Both pages now single-quote such names the POSIX way; plain names stay bare.
  • docsxai burn no longer aborts on an annotation whose box is off the image or has no area. A bounding_box that lies outside the screenshot, has zero or negative size, or holds NaN or infinity used to crash the process inside the rasteriser. Such an annotation is now skipped with a warning that names its selector and step, and burn --report lists it with skipped set. A box that only overhangs an edge is clipped to the image.
  • docsxai burn no longer throws on a nudge with a NaN or infinite part. Satori rejected a NaN position, and an infinite one drew the callout off the image. Such a part now counts as 0.
  • A viewport-only variant such as <flow>/sm no longer sets the page language. sm, md, lg, xl and xs read as locale tags, so docsxai-viewer build and site ignored --lang for those flows. The first part of a variant id is now checked against the color schemes (light, dark) and the viewport names (desktop, tablet, mobile, xs to 2xl, a width such as 1280, mobile-390, 1440x900) before it counts as a locale, and a <flow>/<step>/<locale>.<theme>.<viewport> id reads its locale from the last part.
  • Screenshots with no annotation record stay in render and site. When annotations.json held records for some steps, the viewer page and the Starlight page listed only those steps and dropped the other screenshots. They now follow the annotated steps as plain screenshots, in name order.
  • An unreadable annotations.json stops with an error that names the file. A permissions error or a directory in its place was read as "no annotations": render and site carried on without callouts, and burn said the file was missing. All three now report the path and the error code, and burn also names the file when it is not valid JSON (render and site keep warning and listing the screenshots).
  • A browser that will not start. run, inspect and capture-auth print one reason and one next: command instead of Playwright's banner and call log: no Chromium binary gives the install command, and a --cdp endpoint nobody listens on gives cannot attach to the browser at <endpoint> (ECONNREFUSED) and the --remote-debugging-port flag to start Chrome with. run --cdp no longer asks for a cached session first, because an attached browser owns its own login.
  • First-run start-up errors. init --app-url, run --base-url and login --backend-url reject a value that is not an http:// or https:// URL with exit 2 and the command's usage line (login no longer asks for DOCSX_TOKEN first). run stops on an app_url in .docsxai.json that is not a URL and names the file. init on a path that is a file says so, and a refused mkdir points chmod at the existing parent. run, lint and flow-tree on a workspace whose flows/ was deleted print mkdir <dir>/flows, and on a non-empty directory without .docsxai.json say it is not a workspace; neither suggests init, which refuses a non-empty directory. A cached session that is not valid JSON is called corrupt instead of expired. A plugins entry of the wrong shape shows the two shapes that work.
  • docsxai doctor on a broken workspace. A .docsxai.json it cannot read (EACCES) fails with chmod u+r <file> instead of reading as "no workspace"; a config that holds an array, null, a string or a number says what it holds instead of schema "undefined"; invalid JSON points at the position in the file instead of suggesting init --force, which rewrites it; a workspace path that does not exist or is a file fails; a deleted flows/ gets mkdir <dir>/flows; and the plugins row no longer repeats a config failure the workspace row already printed. doctor exits 2 on a flag it does not know (a typo such as --offine used to probe the network), and its usage line lists --offline.
  • Unreadable .docsxai.json in run and capture-auth. A config file that exists but cannot be read now prints the was ignored (it cannot be read, EACCES) warning with the next: line. It used to pass as a missing file and say nothing.
  • docsxai on Node 18 and older. The CLI prints docsxai: Node v18.20.5 is too old to start (the engine requires Node >= 26) and a next: line, and exits 1, before Playwright's own text appears. Node 20 to 25 start as before, and doctor fails the node row for them.
  • Printed text loses its em dashes. --help for the engine, plugins and the viewer, doctor detail and fix lines, diagnose recommendations, the run, push, pull, inspect, capture-auth and render progress lines, the browser login page and the generated workspace README use commas, colons or full stops. The cli.md and runbook samples match. Generated Playwright specs keep their comments.
  • Exit code for a missing prerequisite is unchanged. lint, flow-tree, diff, push and pull exit 2 and run exits 1 when flows/, a baseline or backend_url is missing; tests pin both and the runbook documents the split.
  • inspect exits 1 when the page does not load. It printed a warning, listed chrome-error://chromewebdata/ and exited 0. It now prints inspect: could not load <url> (<reason>) with a next: start the app, then docsxai inspect <workspace-dir> line and exits 1.
  • run_flows words a browser that will not start like the CLI. The run_flows MCP tool now reports no Chromium binary found or cannot attach to the browser at <endpoint> (ECONNREFUSED) in error and the install or Chrome command in hint, from the same helper run uses. Other launch errors keep Playwright's text. describeBrowserLaunch and CHROMIUM_INSTALL are now exported from @docsxai/engine.
  • A file where .auth/ should be. capture-auth, run, inspect, doctor and the run_flows MCP tool name the file, say it is a file where a directory is needed (ENOTDIR) and give next: mv <file> <file>.bak. capture-auth used to print Playwright's raw ENOTDIR: not a directory, mkdir, run and inspect called it a missing session, and doctor passed the writable row. doctor flags a file at flows/, docs/ or .viewer/ the same way, and any other command that hits ENOTDIR prints this message instead of an unexpected-error report.
  • A workspace path that does not exist or is a file. export adf, export playwright, style, baseline, push and pull print workspace doesn't exist: <dir> (or <path> is a file, not a workspace directory) with a next: line and exit 1. export, style and baseline used to exit 0 and create the directory with .export/, docs/style.yaml or .baseline/ in it, and push and pull blamed a missing .docsxai.json. baseline on a file path no longer prints a second docsxai: line.
  • Output the disk refuses in export, zip, style and baseline. The message names the path you gave, never the temp file or staging directory the engine writes first, and the next: line is chmod u+rwx on the directory that denies the write when the target does not exist yet (it used to be a chmod -R on a path that was not there). style prints a style: line instead of docsxai: cannot access.
  • docsxai-viewer says why a command stopped. build, burn, site and pack (also through docsxai burn, pack and render) print cannot access <path> (EACCES, permission denied) with a chmod next: line where they printed EACCES: permission denied, mkdir '<path>', and name a file that stands where a directory belongs. site stops with exit 1 on a workspace or docs/ that does not exist (it used to emit a ten-file site and exit 0). build over a missing or empty docs directory warns that the index is empty, and burn with no flow to burn ends with a next: line.
  • zip --out and export --flow failures. zip --out <directory> says the path is a directory and gives the --out <dir>/<name>.zip command, and --out through a file names the file and the mv; both used to print unexpected error: EISDIR or EEXIST and ask for a bug report. export adf --flow <missing> and export playwright --flow <missing> print the prefix once and point at docsxai flow-tree instead of lint.
  • A value flag with no value is a usage error. zip --out, export adf|playwright --flow|--out|--mode|--title, lint --flow|--format, flow-tree --format, style --format, calibrate --name, inspect --url|--wait|..., capture-auth --role|..., push --kind|--author, pull --rev, diagnose and init --app-url|... printed or wrote as if the flag was absent (zip ws --out wrote ws.zip, init ws --app-url made a workspace without a URL). Each now exits 2 with <command>: --<flag> needs a value and the command's usage line. init --auth and --capture-trigger show the value they got.
  • run --start-from and --stop-after with an unknown step. The message said startFrom: no step with id "x", an option name from the library. It now reads cannot start from step "x": flow "f" has no such step (steps: a, b), and the same for stop after.
  • calibrate --from on a flow-file with an error. A .yaml file with a schema error or broken YAML was reported as not a structured flow-guide (no parseable flow-file YAML found); it now prints the field path or the YAML error. calibrate --name "bad name" ended with next: fix <the --from file>; it now points at --name.
  • diff report without absolute paths. The text, Markdown and JSON reports print the baseline as typed (ws/.baseline, or the --against value), not /Users/.../ws/.baseline, so a report pasted into a pull request no longer carries a home directory. An annotations.json that fails the schema names the first fields, and not valid JSON no longer uses a dash.
  • A missing extends target. run, export adf, export playwright and diagnose print flow "kid" extends "ghost", but flows/ghost.flow.yaml does not exist and a next: line. export used to print ENOENT: no such file or directory, open '<abs path>', and diagnose said no flow named "ghost" about the flow you did not ask for.
  • Flow-file errors in lint, flow-tree, run and diagnose. lint and flow-tree named the file twice (parse error in <path>: f.flow.yaml: invalid flow-file:); they now print <path>: invalid flow-file: once. diagnose on a YAML error and on an unknown --step ends with a next: line and lists the steps. run --flow x with no match ends with next:.
  • plugins usage errors. An unknown or missing subcommand, a missing workspace or namespace and a bad --format print the message, the usage line and the --help pointer, where they printed the whole help text (or nothing for a bad --format). --format xml shows the value.
  • inspect on an app that does not answer. The warning drops Playwright's page.goto: prefix, call log and repeated URL, names the network code (net::ERR_CONNECTION_REFUSED) and what to change, and hides user:password in --url.
  • capture-auth with unusable credentials or descriptor. A missing credential env var and an invalid auth/strategy.yaml end with a next: line (export the variables, or the file to fix).
  • Notes run prints while a flow executes. A skipped optional step, a skipped obstacle scan and a skipped annotation capture start with run: (they started with runFlow:), keep the first line of the error and leave out Playwright's call log. A step that fails with a driver error that is not an Error halts with its text instead of undefined. The CDP note starts with docsxai:.
  • Error and warning text loses its em dashes. Flow-file, style, auth descriptor, plugin manifest, lock and plan, backend token and auth-cache, workspace, viewer launch, lint rule and halt-cause messages use a colon, a semicolon or a comma. The backend token hint now reads no bearer token: set DOCSX_TOKEN or run ....
  • docsxai-viewer burn with a damaged annotations.json. The error names the file (it printed the JSON parser's message alone), says expected an "annotations" list or annotations[0] has no "step" (it printed step "undefined") and ends with next: fix <file>. burn --flow zz names the flow and lists the ones that exist, where it printed burnFlow: no annotations.json under <dir>.
  • docsxai-viewer site. An invalid --accent exits 2 with the value and the usage line (it exited 1). An annotations.json the site cannot read is a site: warning: line, not silence. A failed --build prints the first lines of astro's report, without its stack trace or node_modules paths, and the command that prints the whole log.
  • docsxai-viewer bin and pack. --help, -h and help exit 0 (they exited 2). An unknown command prints its name on stderr before the help. pack usage errors print the message, the two usage lines and the --help pointer, not the whole pack help. pack <dir> says does not exist or is a file, and a raw capture step without step.json says what the file holds and what to do.
  • Backend wiki-push no longer lets a bearer token holder choose code, hosts or secrets. A stored config could name a directory for the backend to import(), key the webhook signature on any server variable through secret_env, and point a publisher's base_url at another host to receive its credential. Publisher directories, allowed hosts and the variables a publisher sees now come from the operator. The webhook answers 401, with one body, for a bad signature, an unparsable payload and an unknown repository, so it no longer says which repositories exist. OAuth refresh tokens expire after 30 days. What stops working and how to fix it is under Changed.
  • Starlight site keeps doc pack content as data. docsxai-viewer site and starlight:site wrote step prose into the MDX page as written, so an export, {expression} or JSX attribute in a <step>.md ran under Node when the site was built, and a " in a step id or flow name could add JSX attributes. Step prose now has {, } and < escaped outside code and a line-start import or export turned into text; ordinary markdown and code blocks build to the same HTML, and raw HTML or MDX components in step prose now show as literal text. Step ids and flow names with a bidi control character (U+202A to U+202E, U+2066 to U+2069, U+200E, U+200F, U+061C) are skipped with a warning that shows them as \u escapes. visual.logo in docs/style.json must name a file inside the workspace, symlinks followed; anything else prints a style.json visual.logo ... ignored warning and the site has no logo. The logo option may still be absolute.
  • Four file-handling fixes. pull refuses to write style.yaml, style.json or locators.yaml through a symlink that leaves the workspace (refusing to write docs/<name>: a symlink leads it outside the workspace). The session cache .auth/<role>.json is written as a new 0600 file and renamed over the old one, so an older 0644 copy never holds new cookies. Webhook run summaries say server file system error instead of carrying a server path. Re-emitting a site skips generated folders that are symlinks instead of deleting through them.
  • pull wrote style.yaml, style.json and locators.yaml through symlinks. A symlink in the workspace that pointed outside it got the backend's content written to its target. pull now refuses with refusing to write docs/<name>: a symlink leads it outside the workspace and writes nothing.
  • Session cache written owner-only from the first byte. Saving a role's session over an older .auth/<role>.json with mode 0644 wrote the new cookies into that file before the mode changed to 0600. The cache now writes a new 0600 file and renames it over the old one.
  • Webhook run history no longer shows server paths. When a revision could not be laid out in a temp workspace for a reason other than a refused payload, the run summary carried the raw file system error, temp directory included, to anyone with a project token. It now says server file system error. A refused payload still names the file.
  • docsxai-viewer site no longer prunes through symlinks. When src/content/docs/flows, src/assets or another folder on the way to the generated folders was a symlink, re-emitting a site deleted the files at the link target that the emit did not write. Those folders are now skipped.

Prerelease, tagged, never published; its changes ship in 0.3.0-rc.5. Over 0.3.0-rc.3 it adds themeable burned captions and moves the burned-caption renderer to satori 0.63.

  • Themeable burned captions (burn.theme) (#120). The burn.theme block of .docsxai.json sets the look of the halo, numbered badge, callout and arrow that docsxai burn and docsxai pack draw, and of the interactive viewer's overlay, which reads the same values through --sd-* CSS variables. Keys: accent, ink, callout_background, callout_border_color, callout_border_width, radius, shadow, badge_shape (circle, rounded, square), badge_fill, font_size, line_height, padding_x, padding_y and font (a TTF or OTF inside the workspace; the bundled Inter without it). preset selects clean, soft or high-contrast and any key overrides it; high-contrast is black on white at 21:1. from names a tokens file (W3C design tokens, or a nested or flat map) and tokens maps theme keys to token paths; a mapped token the file lacks stops the command with the key and the path. A bad block lists every problem with its key, and text pairs under WCAG AA print a warning. A workspace without a block burns the same bytes as before, and a viewer page without one differs only in the stylesheet reading each value through a var() with today's value as the fallback. A light connector colour gets a dark outline over light pixels, mirroring the white one over dark pixels. Guide: docs/burn-theming.md. Experimental. @docsxai/viewer exports loadBurnTheme, parseThemeConfig, resolveBurnTheme, themedBurner, themeStyle and the preset table.
  • Burned captions scale with the screenshot (burn.theme). New keys: scale (a number from 0.5 to 4, or auto), display_width (CSS px the page shows the screenshot at, default 720), font_weight (400 or 600, needs a font file with that weight), arrow_size (default 8) and max_width_ratio (default 0.62). scale multiplies text, padding, outline, radius, shadow, arrow, badge, halo and callout width; auto uses the screenshot width over display_width, between 1 and 4, so a 1440 px capture in a 720 px column gets factor 2. A fourth preset, readable, sets auto, 15 px text, 10 and 14 px padding, a 0.55 max_width_ratio and ink on near-white at WCAG AA. Every default equals the old value, so a workspace without the keys burns the same bytes. Bad values stop the command with the key and range. Guide: docs/burn-theming.md.
  • Copy buttons for ids in the viewer and the Starlight site. Flow and variant ids, step ids, the viewer build and the capture command copy on click, Enter or Space. The label changes to "Copied" for 1.5 s without moving the page and a polite live region announces it; where the clipboard is unavailable the text is selected and the button reads "Press Ctrl+C". ? opens the keyboard shortcut list.
  • Clearer image and empty states. A step with no screenshot shows the missing path and the command that captures it. A failed image has a Retry button with "Retrying..." and "still failing" states. A failed index thumbnail becomes a placeholder. Annotation and step-name messages now say what to do next.
  • docsxai doctor checks the config, write access, app_url and backend login. New lines: config (field types, URL shape and the burn.theme shape and preset name; the viewer's value and contrast checks stay in docsxai burn, because the engine does not depend on the viewer), writable (workspace root and its output dirs), app_url (one HEAD with a 3 s timeout; a remote host that does not resolve prints a skipped line, --offline skips it, a refused connection or timeout fails) and login (fails when backend_url is set and neither DOCSX_TOKEN nor stored OAuth tokens exist).
  • Sample flow in the init scaffold. flows/example.flow.yaml.sample parses as a flow-file and is ignored until docsxai calibrate . --from flows/example.flow.yaml.sample writes it. The scaffolded README.md gains an optional burn.theme section and the docsxai doctor step.
  • burnWithWorkspaceTheme in @docsxai/viewer. Burns a screenshot with the burn.theme of a workspace's .docsxai.json, loaded once per workspace and cached by path and config mtime. It returns what burnAnnotations returns, lets an explicit options.theme win, sends theme warnings to options.warn once per load and throws BurnThemeError for an invalid block. Guide: docs/burn-theming.md.
  • First-run help. docsxai with no argument prints three first steps (init, calibrate, run) and the commands grouped by purpose, each with a one-line description. docsxai --help starts with the same block, then prints the full usage text. docsxai help <command> and docsxai <command> --help print that command's usage and one example. A mistyped command exits 2 with did you mean \docsxai run`?when a command is within two edits, plus thedocsxai --help` pointer.
  • Annotation placement guide. docs/annotation-placement.md, published as Guides, Placing burned annotations: the annotation record keys, how arrow_style and placement.side hint a side, obstacles, the badge, scale and display_width, per-image theme overrides through options.theme, and a troubleshooting table.
  • Screens pack manifest reference. docs/pack-manifest.md, published as Reference, Screens pack manifest: the docsxai/screens-pack@2 fields and limits, the pack.json keys, and the version policy.
  • JSON Schema for the screens pack and pack.json. @docsxai/viewer ships schemas/screens-pack-2.schema.json (manifest.json) and schemas/pack-config-1.schema.json (pack.json), draft 2020-12, importable as @docsxai/viewer/schemas/<file>. Patterns and limits are copied from validatePack and parsePackConfig, and a test checks each schema against the validator on the same good and bad documents. docs/pack-manifest.md lists the rules a schema cannot say.
  • Accent contrast warning for the Starlight site. docsxai-viewer site checks the accent against Starlight's light (#ffffff) and dark (#17181c) backgrounds and prints a site: warning: line with the ratio when link text is under 4.5:1 or the focus ring and buttons are under 3:1. It never fails the command and the emitted colours stay as configured.
  • burn.theme.display_width takes a wide and a narrow width. Besides a number it now accepts { "default": 720, "narrow": 358, "narrow_below": 900 }: a screenshot narrower than narrow_below px (default 900) uses narrow for scale: "auto", any other uses default. A 780 px phone capture shown at 358 px gets factor 2.18 while a 1440 px capture shown at 720 px keeps 2, in one workspace. Bad shapes stop the command with the key path (display_width.narrow). A number behaves as before and default output is unchanged. The resolved BurnTheme gains displayWidthNarrow and narrowBelow (null for the number form), and @docsxai/viewer exports displayWidthFor and NARROW_BELOW_DEFAULT. Guide: docs/burn-theming.md.
  • Spanish text for the pages docsxai emits (@docsxai/viewer). The labels, empty and error states, notices, keyboard shortcut list, aria-label names and aria-live announcements that the interactive viewer and the Starlight site add now come from one en and es table (ui-strings.ts). A locale tag picks the language by its primary subtag: es, es-ES and es_MX give Spanish, any other tag gives English, and the page gets a matching lang. A matrix variant flow (<flow>/<locale>.<scheme>.<viewport>) takes the locale of its variant id; docsxai-viewer build --lang <locale> sets the rest, and docsxai-viewer site --lang <locale> (also buildViewer({ lang }), config.lang and the lang key of the starlight:site renderer) sets the site language, including Starlight's own labels. The Retry button reserves the longer of its two labels in each language. English output is unchanged. Guide: packages/viewer/README.md, Page language.
  • caption_style defaults to auto at every width. A themed burn used full for captures 900 px and wider; now a caption with no clear spot (clear of text, header, nav, other captions and badges) falls back to its numbered badge, on desktop too. Desktop captures with no clear spot now show their badge only; set caption_style: full to keep the old behaviour. An explicit full or badge still wins, and a burn with no theme is unchanged. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs no longer pick the style by width.
  • Satori 0.63 renderer. The renderer that draws burned captions and the other rendered images moves to satori 0.63.
  • release.yml retired (#115). The GitHub Actions release workflow is removed.
  • Dependency refresh. Dependencies are updated across the workspace.
  • First-run messages. docsxai init ends with a next: line that names calibrate --from <flow.yaml> and leaves out capture-auth for an --auth none workspace. capture-auth in a workspace with no auth descriptor says to skip it when the app needs no login. The README gains a "First run in 10 minutes" walkthrough, and the install steps name @next (0.3.0-rc.3), the Chromium download and docsxai doctor.
  • Zod 4. @docsxai/engine and @docsxai/mcp move to zod ^4.6.6. Schemas and the options they accept are unchanged. Where a flow-file, auth descriptor, plugin manifest or style file breaks a built-in rule (a wrong type, an unknown key), the message after the key path now uses Zod 4's wording. Messages written in the schemas themselves are unchanged.
  • docsxai run prints a starting line. Each flow prints run: <flow>, starting before its browser launches, so a log shows which flow is in flight. Ctrl-C (or SIGTERM) stops any command with one docsxai: interrupted line and the command to rerun, and exits 130 (143 for SIGTERM).
  • Viewer layout. Headings sit in an id row with their copy button, the footer carries the viewer build as copyable text, and each index card has a copy button under it. The skip link is 44 px tall.
  • docsxai doctor prints ok: and fail: lines. Every line starts with ok: or fail: and carries a next: step where there is one; the ✓, ✗ and − glyphs and the header are gone, and the last line is ok: doctor: ... or fail: doctor: .... Exit 1 on any fail: line, as before.
  • The scaffolded README.md follows the auth choice. An --auth none workspace no longer lists capture-auth or auth/strategy.yaml, and the default one points at --auth none for an app without a login.
  • readable caption preset and scale: auto. The auto factor is capped at 4 (was 3), so a 1440 px screenshot shown at 360 px keeps about 15 px captions, it rounds up to two decimals, and readable limits the callout to 55 percent of the image width. Burned output without a theme and with the other presets is unchanged.
  • Plugin and vendored skill review. /docsxai:doctor frontmatter is valid YAML (quoted description and argument-hint), the commands point at docsxai doctor and diagnose on failure, run documents its starting and interrupted lines, calibrate gains a setup order and a burned-captions section (burn.theme readable preset and display_width), and the plugin README is the one place that names the install command.
  • Usage lines wrap under 100 columns. The Usage: block of docsxai --help breaks long entries onto indented continuation lines. Commands, flags and their order are unchanged. The Examples: block gains one line for each command that had none.
  • Border-box fix for satori 0.63 (#119). Rendered boxes keep their size under the new renderer.
  • Halts for an unreachable app. A flow that cannot reach the app (refused connection, unknown host, rejected TLS certificate) or a relative navigate with no app_url now halts with a bracketed cause that names app_url, --base-url or --ignore-https-errors. The scaffolded workspace README.md no longer shows a calibrate --description flag that does not exist.
  • Flow-file errors name the field. A wrong type or an unknown key inside success, wait_for or redactions printed a bare Invalid input; it now prints the path of the bad field and the zod message of the closest match.
  • Missing flows/, token and config errors end with a command. run, lint and flow-tree on a directory without flows/ end with next: docsxai init <dir>. push and pull without a usable token end with the docsxai login ... --oauth <dir> command. run and capture-auth warn when .docsxai.json exists but was ignored (invalid JSON or the wrong schema), and run warns when a flow navigates to a relative path with no app_url.
  • Read-only or full disks. A write refused with EACCES, EPERM, EROFS or ENOSPC prints cannot access <path> (<code>, <reason>) and a next: line in init, zip, baseline, export, run and the bin's last-resort handler, with no report-a-bug line.
  • Docs match the code. Fixed the reserved plugin namespaces, the backend auth gate (any bearer without DOCSX_TOKEN, the webhook exemption), the optional BrowserDriver methods, the lint rule range, the plugin status list, the burn.theme preset count, the session-expiry message and the plugin-sharepoint publish note.
  • Burned callout, arrow and badge placement on dense screens. A stem or arrow that ran through text or a neighbouring halo is now charged per px crossed, so a callout sits near its target and covers a few px of text before a long stem crosses six rows. An arrow_style or placement.side hint now wins over a side that is only a sliver cleaner, where a few px of overlap used to throw it away. A numbered badge no longer crosses the bottom or right edge of the screenshot: it stays inside with a 2 px margin. A callout that overran a narrow gap by a few px retries with its side padding cut by up to 6 px (never below 8 px) and keeps that box when it fits clear. Annotations without obstacles and hint burn the same bytes as before. Guide: docs/burn-theming.md.
  • CI examples. The GitHub Actions nightly recipe now runs its tee steps under shell: bash, so a failing docsxai run or docsxai diff fails the job (the default shell has no pipefail). The weekly GitHub and GitLab refresh recipes in docs/ci-recipes.md install docsxai@next with npm: they used pnpm/action-setup without a pnpm version and corepack, which Node 26 images do not ship. Added examples/burn-theme/ and a README for examples/ci/sample-repo/.
  • Docs site: a print stylesheet that drops the site chrome, and readable dark text on the landing-page mock buttons.
  • Emitted output accessibility. Viewer print keeps a step heading row with its figure, and long ids and code in write-ups and placeholders wrap at 390 px. The Starlight copy and Retry focus ring uses the theme text colour (17:1 or more on both themes) in place of the accent, which a custom accent could push under 3:1, and the step image alt reads "Screenshot of step ".
  • docsxai doctor URL lines show host and path. The login next-step command, the backend line and the app_url line now print backend_url and app_url as host and path only, like the other doctor lines.
  • Docs site at 390 px. The install commands on the landing page have copy buttons that change to "Copied", announce the result and copy no prompt, and the $ transcripts in the CLI and plugins references now copy as commands without prompts or output. The menu, search, theme and copy buttons are 44 px, tables and cards use 16 px text, paragraphs stop at 75 characters, the 404 page links to Installation, and the Quickstart ends with a link to the flow-file format. check-a11y-surface checks the copy buttons, table wrappers, step numbers and next links in the build.
  • --stop-after on an optional step. When the step named by --stop-after was optional: true and failed, it was skipped and the run went on to the end of the flow; the run now stops there.
  • Browser left running after a failed launch step. When Chromium started but creating the context or page failed (a bad environment value, a rejected storageState), the browser process was never closed, so the command hung until it was killed. The browser is now closed before the error is reported.
  • Flags without a value were ignored. docsxai run <ws> --flow (or --variant, --stop-after, --start-from, --cdp, --base-url, --concurrency) ran every flow as if the flag was absent, and diff --against, diff --format and baseline --out fell back to their defaults. Each now exits 2 with --<flag> needs a value.
  • --flag=value was ignored. docsxai run <ws> --flow=tour read flow=tour as an unknown boolean flag and ran every flow. Every command now reads --flag=value the same as --flag value.
  • A bare -- took the next argument as its value. docsxai run -- <ws> reported a missing workspace directory. A bare -- now ends flag parsing and the rest are positional arguments.
  • baseline --out <workspace> deleted the workspace's flows/ and docs/. A refresh clears <out>/flows and <out>/docs before copying, so an --out equal to the workspace removed the sources it was about to snapshot. The command now exits 2 and touches nothing.
  • push payload order followed the disk. The flows, annotations and screenshots entries of a pushed doc pack were added in the order the file system listed them, which differs between machines. They are now sorted, so the same workspace produces the same payload everywhere.
  • style --check listed jargon hits in disk order. The hits were reported flow by flow and file by file in the order the file system listed them, so the output differed between machines. They are now in name order.
  • diff named no file for an unreadable screenshot. A screenshot that was cut short or not a PNG (an interrupted run, a failed copy) made diff print the PNG decoder's own message, such as Invalid file signature, with no hint of which file. The error now starts with docs/<flow>/screenshots/<file>.
  • docsxai-backend starts through an installed symlink. The bin compared process.argv[1] with the module URL, which differ when npm or pnpm links the bin, so the command exited without starting a server. It now compares the real path too.
  • docsxai-backend flag parsing. --port= (empty) picked a random port, --port=70000 crashed with a stack trace, --port 4000 and --data-dir <dir> were ignored, and a mistyped flag such as --data-dri= started an in-memory server. The bin now reads both --flag=value and --flag value, and exits 2 with a usage line for a missing value, a port outside 0-65535 or an unknown argument.
  • docsxai-backend startup errors. A port already in use, a port the user may not bind, and a --data-dir that is a file ended in an unhandled rejection with a stack trace. The bin now prints one line naming the port or the data dir and exits 1.
  • Backend: a malformed percent-encoding in a path answers 400. GET /v1/workspaces/%E0%A4%A threw out of the route matcher and returned 500 internal; it now returns 400 bad_request.
  • Backend: a 405 carries Allow. A method the route does not serve (a DELETE on /v1/workspaces, any OPTIONS) now answers with the methods the path does serve in an Allow header, as HTTP requires.
  • Backend: an over-limit chunked upload answers 413. A body sent without Content-Length that grew past the 10 MB or 25 MB limit destroyed the connection, so the client saw a reset instead of the 413 payload_too_large body. The server now answers 413 and drops the rest of the upload.
  • Backend: 400 only for a bad request. A missing name came back as invalid JSON body: body requires a non-empty { name }, and a damaged file in the data dir came back as a 400 with the same prefix. The first now reports the missing field alone, and the second answers 500 with the file name.
  • Backend: a webhook body of null answers 400. POST /v1/github/webhook with the JSON body null threw and returned 500; it now returns 400 payload missing repository.full_name, like any other payload without a repository.
  • Backend: run-history bodies are type-checked. POST .../run-history stored "ok": "false" as true and a text duration_ms as null. It now returns 400 bad_request naming the field unless ok is a boolean, duration_ms is a non-negative number (default 0) and summary is a string (default empty).
  • Backend: run history is capped at 1000 records per project. runs.json and the in-memory list grew with every run, and each append rewrote the whole file. Appending past 1000 now drops the oldest record.
  • Backend: a webhook run's summary is the engine's last line. The runner kept the first 64 KiB of engine output and read the last line of that, so a run that printed more than 64 KiB recorded a line from the middle. It now keeps the last 64 KiB.
  • Backend: a webhook run removes its temp workspace when run history cannot be written. If recording the run threw, the materialized workspace (flows, screenshots, rendered output) stayed in the temp dir.
  • Backend: an over-limit chunked upload answers 413. A body sent without Content-Length that grew past the 10 MB or 25 MB limit destroyed the connection, so the client saw a connection reset and no 413 payload_too_large body. The server now answers 413 and drops the rest of the upload.
  • Doc pack, annotation, style and export writes are atomic. run, pull, style, run --verify-determinism and export adf write to a temp file in the same directory and rename it over the target, so an interrupted write leaves the previous file instead of a truncated annotations.json. An existing file keeps its mode, and where the rename is refused (Windows) the write falls back to a plain overwrite.
  • docsxai baseline keeps the previous snapshot when a refresh fails. The new snapshot is built in a staging directory inside the output directory and swapped in after every file is copied, so a full disk or a read error no longer leaves .baseline/ without flows/ and docs/.
  • render, burn and pack forward SIGTERM and SIGINT to the viewer. The command passes the signal to the viewer child and waits for it, then exits with the child's exit code, or 128 plus the signal number when the signal ended it. Before, the command exited at once and the child kept running and writing.
  • run --pause and inspect --headed no longer hang when the browser is already closed. The wait resolves at once for a browser that disconnected during the last step, and the session is closed and the command exits.
  • run --stop-after with an unknown step id fails before any step runs. It named no step and so ran the whole flow and overwrote its annotations; it now fails with stopAfter: no step with id ..., as --start-from already did.
  • An unresolved locator ref halts as a step failure. With a custom resolveLocator, a target or redaction $ref that resolved to nothing threw a plain error with no step id and no halt screenshot. It now halts as a FlowExecutionError that names the step. When a redaction cannot be resolved, no halt screenshot is taken, since it would go out unmasked.
  • run --start-from warns when it cannot merge into the existing annotations.json. A file that was unreadable, invalid JSON or not an annotations file was replaced by the fresh annotations without a word, dropping the earlier steps. The run now prints a warning: line naming the file.
  • run --concurrency rejects a value that is not a whole number of 1 or more. abc, 0, -2 and 1.5 fell back to 1 without a message. They now exit 2 with --concurrency must be a whole number of 1 or more.
  • zip keeps the outputs of a flow named halts. Every path segment named halts was excluded, so docs/halts/ vanished from the archive. Only halts/ directories below docs/<flow>/ are left out now.
  • diff screenshot severity compares the exact changed ratio. The warn and fail thresholds were compared with pct after it was rounded to 4 decimals, so 0.99996% counted as 1% and tripped a screenshot_pct_warn of 1. The reported pct is unchanged.
  • push names the file when docs/style.json is not valid JSON. It failed with a bare SyntaxError that carried no file name. The message is now <path>/docs/style.json: invalid JSON, ....
  • Halt screenshot and jargon-hit paths use / on Windows. diagnose and style --check printed workspace-relative paths with backslashes there; they now match the POSIX form the other reports use.
  • docsxai and docsxai-viewer start through an installed bin symlink. The entry check compared import.meta.url with the path the shell used, so a bin that npm links into PATH exited 0 without running. It now also compares the real path, as docsxai-backend does.
  • HEAD /v1/health answers 200 (@docsxai/backend). It was a 405, which failed load balancer probes that use HEAD. Other GET routes still answer HEAD with 405.
  • A revision with a non-string author is rejected (@docsxai/backend). POST .../revisions stored an object as [object Object]; it now answers 400 author must be a string. A missing author still defaults to unknown.
  • FsStore removes its temp file when a write fails (@docsxai/backend). A failed write or rename left <file>.tmp-<id> in the data dir.
  • FsStore no longer reads an unreadable data file as empty (@docsxai/backend). Any read error, such as a permission error, counted as a missing file, so the next createWorkspace could overwrite workspaces.json with a single entry. Only a missing file reads as empty now; other errors answer 500.

Prerelease, published under the next dist-tag. 0.2.0 stays latest. Over 0.3.0-rc.2 it fixes the @docsxai/plugin and @docsxai/skill tarballs (rc.1 and rc.2 shipped without their commands, skills and skill folder), adds thin themed scrollbars on the docs site, the viewer and emitted Starlight sites, static accessibility checks, the DOCSX_DEBUG error path, and the plugin, MCP and docs-accuracy passes.

  • @docsxai/plugin-sharepoint is published. It is published, from this release, as an experimental package, the seventh in the release set. It takes the shared release version and drops "private": true. Graph behaviour has only been tested against a fake server; no live tenant has run.

  • DOCSX_DEBUG for errors no command handled. The docsxai bin (engine and meta-package) now prints docsxai: unexpected error: <first line> and a next: line instead of a Node stack, and exits 1. With DOCSX_DEBUG=1 (or true, yes) it prints the stack too. URLs in either are printed without user:password or query. doctor knows the variable. The engine CLI entry exports runAsBin.

  • Static accessibility checks in CI. pnpm test lints rendered viewer pages and the docs-site build lints four built pages (home, 404, a docs page, a table page) for lang, one h1, heading order, alt, form labels, landmarks, the skip link target, tabindex, empty links and buttons, aria-* names and roles, labelled scroll regions, prefers-reduced-motion and hidden scrollbars, with no browser.

  • Screenshot scripts for the docs site and the viewer. scripts/visual-capture.mjs renders the docs site and a sample viewer pack in Chromium at 390 and 1280 px in light and dark, plus the 404 page, search, a wide-table page, the mobile menu and the viewer's empty, error and focused-step states, and writes PNGs and a markdown summary. It compares nothing and gates nothing. No CI pipeline runs it.

  • Starlight site emitter: thin, themed scrollbars. Emitted docs sites now write src/styles/scrollbars.css (always, wired into customCss ahead of theme.css) and set expressiveCode: { useThemedScrollbars: false }. Every scroller gets a thin bar whose thumb is --sl-color-white at 50% (70% on hover), at least 3.2:1 against the page, sidebar and nav surfaces of both Starlight themes, with a 12px webkit fallback where scrollbar-color is missing and the system bar under forced colors or prefers-contrast: more. The tokens --scrollbar-track, --scrollbar-thumb and --scrollbar-thumb-hover override it. No scrollbar is hidden. Regenerating a site adds the file and the two config lines; the emitted tree is otherwise unchanged.

  • caption_style defaults to auto at every width. A themed burn used full for captures 900 px and wider; now a caption with no clear spot (clear of text, header, nav, other captions and badges) falls back to its numbered badge, on desktop too. Desktop captures with no clear spot now show their badge only; set caption_style: full to keep the old behaviour. An explicit full or badge still wins, and a burn with no theme is unchanged. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs no longer pick the style by width.

  • Staged npm releases (#113). Each package version is staged on npm, and a maintainer approves it before it goes live.

  • More CI checks. CI gains format-check, audit (pnpm audit:prod, licenses, lockfile lint), package-contents and secret-scan steps. The ci, quality, visual-captures and dependabot-auto-merge GitHub Actions workflows are removed; Actions runs release.yml only. Dependabot pull requests no longer auto-merge.

  • Releases move off GitHub Actions. The project's CI tests, builds and stages each release on npm, and a maintainer approves each staged version with 2FA. These releases carry no npm provenance attestation. The GitHub Release is created by hand.

  • CLI usage lines. --format values are listed default first everywhere: run --verify-determinism and diff now read [--format text|md|json]. init reads [--role <role>] like inspect and capture-auth, and so does the capture-auth hint for an unknown role. Only the help text changed; every flag and value is accepted as before.

  • Scrollbars on the docs site and in the interactive viewer. Every scroller gets a thin scrollbar from three tokens (--scrollbar-track, --scrollbar-thumb, --scrollbar-thumb-hover): the thumb is the theme's text colour at 50%, 70% on hover, at least 3:1 against the page in light and dark; browsers without scrollbar-color get a 12 px webkit bar, forced colours and prefers-contrast: more keep the system scrollbar, and no scrollbar is hidden (the docs site's on-this-page list showed none).

  • Publishing outside GitHub Actions no longer fails on provenance. Every published package.json has publishConfig.provenance: true, which makes npm refuse to publish from any runner other than GitHub Actions or GitLab CI. The release script now turns provenance off elsewhere, so a release from the project's CI does not fail on the first package.
  • Backend errors redact quoted URLs. A failed token refresh and the login, push and pull error lines printed the message they got as is, so a URL in it kept its user:password and query. Every URL in those messages now goes through the same redaction as the backend URL.
  • @docsxai/plugin and @docsxai/skill tarballs. 0.3.0-rc.1 and 0.3.0-rc.2 of both packages were published without the plugin tree (.claude-plugin/, commands/, skills/) and without the skill bundle (skill/), because files listed only dist; vendorSkill() from the npm package had nothing to copy. files now lists them, and scripts/audit-package-contents.mjs fails when a tarball lacks its main, its bin targets or those trees.
  • Claude Code plugin and vendored skill. Commands pass $ARGUMENTS as single-quoted words and say <workspace-dir>; run, export, push and the skills cover variants, --verify-determinism, export playwright, burn and pack; skill names are calibrate and diagnose; the vendored skill triggers only on a docsxai workspace; a test checks every documented docsxai example against --help.
  • MCP server: tool descriptions, bounds and error hints (experimental, private package). Each tool description now says when to use it, what it returns and how it fails, every argument is described, the server sends usage instructions, string arguments that name a workspace, flow, step, revision, output path, CDP endpoint, base URL or author reject "" (it meant "every flow" or the working directory), run_flows checks startFrom and stopAfter against the flow's steps and adds a hint per failed flow and at the top level, a matrix flow is reported as failed with the CLI command instead of running without its matrix, backend failures give a hint per cause, and over HTTP a path outside the workspace root in an error is replaced with <path>. Tool and argument names are unchanged.
  • MCP server: matrix flows (experimental, private package). run_flows reports a flow with a matrix: as failed (ok: false, with the CLI command to use: docsxai run <workspace-dir> --flow <flow>, --variant <id> for one variant) where it used to run it once without its matrix, and diagnose_halt refuses such a flow with the docsxai diagnose ... --variant command. The other flows in the call still run.
  • MCP server: tool descriptions, bounds and error hints (experimental, private package). Each tool description now says when to use it, what it returns and how it fails, every argument is described, the server sends usage instructions, string arguments that name a workspace, flow, step, revision, output path, CDP endpoint, base URL or author reject "" (it meant "every flow" or the working directory), run_flows checks startFrom and stopAfter against the flow's steps and adds a hint per failed flow and at the top level, a matrix flow is reported as failed with the CLI command instead of running without its matrix, backend failures give a hint per cause, and over HTTP every absolute path outside the workspace root (POSIX, file://, drive-letter, UNC) in a result is replaced with <path>, JSON parse errors quote no file content and backend errors are fixed sentences. Tool and argument names are unchanged.
  • Docs match the 0.3.0-rc.2 surface. The pack docs cover matrix sources (sources with matrix, matrixFlow), drift is named pack --check everywhere, and the CLI reference, runbooks and package pages now state the doctor env checks and --help, the pull name rules, that baseline and diff do not read matrix variant directories, the MCP HTTP transport, the egress guard variables, the @next installs, and that the MCP server and every @docsxai/plugin-* package are repo-only; 40 mismatches in all. packages/engine/test/docs-cli-mentions.test.ts fails when the README or a site page shows a docsxai command or flag that docsxai --help does not list.
  • GitBook publisher: markdown escaping and log lines. A code span whose content starts or ends with a backtick rendered with unbalanced fences, and a newline in a code span, heading or list item ended its line. Code spans are now padded and flattened to one line, headings and list items stay on one line, heading levels clamp to 1..6 (level 0 was 2), a ! before a link is escaped, and link targets are percent-encoded ((, ), whitespace, brackets, quotes) where a target with a parenthesis used to lose its link. Alt text is escaped on one line, a page title and title_prefix are cut to one line, two screenshots of one page that fold to the same file name are refused before any write, and section names in logs and errors are quoted on one line. Pages with those characters render differently, so the first push after the upgrade rewrites them.
  • Guru publisher: heading level 0, name collisions and log lines. A heading of level 0 rendered as <h2> where <h1> was meant; levels now clamp to 1..6. Two sections that fold to one manifest key (a b and a-b) shared a card, a section titled like the manifest card was taken for it on the next push, and two different screenshots with one safe name shared an upload. Each is refused before any request, as is an image name that is all dots. Card titles and title_prefix are cut to one line, and section names in logs and errors are quoted on one line.

Prerelease, published under the next dist-tag. 0.2.0 stays latest. Over 0.3.0-rc.1 it adds matrix-aware docsxai pack, a hardened pack.json reader, the burned badge fill #c2410c (burned PNGs that carry a numbered badge change once, so re-record pack baselines once), and viewer, CLI and docs-site UX fixes.

  • caption_style defaults to auto at every width. A themed burn used full for captures 900 px and wider; now a caption with no clear spot (clear of text, header, nav, other captions and badges) falls back to its numbered badge, on desktop too. Desktop captures with no clear spot now show their badge only; set caption_style: full to keep the old behaviour. An explicit full or badge still wins, and a burn with no theme is unchanged. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs no longer pick the style by width.

  • Interactive viewer: keyboard, screen reader, contrast, motion and error states. Pages from docsxai render get landmarks, a skip link and an in-order outline; arrow keys, j/k, Home/End, [/] and Esc move between steps and flows and hide callouts, with step changes announced; call-outs open on focus or tap; text meets WCAG AA in new light and dark schemes; the halo pulse stops under prefers-reduced-motion; image boxes are reserved; a broken annotations.json, a missing screenshot, an empty flow and a failed image load (with Retry) each show a message; phones get a viewport meta, 44 px touch targets and overlays redrawn on resize; print gets its own styles. The viewer badge fill is now #c2410c.

  • Burned screenshots: numbered badge fill is #c2410c. White 12 px bold numerals on the old #e8590c measured 3.58:1; on #c2410c they measure 5.18:1, and the burned badge now matches the viewer badge. Only the badge fill changes. The halo outline, connectors and arrowheads keep #e8590c. Burned PNGs that carry a numbered badge change once, so committed packs regenerate once (docsxai burn / docsxai pack) and pack baselines need re-recording.

  • CLI output and viewer paths. A backend URL is printed without its query string and fragment (a token in --backend-url https://h/?token=... reached the cannot reach, login: ok, push: and next: lines), and a string that is not a URL prints as <invalid url>. Text the backend controls (response body, revision author, kind and id, error messages) is stripped of C0 and C1 control characters, DEL and ESC sequences before it is printed, and values in suggested next: commands (workspace dir, flow, step, variant, URL) are single-quoted when they are not plain words. docsxai render skips a step id or flow name that holds /, \, .., : or a control character (a ../../x id read and copied files outside the pack, a flow named javascript:... became a link target) with a warning on stderr and an error state on the step, and index links start with ./.
  • Guru publisher: card read without collection. A page card whose read carried no collection failed the target-collection check as intended and was recreated on every push with a warning per section that blamed the wrong cause. The check is unchanged and still fails closed; the plugin now logs one masked warning per push that says Guru returned the card without a collection and that new cards are created until it does, and the README says the same. The manifest card still fails the push in that case.
  • Request guard: lookup deadline. requestProblem gave a hostname lookup no time limit, so a stalled resolver left the request pending. A lookup now has 5 seconds (lookupTimeoutMs on the guard options) and a request whose lookup times out is refused like any other failed lookup. SECURITY.md also says that on a CDP-attached context the guard cannot block service workers.
  • MCP token file on Windows. serve --http prints one stderr warning when it reads a --token-file on Windows, where the permission check cannot run. The README and SECURITY.md now say --token-file is the preferred source, because the initial environment block stays readable to other processes of the same user even after the variable is cleared.
  • upload paths: hidden and reserved files refused. The upload confinement allowed .auth/<role>.json (a captured storage state), .docsxai.json and webhook-job.json, which are inside the workspace. A value with any segment that starts with a dot, or that names webhook-job.json (any case), is now refused by the driver and when the backend materialises a revision, and the driver applies the same rule to the real path of a symlink's target. The two copies of the rule stay in step through the parity test.
  • MCP HTTP transport: cdp and baseUrl confined. run_flows and diagnose_halt passed cdp straight to connectOverCDP, and run_flows took any baseUrl, so an HTTP client could attach to a browser on the server's host or point a run at a metadata address. With serve --http, cdp is refused, baseUrl (and a workspace app_url) must be an http(s) URL whose host passes the engine's address rules, resolved the way the request guard resolves it, and every browser a tool starts gets the request guard (DOCSX_EGRESS_GUARD=0 switches it off; DOCSX_EGRESS_DENY_PRIVATE adds the private ranges). stdio is unchanged. @docsxai/engine now exports the egress-guard module (requestProblem, envFlagOn, envFlagOff and the rest).
  • Pack workspace reader: reserved names, symlinked directories, caps, error text. A pack.json sources key of __proto__ set the prototype and the entry vanished, and a flow or step named constructor made flows[...] lookups throw a raw TypeError; __proto__, constructor and prototype source names are now refused and flows and steps are read by own keys only. readRegularFile checks only the last path component, so a symlinked screenshots/ directory was followed; the flow, variant and screenshots/ directories are now refused when they are symlinks (flat sources too), and a symlinked variant directory under a matrix flow is skipped with a warning that names it. A flow directory with more than 256 variant directories is refused, variant ids are looked up in a Set, a flat source and a matrixFlow whose names differ only by case are refused, and error messages print workspace-relative paths with control characters stripped from directory names. Valid input packs to the same bytes.
  • CI recipes and install snippets: docsxai@next. The nightly drift recipes under examples/ci/, docs/ci-recipes.md, the README files and the website install page ran a bare npm install -g docsxai, which resolves to 0.2.0 (latest) and has no pack, --verify-determinism or matrix flows, so the recipes failed on their first docsxai command; 0.3.x is only on the next dist-tag. The install lines now say docsxai@next with a one-line note that the pin should move to the stable version when latest does, and a test checks that every recipe's install line carries a version or dist-tag.
  • Notion publisher: interrupted manifest write, duplicate ids, page identity. A push that died between clearing (or creating) the manifest page and appending its JSON left an empty page, and every later push failed with "not a docsxai manifest". An empty or whitespace-only manifest page is now treated as that interrupted write: one masked warning, every page written again (a page that already existed can get a second copy), manifest rewritten. A page with other content that is not a manifest still refuses. Manifest entries that name one page id keep the first, sections whose keys collide case-insensitively and sections or titles named like the manifest page are refused before any request, and the screenshot read cap drops from 64 MiB to 21 MiB (the 20 MiB upload limit plus 1 MiB).
  • GitBook publisher: merge conflicts, caps, 429, escaping. A merge that answered conflicts returned ok: true while the manifest in the same change request already held the new hashes, so the next push said unchanged. The push now returns ok: false with a masked message and resets those hashes in a second change request (config.force is the fallback when that fails too). Screenshots are capped at 4 MiB per page batch (the rest are captioned and named in warnings), page markdown at 1 MiB (refused with an error), and the screenshot read at 4 MiB instead of 64 MiB. A 429 is retried after Retry-After (at most 5 times, each wait at most 30 s), a change request whose id cannot be used is archived, manifest entries that share a page id and sections that collide on a slug are refused like in the Notion plugin, and text now escapes block-start characters (#, -, +, =, 1., 1)) at the head of each line.
  • Confluence publisher: attachment upload. A live run against Confluence Cloud created the page, then POST /wiki/api/v2/pages/{id}/attachments answered 405 METHOD_NOT_ALLOWED, because v2 only reads attachments. Uploads now go to POST /wiki/rest/api/content/{pageId}/child/attachment (multipart file, comment, minorEdit, header X-Atlassian-Token: no-check), a changed screenshot is posted to .../child/attachment/{id}/data, and the media file id comes from extensions.fileId in the response. A publish that fails after creating a page now throws a ConfluencePublishError carrying partial.pages (and logs a page_map fragment), so a retry updates that page instead of creating a duplicate. The fake Confluence server in the tests models the 405 and the v1 response shape.
  • SharePoint publisher: manifest read, timeouts, name collisions, markdown escaping. Graph answers GET .../root:/<path>:/content with a redirect to a pre-authenticated download URL, and the client refused every redirect, so the manifest read of a second push would fail on a real tenant (no live run has confirmed either side). A read now follows exactly one hop, only to https on a *.sharepoint.com (or .us, .cn, .de) host with no credentials and the default port, without the Authorization header; a second redirect or any other Location fails, and writes still refuse redirects. The manifest declares egress:*.sharepoint.com next to egress:graph.microsoft.com, so workspaces list both. Every call has a deadline that covers the response body (30 s API, 120 s upload), error bodies are masked before they are cut to 500 characters, and a failed manifest write after an earlier error logs itself and leaves the first error as the one reported. Sections that land on one path (a b and a-b, case-only differences, a flow named index) and different screenshots with one image name fail before any request, naming both. Code spans and fences use a backtick run longer than any inside, links are kept only for http, https and mailto with (, ), whitespace and brackets percent-encoded, titles, title_prefix and alt text lose newlines and control characters and are escaped, and heading levels are clamped to 1 to 6. graph_base_url is returned as the parsed origin and path, refuses a query or fragment, and accepts only /v1.0 or /beta. The README no longer claims a 250 MB simple upload or parent folder creation as verified.
  • SharePoint publisher: capabilities cover every reachable host. The code accepted graph.microsoft.us, microsoftgraph.chinacloudapi.cn, graph.microsoft.de and the sharepoint.us, .cn and .de download domains, but the manifest declared only egress:graph.microsoft.com and egress:*.sharepoint.com. It now declares all eight, so a workspace's plugin_capabilities has to list all eight to load the plugin. README, AGENTS.md and docs/public-surface.md are updated.
  • SharePoint publisher: ! before a link. A text node ending in ! followed by a link-marked node rendered as ![t](https://github.com/kalebteccom/docsxai/blob/main/url), which markdown viewers load as a remote image. The ! is now escaped when a link follows it.
  • SharePoint publisher: image link and upload share one name; names checked first. A page linked an image by safeName(alt) while the upload used safeName(fileName), and an alt of .. threw only after earlier files were written. The link now takes the path of the screenshot with the same file name, a media node with no such screenshot is refused, and every section, screenshot and image name is checked before the first request.
  • SharePoint publisher: section names in log lines. The per-section log line and the collision errors printed doc.section as written, so a newline or control character in a section name could forge a log line. They now print the name on one line with controls replaced by a space.
  • SharePoint publisher: trailing dot in a name. SharePoint strips a trailing ., so a. and a were one file that the collision check treated as two. safeName now drops trailing dots (and any dashes left behind), so both come out as a and are refused as a collision.
  • SharePoint publisher: names that strip to nothing, quoting in logs and errors. safeName refused only all-dot names, so .-. or .-.- passed and the trailing strip left an empty string (a page .md, an upload path images/, a folder docsxai//); an empty result now falls back to item like an empty name does. The per-section log line quotes the section name with JSON.stringify instead of hand-written quotes, so a " in a name no longer breaks the quoting. Attachment paths in read errors are quoted on one line, and every error message is reduced to one line before it is logged or thrown, which covers the engine's path-escape error and the filesystem's own errors. The README lists the unescaped &entity; and indent cases as a known cosmetic gap.
  • SharePoint publisher: site_id and drive_id validation. A site_id or drive_id of .., or one containing /, \, ? or #, now fails config validation before any request. encodeURIComponent left .. untouched, so it reached the request path as a dot segment.
  • docsxai pack reads matrix flows. docsxai run on a flow with a matrix: block writes docs/<flow>/<variant id>/, and a pack variant key is <locale>.<theme>.<viewport width>, so pack.json could not name those directories. A sources entry can now carry "matrix": "<variant id>" next to flow and variant, and a matrixFlow block ({ flow, map, auto? }) maps every variant directory of one flow, with "auto": true taking ids already written as <locale>.<theme>.<viewport width>. A matrix id with no directory, a directory with no pack key and two ids that map to one key stop the pack, naming the variants. pack --check resolves the same way. Flat sources entries and the pack built from them are unchanged. The pack.json surface is marked experimental.
  • @docsxai/plugin-notion. A publisher plugin, notion:push, that pushes a doc pack to Notion through the public API, under a parent page (parent_page_id) or as rows of a database (database_id, with title_property). It takes the same ADF projection as the Confluence plugin and converts each document to blocks (headings, paragraphs, list items, code, images), one page per document. Screenshots go through the file upload API (POST /file_uploads, then /send) and are attached as image blocks; a screenshot over the 20 MiB upload limit is published as a note. Rewriting a page deletes its content blocks and appends the new ones, since Notion has no replace call, and leaves nested pages alone. Idempotent: a page titled docsxai manifest next to the pages records the page id and content hash of every page, and a second push of unchanged content performs zero writes; a page whose rewrite did not finish is recorded with an empty hash and redone. The token is read from the environment variable named in secretsEnv.token (default NOTION_TOKEN) and masked in every log line and error. Requests send Notion-Version: 2022-06-28, which accepts database parents. The base URL is pinned to https://api.notion.com/v1, redirects are refused, every request times out (30 s for API calls, 120 s for uploads), requests are spaced 350 ms apart and a 429 is retried after its Retry-After (at most 5 times, each wait at most 30 s), a page is rewritten only when it sits directly under the configured parent, responses are size-capped and attachment reads stay inside the workspace. Config keys are parent_page_id or database_id, title_property, base_url, title_prefix, force and manifest_page_id. The only declared capability is egress:api.notion.com. The package is "private": true for now and not published to npm. Tests run against an in-process fake Notion server. Experimental.
  • Sample repo for the CI recipes. examples/ci/sample-repo/ is a minimal workspace (flow, committed doc pack, committed baseline, pack.json) built from existing engine and viewer fixtures, and a test runs each recipe's run --verify-determinism and diff lines against it, plus pack and pack --check. The diff and pack steps need no browser; the determinism step skips without Chromium.
  • caption_style defaults to auto at every width. A themed burn used full for captures 900 px and wider; now a caption with no clear spot (clear of text, header, nav, other captions and badges) falls back to its numbered badge, on desktop too. Desktop captures with no clear spot now show their badge only; set caption_style: full to keep the old behaviour. An explicit full or badge still wins, and a burn with no theme is unchanged. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs no longer pick the style by width.
  • Docs site accessibility and copy. docsxai.dev now meets WCAG AA contrast on its primary buttons, run transcript and sidebar labels, keeps the skip-link target on the landing and 404 pages, shows a focus ring on every custom control, honours reduced motion on every custom surface, gives touch screens 44 px targets, stops the always-open sidebar groups collapsing from the keyboard, adds a search hint to the 404 and empty-search states, and shows expected output in the quickstart.
  • CLI errors and closing lines. A usage error prints the failing command's own usage line and a --help pointer instead of the whole help text, and <project-dir> is now <workspace-dir> everywhere. Failures in run, capture-auth, calibrate, lint, diagnose, burn, zip, baseline, login, push and pull end with a next: line naming the command to run, a refused or rejected backend connection prints cannot reach <url> or rejected the token instead of a stack trace, and backend URLs are printed without user:password. run ends with run: N of M flows ok, outputs in <ws>/docs, the closing lines of doctor, pull and push carry counts and destination, and docsxai-viewer rejects an unknown flag or a flag with no value (exit 2). --help gains an Examples: section; the Usage: block, exit codes and every JSON output are unchanged.
  • Viewer footer is deterministic. Pages from docsxai render ended with Rendered <timestamp>, so two renders of the same pack differed in every page. The footer now reads Rendered by @docsxai/viewer <version> and carries no clock; the no-cache metas are unchanged.
  • CLI: quoted next: hints and doctor --help. The next: and fix: lines of init, calibrate, run, lint, flow-tree, style, zip, baseline, export and doctor printed the workspace directory, flow-guide path and --cdp endpoint bare, so a path with a space or an apostrophe gave a command that did not paste; they now go through shellQuote like the backend commands already did. docsxai doctor --help and -h print the command's usage and the meaning of its rows and exit 0 (-h used to be read as a workspace directory and --help ran the checklist); every other path, exit codes included, is unchanged.
  • Docs site: wide tables scroll by keyboard. Each markdown table now sits in a docsx-table-scroll wrapper (a rehype step, website/plugins/rehype-wrap-tables.mjs) that does the scrolling; while a table is wider than the column, a script in the footer component gives the wrapper tabindex="0", role="region" and an aria-label naming its section, so a keyboard user can scroll it. Headings and anchors are unchanged. check-agent-surface.mjs fails the build if a rendered table is outside the wrapper.

Prerelease, published under the next dist-tag. 0.2.0 stays latest.

  • Breaking: upload steps are confined to the workspace. PlaywrightDriver.upload resolved its value against the workspace root and accepted an absolute path, so a flow could hand /proc/self/environ or a private key to the page it drives. The value must now be a path relative to the workspace with no .. segment, naming a regular file whose real path (symlinks followed) is under the root; anything else fails the step with upload path "..." is outside the workspace or a sibling message. Materialising a backend revision refuses a flow file with an absolute or .. upload value as well. The backend and the engine each hold a copy of the spelling rule, and a test in packages/docsxai compares them.

  • Request guard and navigate filter for webhook runs. A flow's navigate step took any absolute URL, so a tenant flow could screenshot http://169.254.169.254/... past the app_url filter, and a redirect or a DNS name could do the same. Materialising a revision now reads each flow file and refuses a navigate value that resolves (the way Playwright resolves it, so //host/x and /\host count) to an absolute URL appUrlProblem refuses or, when the project has an app_url, to one outside its origin; relative values pass. launchPlaywrightSession takes an egressGuard option and reads DOCSX_EGRESS_GUARD (1, true or yes): a context route checks every request, each redirect hop included, resolves a host name with dns.lookup for all its addresses and aborts the request when one is link-local or a cloud-metadata address, when the lookup fails or returns nothing, or when the scheme is not http(s), ws(s), data, blob or about; service workers are blocked on a guarded context. DOCSX_EGRESS_DENY_PRIVATE adds loopback, RFC 1918, CGNAT and unique-local addresses. The backend runner starts every webhook run's engine with the guard on (DOCSX_EGRESS_GUARD=0 opts out) and the private ranges on when DOCSX_BACKEND_DENY_PRIVATE_APP_URL is. A local docsxai run is unchanged. The address rules gain 168.63.129.16, 6to4 2002::/16 and Teredo 2001::/32 (the embedded IPv4 address is checked, the Teredo client decoded), 64:ff9b:1::/48, fec0::/10 and localhost.localdomain (with ip6-localhost and ip6-loopback) under the private switch. Both packages carry a byte-identical address-class.ts that a test in packages/docsxai compares. DOCSX_BACKEND_DENY_PRIVATE_APP_URL now accepts 1, true and yes in any case, and doctor flags any other non-empty value on it and on the two new switches (0, false and no count as off on purpose). @docsxai/backend gains a runtime dependency on yaml, the parser the engine already uses. The guard also routes WebSocket connections (context.routeWebSocket), and what a run prints for a refusal is generic (address not allowed, URL without userinfo or query), with the host and resolved address passed only to the onBlock callback. Not covered: DNS rebinding between the guard's lookup and the browser's; SECURITY.md says what to put around a hosted deployment. Experimental.

  • docsxai-mcp serve --http. An opt-in Streamable HTTP transport for @docsxai/mcp, with the same tool registry as stdio. It binds 127.0.0.1:8765 and serves /mcp. A bearer token of at least 32 characters is required, read from DOCSX_MCP_TOKEN or --token-file and never from an argument. A token with fewer than 8 distinct characters is refused, and so is a token file that group or other can access (POSIX). The variable is cleared from the environment once read, so spawned tool processes do not inherit it. The server refuses to start without one. A non-loopback --host needs --allow-remote, and TLS has to terminate in front. The Host header is parsed strictly as host[:port] and must name a loopback host, the bound host or an --allowed-host. An Origin must name one of those on the bound port, or match an --allowed-origin entry exactly. Bodies over 1 MiB get 413, a seventeenth session gets 429, and a session idle for 30 minutes closes. --workspace-root <dir> is required with --http: every path a tool receives has to resolve inside it, symlinks followed. docsxai doctor knows DOCSX_MCP_TOKEN. Experimental: @docsxai/mcp stays private.

  • @docsxai/plugin-guru. A publisher plugin, guru:push, that pushes a doc pack into a Guru collection through the Guru public API. It takes the same ADF projection as the Confluence plugin and renders each document to HTML, one card per document (POST /cards/extended, then PUT /cards/{id}/extended). Screenshots are uploaded with POST /attachments/upload and embedded as <img> tags pointing at the Guru-hosted URL. Idempotent: a card titled docsxai manifest in the collection records the content hash of every card and the hash and hosted URL of every image, and a second push of unchanged content performs zero writes. Credentials are the Guru user email and user token, read from the environment variables named in secretsEnv.email and secretsEnv.token (defaults GURU_USER_EMAIL and GURU_USER_TOKEN), sent as HTTP Basic auth and masked in every log line and error. The base URL is pinned to https://api.getguru.com/api/v1, redirects are refused, every request times out (30 s for API calls, 120 s for uploads, the manifest write included), a card is updated only when it is in the target collection (a manifest entry pointing elsewhere creates a new card), hosted image links must match https://content.api.getguru.com/files/view/<id> exactly, responses are size-capped and attachment reads stay inside the workspace. Config keys are collection_id, base_url, title_prefix, share_status, force and manifest_card_id. The only declared capability is egress:api.getguru.com. The package is "private": true and not published to npm. Tests run against an in-process fake Guru server. Experimental.

  • @docsxai/plugin-sharepoint. A publisher plugin, sharepoint:push, that pushes a doc pack to a SharePoint Online document library through Microsoft Graph. It takes the same ADF projection as the Confluence plugin, renders each document to markdown and uploads it with its screenshots (PUT /drives/{id}/root:/{path}:/content, images linked by relative path), so it is plain library files and not modern site pages. Idempotent: a docsxai-manifest.json next to the pages records the sha256 of every file written, and a second push of unchanged content performs zero writes. The bearer token is read from the environment variable named in secretsEnv.token (default SHAREPOINT_TOKEN) and masked in every log line and error. Config keys are drive_id or site_id, folder, graph_base_url, title_prefix and force. The only declared capability is egress:graph.microsoft.com. The package is "private": true for now and not published to npm. Tests run against an in-process fake Graph server. Experimental.

  • @docsxai/plugin-gitbook. A publisher plugin, gitbook:push, that pushes a doc pack to a GitBook space through the GitBook API. It takes the same ADF projection as the Confluence plugin and renders each document to markdown, one page per document. Content goes in through a change request: the plugin opens one (POST /spaces/{id}/change-requests), applies a content batch per changed page (POST .../content, with insert_files, insert_page and update_page changes) and merges it. Screenshots travel inline as base64 file uploads in the same batch, so egress stays on one host; a screenshot over 700,000 bytes is named in warnings and replaced by a caption. Idempotent: a hidden docsxai manifest page records the page id and content hash of every section and is written in the same change request, so an unchanged pack costs a page listing and a read of the manifest page, performs zero writes and opens no change request. A push that fails before the merge archives its change request. The API token is read from the environment variable named in secretsEnv.token (default GITBOOK_TOKEN) and masked in every log line and error. The base URL is pinned to https://api.gitbook.com/v1, redirects are refused, every request times out, responses are size-capped, a page is updated only when it sits directly under the target (parent_page_id or the top of the space) and attachment reads stay inside the workspace. Config keys are space_id, base_url, parent_page_id, title_prefix, force and manifest_page_id. The only declared capability is egress:api.gitbook.com. The package is "private": true and not published to npm. Tests run against an in-process fake GitBook server. Experimental.

  • Flow matrix. A top-level matrix: key (locales, color_schemes, viewports; each 1 to 64 unique entries, product at most 64) expands one flow file into one variant per combination at parse time. A viewport is a preset name or { width, height } with an optional lowercase name. Each variant overrides environment on the axes the matrix names, and its id joins the axes present as <locale>.<color_scheme>.<viewport> (es-ES.dark.mobile); expansion order is locales, color schemes, viewports, each as written. Steps and annotations take only: and skip: (a map from viewport, color_scheme or locale to a list; a value no matrix entry can match is a parse error), and annotations take copy_by_locale (exact tag, then language, else copy). matrix is not inherited through extends. Without a matrix the output layout and every output byte are unchanged. With one, docsxai run starts one browser per variant and writes docs/<flow>/<variant>/{screenshots/, annotations.json, halts/}; annotations.json gains an optional variant object (the schema id stays docsxai/annotations@1), a halt message names the variant ([variant es-ES.dark.mobile] step ...) and FlowExecutionError.variant carries the id. run --variant <id> runs one variant, diagnose --variant <id> diagnoses one, lint adds R015 (info, lists the variants) and R016 (warning, a copy_by_locale key no variant locale uses), flow-tree prints the variants, and push/pull carry variant directories. docsxai-viewer render and burn treat each <flow>/<variant> as a flow (discoverFlows takes { variants: true }; burn --flow <flow> also selects its variants). Not covered yet: baseline/diff, export playwright (refuses a matrix flow) and the MCP run_flows and diagnose_halt tools (runFlow rejects an unexpanded matrix flow).

  • docsxai pack and docsxai pack --check. The screenshot-pack pipeline is a product feature instead of a script each consumer copies. docsxai pack <workspace-or-raw-dir> [--from-raw] [--out <dir>] [--public-prefix <path>] [--no-optimise] [--generated-for <text>] burns each step's annotations (the viewer's renderBurn, so obstacles, placement and the dark-connector outline apply), optimises the PNG losslessly with the external oxipng binary ($DOCSX_OXIPNG_BIN or PATH; a missing binary fails with brew install oxipng unless --no-optimise), names it <flow>/<step>.<hash8>.png from the final bytes and writes manifest.json. A workspace is read through a pack.json (docsxai/pack-config@1: which capture flow feeds which variant, plus alt text); a raw capture directory (<flow>/<step>/<locale>.<theme>.<viewport>.png with a sidecar, step.json, flow.json) is read with --from-raw. Files the previous manifest listed and the new one dropped are removed by exact path and nothing else in the output directory is touched. Loopback addresses and obvious secrets in a title, caption, alt text or callout stop the build. docsxai pack <workspace-or-raw-dir> --check --against <pack-dir> [--threshold <pct>] rebuilds in memory and compares with the committed pack: equal hash is unchanged, otherwise a pixel diff gives the changed share and region, and a change over the threshold (default 0.5), a resize, a new or missing variant or a committed file that does not match its name exits 1. Both run the viewer's command through the same bin resolution as burn, so the engine still does not depend on @docsxai/viewer; the docsxai meta package needs no change.

  • docsxai/screens-pack@2. One manifest shape for both earlier ones (docsxai/screens-pack@1 and docsxai/screens-manifest@1): { schema, generated_for?, flows: { <flow>: { title?, steps: { <step>: { caption?, alt, variants: { "<locale>.<theme>.<viewport>": { src, width, height, bytes, callouts: [{ index, copy, bbox? }] } } } } } } }, text as { <locale>: text }, keys sorted, no timestamps. Locales, themes and viewports are bounded patterns, not a fixed list. @docsxai/viewer exports validatePack, buildPack, writePack, computeDrift, guardPack and the converters convertScreensPackV1 (returns the file moves it implies) and convertScreensManifestV1.

  • Public surface inventory and contract tests. docs/public-surface.md lists 121 surface items (CLI, flow-file, doc pack and schema ids, plugin API, BrowserDriver, engine library, MCP tools, backend REST and OAuth, DOCSX_* variables, .docsxai.json, viewer, Claude Code plugin), marks each stable candidate, experimental, internal or planned with the reason, states the compatibility and deprecation policy (a Breaking: CHANGELOG line, one minor of deprecation, schema ids bump), and holds the 1.0 checklist. Eleven contract test files under packages/{engine,backend,viewer,mcp,plugin}/test/contract/ compare the live surface with checked-in JSON snapshots: the CLI usage lines and exit codes, a dump of every Zod schema in doc-pack.ts (the flow matrix keys and the annotations variant included), the docsxai/verify-determinism@1 report, the BrowserDriver signatures, the plugin API types and manifest, the backend route table and error codes, the MCP tool names and argument shapes, the DOCSX_* list, the viewer CLI, burn report and docsxai/screens-pack@2 types, and the plugin's command and skill names. They need no browser. A normal run never creates or rewrites a snapshot; UPDATE_CONTRACT_SNAPSHOTS=1 rewrites one and fails that run on purpose.

  • wait_for: settled. A bounded page settle that needs no target: web fonts loaded (document.fonts), every <img> in the viewport complete, and the boxes of the viewport-visible elements (light DOM and open shadow roots) unchanged within 0.5 px on two consecutive polls. PlaywrightDriver runs a fixed in-page function every 50 ms after an animation frame; it takes four numbers and no selector, and nothing from the flow reaches the page. The budget is the step's timeout_ms (default 10 s), which is now valid with settled on any action. When it runs out the step halts with [page never settled: ...] and a message naming what was still moving (fonts, N images, layout); optional: true skips it. It replaces the chains of wait steps authors used for late font swaps and images. lint R014 (info) notes a wait step that only sleeps and points at settled; diagnose suggests it; export playwright emits a network-idle plus document.fonts.ready wait.

  • docsxai burn. docsxai burn <workspace-dir> [--flow <name>] [--out <dir>] [--report <file>] [--no-connector-outline] bakes annotations into PNG copies from the one CLI, where it was only docsxai-viewer burn. It runs the viewer's burn through the same bin resolution as render, so the engine still does not depend on @docsxai/viewer; --flow can repeat. Exit 1 when the workspace has no docs/ directory, 2 on a bad flag. The docsxai meta-package bin now points DOCSX_VIEWER_BIN at the viewer it depends on when the variable is unset, so render and burn also work in nested installs (pnpm, workspace checkouts) where the engine cannot see its sibling.

  • hide and show steps. action: hide sets visibility: hidden !important on every element its target matches, for the rest of the flow or until a show (no target lifts every hide; a target lifts the hide that used the same selector). The element keeps its box, so nothing around it reflows, and it is absent from every later screenshot, halt shots included, and hidden from the next check at once even on a page whose reduced-motion reset gives every element a tiny transition-duration (the rule carries transition: none). The driver marks the elements with a data attribute and adopts a fixed engine-owned stylesheet keyed on it, on the element's own root, so it reaches shadow trees and is not blocked by a page's CSP; the selector is only data. The driver re-marks before each screenshot, so the hiding survives navigations and re-renders. hide waits for a match to exist and halts if none does, unless optional: true. That covers the Next.js dev overlay badge (target: nextjs-portal); there is no general CSS-injection step and no display: none option (it would reflow the page). export playwright emits both steps.

  • Per-step timeout_ms. Any step that waits on a target (and a wait step's wait_for: { selector }) accepts timeout_ms, 100 to 30000. Unset, nothing changes: the default stays Playwright's 30 s for optional and non-optional steps alike, so existing flows run as before. Set it on an optional step and a missing target is skipped in that budget instead of 30 s. Rejected on steps where it would bound nothing.

  • Lint and diagnose. R011 (info): optional step with no timeout_ms. R012 (error): hide without a target. R013 (warning): a step targets, anchors an annotation to, or waits on an element an earlier hide hid. diagnose adds hints for a halted hide, for a target hidden by an earlier step, and suggests optional + a short timeout_ms on not-found.

  • Burned callouts on small screenshots. On annotation records with obstacles, the callout is at most min(280, 0.62 x image width) wide, never under 168 px (242 px on a 390 px screenshot), and when that box has no clear spot the burner tries two narrower ones before settling for the least overlap. Screenshots 452 px and wider, and records without obstacles, keep the fixed 280 px and burn to the same bytes as before.

  • placement on annotations. docsxai/annotations@1 records and flow-file step annotations accept an optional placement object, still valid without it: inside (callout inside a target big enough to hold it, no arrow), side (try only that side; arrow stays a soft hint whose corner half is ignored), align (start, center, end along the edge), pin_arrow (nudge moves only the callout, the arrow stays on the target), max_width (120 to 560), and obstacle_radius (0 to 2000 CSS px) and obstacle_limit (1 to 40), which docsxai run uses for that annotation's obstacle scan instead of 320 px and 40 boxes. Bounded and strict like obstacles. The interactive viewer ignores it.

  • docsxai-viewer burn --report <file>. Writes docsxai/burn-report@1 JSON: per annotation the callout and badge boxes, the px² still covering obstacles and other halos, badges and callouts, the overlap as a share of the callout's area, and unplaceable: true when that share is above 0.1 (--max-overlap <ratio>). The burner still draws every annotation; the pipeline decides what to drop. burnFlow returns the same report, renderBurn returns it with the PNG.

  • docsxai run --verify-determinism. docsxai run <workspace-dir> --verify-determinism [--runs <2-5>] [--format json|md|text] runs the selected flows 2 to 5 times (default 2), each into its own root under <workspace>/.docsxai-verify/run-<k>/, and byte-compares every artefact: annotations.json, screenshots, step markdown, locators and halt context. The report (docsxai/verify-determinism@1, no timestamps or paths, deterministic order) names the first differing artefact by path with a cause: the JSON key path, the changed-pixel count and bounding box of a PNG (the pixel diff docsxai diff uses), the first differing text line, or the sizes. Exit 0 identical, 1 differing or a flow halted, 2 bad flags (--runs outside 2 to 5, or any of --pause, --stop-after, --start-from, --cdp). The workspace output is written only when every run agrees (run 1's files are copied in); otherwise it is untouched. The run roots are removed at the end by their listing, with no recursive delete. Report on stdout, progress on stderr. PlaywrightSessionOptions gains an optional outputRoot, and run's flow loop moves to run-flows.ts unchanged for a plain run. The engine exports compareRuns, compareArtefactBytes and the report formatters.

  • Nightly drift recipes. docs/ci-recipes.md gains copy-paste nightly jobs for GitHub Actions (schedule and workflow_dispatch), GitLab CI (pipeline schedule) and Woodpecker (cron): install, run --verify-determinism, diff --against <baseline> --fail-on fail, and the markdown reports uploaded as an artifact. Runnable copies sit in examples/ci/ (not wired into this repository's own CI), and a test checks that they parse, that every command and flag they use appears in docsxai --help, and that the copies in the guide match the files. The page says browser capture must not run in per-PR pipelines on shared runners. A new guide, Determinism and drift, covers reading the report and fixing what varies.

  • Deprecation helper. deprecation.ts prints docsxai: <item> is deprecated since <version>, use <replacement> once per invocation and looks names up in a retired registry (warnDeprecated, findRetired). Its first use is the retired drift command.

  • login --oauth and inspect --ignore-https-errors in --help. Both already worked; the usage text, the CLI reference and the contract snapshot now carry them.

  • Project app_url. The backend Project resource gains an optional app_url: the base URL of the running app the project documents, an absolute http: or https: URL of at most 2048 characters with no embedded credentials. POST /v1/workspaces/:ws/projects takes { name, app_url? }, the new PUT /v1/workspaces/:ws/projects/:project takes { app_url: string | null } (null clears it), and an invalid value gets 400 bad_request naming app_url. BackendStore gains setProjectAppUrl and createProject an optional third argument; MemoryStore and FsStore implement both, and existing meta.json files read as before. A webhook run writes it into the materialised .docsxai.json as app_url, which is what docsxai run uses as the base URL for relative navigate values. This extends the frozen backend core additively: the backend-api contract snapshot gains the route and the optional member, no existing field or route changes.

  • caption_style defaults to auto at every width. A themed burn used full for captures 900 px and wider; now a caption with no clear spot (clear of text, header, nav, other captions and badges) falls back to its numbered badge, on desktop too. Desktop captures with no clear spot now show their badge only; set caption_style: full to keep the old behaviour. An explicit full or badge still wins, and a burn with no theme is unchanged. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs no longer pick the style by width.
  • Backend core surface. The frozen route list grows from 16 to 17 routes (PUT /v1/workspaces/:ws/projects/:project) and Project gains the optional app_url. Both are additive; docs/public-surface.md and the website reference list them.
  • Driver contract (settled). BrowserDriver gains an optional waitForSettled?(timeoutMs?). Optional, so existing third-party drivers (browxai included) keep compiling; a wait_for: settled step on a driver without it halts with a message saying so. PlaywrightDriver implements it.
  • Driver contract. BrowserDriver gains two optional methods, hideElements?(selector, timeoutMs?) and showElements?(selector | null); nearbyBoxes (from 0.2.1-rc.1) becomes optional too. A hide or show step on a driver without the method halts with a message naming it, and so does an annotated step when annotations.obstacles is on and the driver has no nearbyBoxes. Seven existing signatures widen with an optional trailing timeoutMs: click, fill, upload, press, hover, selectOption and setChecked. PlaywrightDriver implements all of it; third-party drivers may ignore timeoutMs until they want the per-step budget, and add the optional methods when a flow needs them.
  • Burned badges keep off the target's text and its neighbours. On annotation records with obstacles, docsxai-viewer burn now places the numbered badge at the corner of the halo, up to 26 px out, that covers the least of the obstacles, other halos and callouts, and of the target's own box. A flush-text target (a title, a tab, a list row) no longer loses its first letter under the badge. Callouts keep clear of the badge where it landed. Records without obstacles burn byte-identically to before; the same input still yields identical bytes.
  • Burned arrows and stems stay visible on dark screenshots. docsxai-viewer burn reads the screenshot's pixels and, where at least a third of those under an annotation's arrow and stem are dark (integer luma under 110), paints a 2 px white outline under the near-black connector. 72 of 144 remotxai images and every trackxai image have dark UIs where the ink arrow was close to invisible. On light screenshots nothing changes: the tree and the PNG bytes are those of before, and the frozen legacy fixtures still hold. The callout box, halo and badge are untouched, and the same input still yields identical bytes. --no-connector-outline (CLI) and connector: "off" (BurnOptions, burnFlow) keep plain ink everywhere; there is no new annotation or schema field.
  • docsxai drift. Replaced by docsxai pack --check before it shipped in a release. It still works: it prints a deprecation warning (since 0.3.0) and runs pack --check with the same arguments, and it is not listed in --help.
  • Flow names are path-safe. name (and extends) in a flow-file must start with a letter or digit, use only letters, digits, ., _ and -, contain no .. and be at most 64 characters, and calibrate --name follows the same rule. Before, ../.docsxai.json passed the schema, and run or run --verify-determinism would then write under that path. A flow-file with a name outside the rule now fails to parse; uppercase letters, underscores and dots are still fine.
  • run --verify-determinism refuses symlinks. A symlink in a run root stops the verification before anything is copied into the workspace, with the entry named.
  • Verify reports carry no absolute paths. Halt messages in the report are cut to their first line and every absolute path (POSIX, Windows, UNC, file://) becomes <path>, as the report header always claimed.
  • Verify comparison is bounded. Artefacts above 64 MiB are compared by size and then byte by byte in 1 MiB chunks, and reported as a bytes difference, instead of being read into memory twice.
  • docsxai pack checks the optimiser. The output of oxipng (or whatever DOCSX_OXIPNG_BIN names) has to be a complete PNG with the same pixels as its input. A binary that exits non-zero, writes garbage or is lossy stops the build and is never hashed.
  • More pack guards. Titles, captions, alt text and callouts that hold a private-network address (10/8, 172.16/12, 192.168/16, 169.254/16), an email address outside the reserved example domains, an Authorization: header that is not Bearer, or a token in a URL query (?token=, key=, sig=, signature=, access_token=, api_key=) stop the build.
  • Hardening from the pack review. pull checks every file name in a backend response before it writes anything and refuses the whole response on one bad name (a flow file must be <flow name>.flow.yaml, annotations and screenshots must sit under docs/<flow>[/<variant>]/). pack --check --against and the raw and workspace pack readers refuse symlinked PNGs and PNGs over 64 MiB, and a file that is not JSON no longer has its text quoted in the error. The run --verify-determinism report scrubs a path under /tmp, the home or temp directory or the workspace root to the end of its token run, spaces and single segments included. A flow name may not end in . or be a Windows device name (con, nul, com1 and so on), and run and pack refuse two names that differ only by case.
  • Backend app_url target filter and review follow-ups. The backend refuses a project app_url whose host is link-local or a cloud-metadata address (169.254.0.0/16, fe80::/10, fd00:ec2::254, 100.100.100.200, metadata.google.internal, instance-data, in decimal, hex, octal, IPv4-mapped and trailing-dot forms) on POST/PUT and again when a run writes .docsxai.json; the new DOCSX_BACKEND_DENY_PRIVATE_APP_URL=1 also refuses loopback, RFC 1918, CGNAT and unique-local hosts (listed in doctor and docs/public-surface.md). Materialising a workspace checks a screenshot's sha256 is 64 hex digits before the blob lookup. pull and the backend refuse a variant directory named annotations.json or screenshots. @docsxai/plugin-sharepoint refuses a graph_base_url with a non-default port, reads attachments only as regular files under a 64 MiB cap and names at most 20 invalid manifest entries per push.
  • Review fixes for the hardening and SharePoint work. @docsxai/plugin-sharepoint takes graph_base_url only as https on graph.microsoft.com, graph.microsoft.us, microsoftgraph.chinacloudapi.cn or graph.microsoft.de (loopback http only through the createSharePointPublisher({ allowLoopbackHttp: true }) test option), never follows a redirect, refuses an attachment path outside the workspace and hashes the bytes it read, refuses ./.. file names and folder segments, drops invalid or off-host manifest entries and caps manifest (8 MiB) and JSON (1 MiB) reads; the viewer's readRegularFile refuses a FIFO before opening it and caps the bytes actually read; pull also refuses annotation and screenshot paths, and the directories they sit in, that differ only by case, and variant segments and screenshot stems that are Windows device names or end in a dot; verify-determinism also scrubs a capitalised directory with a space (/Users/me/My Projects) under a known root.
  • Backend webhook runner writes a workspace the engine can run. SpawnRunner.materializeWorkspace wrote each artifact slot as <slot>.json (flows.json, annotations.json, ...) in the temp dir, a layout docsxai run cannot read: it lists flows/*.flow.yaml and exits with has no flows/ directory. It now writes flows/<name>.flow.yaml, docs/<flow>[/<variant>]/annotations.json, the screenshot bytes from the blob store under docs/<flow>[/<variant>]/screenshots/, docs/style.yaml, docs/style.json, docs/locators.yaml and .docsxai.json (app_url comes from the project's app_url, below), the same layout pull produces. Stored file names are checked with the rules pull applies (flow names as the engine's FlowName, case collisions refused); a bad name fails the job and the temp dir is removed. A test in packages/docsxai/test materialises a revision and reads it with the engine's listFlowFiles, parseFlowFile and loadWorkspaceConfig, and holds the backend's copy of the name rules to the engine's.
  • Backend webhook runner passes the workspace as an argument. SpawnRunner ran docsxai run --workspace <dir> and the viewer-refresh strategy ran docsxai render --workspace <dir> --out <dir>, but the engine reads the workspace as its first positional argument and has no such flags, so both exited 2 with missing <project-dir>. They now run docsxai run <dir> and docsxai render <dir>, and viewer-refresh reads the result from <workspace>/.viewer/index.html, where render writes it. The webhook tests used a fake engine that accepted the old flags; it now takes the positional like the real one, and a test checks the argv against the engine's own parser and bin.
  • docsxai doctor knows DOCSX_OXIPNG_BIN. The variable docsxai pack reads to find oxipng was missing from the doctor's list of DOCSX_* names, so setting it was flagged as a likely typo.
  • proxy-addr 2.0.7 to 2.0.8 in the lockfile. Clears the critical IPv4-mapped-address IP-spoofing advisory (GHSA-jqcg-44mw-7w3h) that pnpm audit --prod --audit-level=high reported through @docsxai/mcp > @modelcontextprotocol/sdk > express. express already allows ^2.0.7, so only the lockfile moved; no package manifest or override changed.

Prerelease, published under the next dist-tag to prove the OIDC trusted-publishing path. 0.2.0 stays latest.

  • Claude Code marketplace manifest. .claude-plugin/marketplace.json at the repo root (marketplace docsxai, one plugin entry sourced from ./packages/plugin) gives the plugin a real install: /plugin marketplace add kalebteccom/docsxai, then /plugin install docsxai@docsxai. Both manifests pass claude plugin validate, and a plugin test checks that the marketplace parses, lists the plugin and that its source path holds plugin.json. --plugin-dir stays the local-development path in the root and plugin READMEs.
  • Obstacle-aware callout placement for the burner. annotations.json records (docsxai/annotations@1, still valid without it) accept an optional obstacles array of { x, y, width, height } boxes the burned callout must not cover. docsxai-viewer burn then scores callouts on every side, further from the target than before (joined to the arrow by a stem) and slid along its edge, against those boxes, other halos and badges, earlier callouts and the image edge, and picks the cheapest, so a narrow target beside text no longer gets a callout over that text. Records without obstacles burn exactly as before; the same input still yields identical bytes.
  • docsxai run can write obstacles. Set "annotations": { "obstacles": true } in .docsxai.json (default off) and each annotation record gets an obstacles array: the visible text (per rendered line) and interactive elements within 320 CSS px of its target, in screenshot pixels, the target's own subtree and elements containing it left out. Boxes are whole pixels, clipped to the screenshot, deduplicated, capped at the 40 nearest and sorted by y, x, width, height. docsxai-viewer burn reads them with no further setup. With the setting off or absent, annotations.json and the screenshots are byte-identical to before; with it on, two runs against the same target state still write identical bytes. BrowserDriver gains a required nearbyBoxes(selector, radius, timeoutMs?) method (implemented by PlaywrightDriver; pre-1.0 that is a minor bump for third-party drivers), and the engine exports selectObstacles. The MCP run_flows tool honours the same setting.
  • Woodpecker CI pipeline (.woodpecker.yml): a push-triggered mirror of the GitHub quality gate (typecheck, lint, format check, build, depcruise, jscpd, unit tests, docs site build). It has no publish step and uses no secrets; releases stay in .github/workflows/release.yml. The keystone suite has a separate step that stays disabled until the CI image ships a Chromium binary.
  • caption_style defaults to auto at every width. A themed burn used full for captures 900 px and wider; now a caption with no clear spot (clear of text, header, nav, other captions and badges) falls back to its numbered badge, on desktop too. Desktop captures with no clear spot now show their badge only; set caption_style: full to keep the old behaviour. An explicit full or badge still wins, and a burn with no theme is unchanged. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs no longer pick the style by width.
  • Versioning plan stated. CONTRIBUTING.md, SECURITY.md and the release-process docs now say what the code already did: in 0.x a minor version may break the public surface (noted here, never in a patch), and 1.0 is the stability milestone. 1.0 gates full semver on the stable surface, the 1.x security support windows and the maintainer track. No date is set.
  • Release workflow hardening. release.yml builds before typecheck (the next tag would have failed on Cannot find module '@docsxai/engine'), and a new manual dry-run job (workflow_dispatch, contents: read, no environment, no OIDC token) packs, audits and dry-runs the publish of all six packages; publish and github-release run on tag pushes only. A shared scripts/release-publish.sh fails when a package version differs from the tag, publishes dependencies before dependents, skips versions already on npm so a rerun finishes a partial publish, and publishes prerelease tags under next. npm is pinned to 11.5.1. RELEASING.md now says 0.2.0 was published by hand, without attestations.
  • Docs site is for end users; agent content is plaintext Markdown. A rehype plugin strips the agent-only asides from the rendered HTML, and every published page now has a .md twin (/reference/cli.md, ...) that keeps them. agent-runbook and agent-guidance render as .md only and leave the sidebar. llms.txt links the .md versions. Agent-only notes in canonical sources are blockquotes with an agent label, converted to asides by sync-docs.mjs (shared transform in doc-pipeline.mjs). pnpm docs:build now checks the split. End-user pages link to the agent runbook on GitHub. The emitted Starlight sites from @docsxai/viewer are unchanged: they have no agent-aside convention.
  • Dependency refresh. Bumps yaml 2.9.1, satori 0.33, playwright-core 1.63, @modelcontextprotocol/sdk 1.30, prettier 3.9, eslint-plugin-import-x 4.17, typescript-eslint 8.62, the dev-deps-patch group (@eslint/js, @types/node, astro 6.4.8, esbuild, sharp), and the pinned actions/checkout 4.4.0, trufflehog 3.97.6 and zizmor-action 0.6.4 workflow actions. @astrojs/starlight 0.41 and starlight-links-validator 0.25 stay put: Starlight 0.41 requires Astro 7.
  • Astro 7. Moves the docs site and the Starlight site emitter to astro 7.3.5, @astrojs/starlight 0.41.2 and starlight-links-validator 0.25. Sites emitted by docsxai-viewer site now pin astro@7.3.5 and @astrojs/starlight@0.41.2 (Vite 8 and the Rust compiler underneath, Node >=22.12 to build). The page output and --build flow are unchanged.
  • api-login with method: GET. A link-style login (a GET route that sets the session cookie and redirects) threw Request with GET/HEAD method cannot have body. GET and HEAD now send no body and no content-type.
  • Doc and code mismatches. The calibrate skill no longer describes needs_resolution / resume engine functions that do not exist; it lists the CLI and @docsxai/mcp surface it actually has. doctor help, the plugin command and the site metadata say Node >= 26. The plugin manifest is 0.2.0 (matching package.json) and its package description no longer mentions MCP registration. /docsxai:login documents --oauth. MAINTAINERS.md no longer calls the backend a stub. @docsxai/plugin-confluence is documented as repo-only (wire it by path). The plugin README marks the install-from-GitHub-URL command as unverified.
  • Docs match the code. Stale claims corrected across the README, runbooks, package READMEs, RELEASING.md, SECURITY.md and the docs site: Node 26+ (not 20) in the CI recipes, CONTRIBUTING.md and the doctor reference; the repo is public and 0.2.0 is published; agent-driven calibration is the plugin's calibrate skill plus the @docsxai/mcp tools (not "not built"), though there is still no one-command calibration; the plugin registers no MCP server; @docsxai/mcp and the two publisher/renderer plugins are repo-only; the release workflow has one publish job on Node 26; capture-auth is the headed command and run is headless by default.
  • CI is green again. ci builds before pnpm -r typecheck and quality builds before pnpm lint, since both resolve @docsxai/* imports through dist/. The lockfile moves transitive fast-uri to 3.1.8 and ip-address to 10.7.3 (via @modelcontextprotocol/sdk), clearing the high advisories pnpm audit:prod reported.

The MVP: an LLM-agnostic engine + Claude Code plugin that walks a web app, follows written flows, and emits screenshot-rich docs. Calibration is AI-assisted and rare; execution is deterministic, agent-free, and CI-friendly.

  • docsxai on npm is the batteries-included CLI package. packages/docsxai/ carries a bin.mjs that resolves @docsxai/engine's CLI entry (new @docsxai/engine/cli export) and runs it in-process (no spawn), plus index.mjs/index.d.mts re-exporting the engine's library surface. Dependencies are exactly @docsxai/engine + @docsxai/viewer. The viewer dep is deliberate, so one pnpm add -g docsxai puts docsxai-viewer on the path and docsxai render works out of the box through the engine's layered viewer resolution. Gated by a real subprocess test (init + lint against a fixture workspace through the wrapper bin).
  • docsxai doctor [<workspace-dir>]: environment + workspace health-check: ✓/✗ checklist with a one-line fix per failing row (− rows are informational; exit 1 on any ✗). Checks: Node >= 20; Chromium presence for playwright-core (the documented one-shot install as the fix); .docsxai.json found + parseable (cwd or the arg; informational when absent); every flow-file parses (count; first error fails); auth descriptor parse + cached-session freshness (expired → capture-auth fix hint); backend reachability via GET /v1/health when backend_url is configured (with a token-presence note); the plugin declarations through the same stage-1 inspection plugins list runs: declared/installed/lock/capabilities, no plugin code executed; viewer-bin resolution naming which of the three layers hit; and DOCSX_* env sanity (DOCSX_CACHE_KEY well-formed when set; unknown DOCSX_* names flagged as likely typos).
  • Standalone stdio MCP server (docsxai-mcp bin, --workspace <dir> default) exposing calibration meta-orchestration + read-only doc-pack introspection to any MCP-speaking host, no browser primitives (live-page discovery stays browxai's surface). Fourteen tools: init_workspace, run_flows (flow filter / startFrom / stopAfter / CDP attach / bounded concurrency; per-flow ok / halt-cause / artifact paths; merged-flow environment passed into the Playwright session), render_viewer, lint_flows (incl. plugin extraRules), flow_tree, diagnose_halt, style_check, zip_pack, push_pack, pull_pack, list_flows, get_annotations, get_run_artifacts (paths only), plugins_list. Structured {ok, …} | {ok:false, error, hint} results throughout.
  • Scripted-client acceptance suite: an in-process linked client/server pair over the SDK's InMemoryTransport drives the whole surface as a non-Claude MCP client, including run_flows against the toy-site fixture over real Chromium (loopback node:http, Chromium-gated).
  • Streamable-HTTP transport is not yet implemented; the stdio transport is the supported surface.
  • Workspace plugin runtime v1: four extension points (publishers, renderers, lint-rules, auth-strategies) via a docsxai manifest on a plugin package's package.json plus a register(api) module. Resolved once per CLI invocation; mandatory <namespace>:<name> prefixing (reserved: docsxai, site-docs, core, plugins); dependsOn topological load with cycle rejection; capability declarations (egress:<host-glob>) subset-checked against workspace plugin_capabilities; in-process and unsandboxed: trust is a review signal.
  • docsxai plugins list|info|sync: status table (load/disable reasons), manifest introspection, and plugins-lock.json sha256 pinning verified before any register module is imported (mismatch fails closed; sync never executes plugin code).
  • docsxai export adf + projectDocPackToAdf: pure, deterministic Confluence ADF projection of the doc pack (zero HTTP): one consolidated document with anchored H2 flow sections (default single mode) or a parent overview + one document per flow (page-tree); markdown-subset → ADF converter (paragraphs, bold/em/code, links, lists, fenced code; raw HTML stays literal text); per-step mediaSingle nodes referencing burned PNGs (clean-screenshot fallback with a warning) plus an attachments manifest with sha256s. Writes <workspace>/.export/adf/{projection,attachments}.json: the artifact a host agent hands to the Atlassian MCP.
  • @docsxai/plugin-confluence: first publisher plugin (confluence:push): Confluence Cloud REST v2 via built-in fetch, capability-declared egress:*.atlassian.net (the only Confluence egress path: the engine emits projections only). Page identity is the { section → pageId } config.page_map (each result page echoes its section); idempotent via a docsxai-content-sha content-property: re-publishing an unchanged projection performs zero mutations, and attachment uploads are skipped when the same-name attachment carries a matching docsxai-sha256:<hex> comment; the API token is masked as <CONFLUENCE_TOKEN> in every error/log line. Verified against an in-process fake v2 server that counts mutations, loaded through the real resolvePlugins path.
  • environment block in the flow-file (clock freeze, locale, timezone, viewport incl. desktop/tablet/mobile presets, color_scheme, reduced_motion) applied at session creation; per-key child-wins extends merge; CDP-attached sessions apply what page-level APIs allow and warn once on the rest.
  • Deterministic redactions: flow-level + per-step, selector- or region-based, box (solid fill) or pixelate (16px mosaic); applied in-memory before any screenshot byte hits disk, halt screenshots included; annotation-on-redacted-target lint guard.
  • Real element_stable: best-effort bounding-box stability poll (two consecutive identical reads, 10 s budget).
  • Lint R005-R010 (missing extends target, unused locator, terminal step without success, un-guarded optional, selector-less element_stable, annotation anchored to a redacted element) + injectable extraRules for lint-rule plugins.
  • Byte-identical determinism keystone: frozen-clock + redacted flow re-run twice asserts identical screenshot bytes against real Chromium.
  • BrowserDriver.screenshot gained an optional redactions parameter (external driver implementers take note).
  • resolveWorkspacePath / resolveWorkspacePathReal: the filesystem chokepoint: every workspace artifact read/write routes through containment checks (separator-boundary prefix + realpath symlink-escape defense); typed WorkspacePathEscapeError.
  • In-process deterministic docsxai zip (fflate): no system zip binary; sorted entries, zip-epoch mtimes, fixed compression: same doc pack → byte-identical archive; workspace-escaping symlinks never archived.
  • Layered viewer-bin resolution for render: DOCSX_VIEWER_BIN → installed @docsxai/viewer bin (run with current Node) → PATH, all three attempts reported on failure.
  • Full library surface exported from the package root (lint / flow-tree / diagnose / style / backend-client / doc-pack-io / zip were previously CLI-only); dead in-engine pipeline Stage contract removed (the dropped calibration-stage shape: agent orchestration lives at the harness/MCP layer).
  • Flow-file format: declarative YAML (prerequisites / locators / steps[]), extends: composition, schema-validated, hand-editable. Actions: navigate / click / fill / upload (file-input via Playwright setInputFiles) / press / hover / select / check / uncheck / wait.
  • Deterministic runtime: docsxai run replays a doc pack headless with zero agent/LLM involvement; byte-identical re-runs (keystone test).
  • optional: true steps: best-effort steps for conditionally-present UI (confirmation modals, first-run tooltips, cookie banners); skipped (logged, no screenshot/annotation) instead of halting.
  • Calibration aids: docsxai lint (static flow-file checks), flow-tree (extends-graph + collision check), diagnose (halt context + typed recommendations), inspect (live-page locator discovery).
  • Fast iteration: run --start-from <step> --cdp <endpoint> skips to a tail step against an already-warm Chrome; sub-3-sec inner loop on long-async flows.
  • actionable() predicate: portable element-state probe (actionable/disabled/off-screen/covered/…) for browser-bridge consumers; contract in docs/actionability-contract.md.
  • Halt-cause prefix: flow-execution errors lead with an inferred 1-line cause parsed from the Playwright actionability log.
  • Target-site auth: auth/strategy.yaml descriptor + manual-capture strategy (security-lowered instrumented Chrome, local storageState cache, real-cookie-expiry tracking, persistent profile, --cdp attach).
  • Scripted auth catalogue: unattended re-auth strategies, one module per scheme under src/auth/: api-login (redirect-chain cookie collection via an own RFC-6265 jar), ui-form (drive the app's login form; pre_steps for pre-login chrome; options.totp RFC-6238 hop with dep-free generateTotp/verifyTotp), email-otp (pluggable InboxProvider polling: http-json built-in, code_pattern extraction, registerInboxProvider hook), webauthn (CDP virtual authenticator attached before navigation), jwt-injection (static token or OAuth2 client-credentials mint; localStorage/cookie injection), http-basic / pat-header / mtls (connection-level context options), test-backdoor. Credential user pools (comma-separated env values; per-worker consistent pick via resolveCreds), registerAuthStrategy plugin hook consulted before the built-ins, expiresAt derived whenever credible (cookie expiry / JWT exp / expires_in), secret values never echoed.
  • Style artifact: docsxai style init/validate + derived JSON + jargon-leak scanner (semantic-reshape enforcement).
  • Hand-off: docsxai zip packages a reviewer-ready archive (excludes operator-local .auth/, halts, .viewer/).
  • Backend client: docsxai login / push / pull against the stub backend (linear immutable revisions).

Viewer: Starlight docs site (@docsxai/viewer)

Section titled “Viewer: Starlight docs site (@docsxai/viewer)”
  • emitStarlightSite / buildStarlightSite + docsxai-viewer site: emits a complete, buildable Astro Starlight project from a doc pack: one MDX page per flow (H2 per step, step prose verbatim, <AnnotatedShot> figures with captions numbered to the burned badge indexes), a landing page of flow cards, a sidebar ordered by the flow extends graph, theme accent/logo from the style artifact's visual keys (--title/--accent overrides). Burned PNGs preferred, clean-screenshot fallback. Deterministic (two emits byte-identical), self-contained (no remote fonts/CDN imports); astro@6.4.6 + @astrojs/starlight@0.40.0 (MIT) exact-pinned into the emitted package.json; --build runs astro build against the workspace-pinned install via per-package symlinks (zero network at build), real-build E2E gated behind DOCSX_STARLIGHT_BUILD=1. The single-file interactive viewer remains the zero-dependency default/embed renderer.
  • @docsxai/plugin-starlight: first renderer plugin (starlight:site): thin adapter over the emitter/builder, zero capabilities, loaded through the real resolvePlugins path in tests.
  • docsxai baseline + docsxai diff: deterministic drift reports (docsxai/drift@1): id-keyed step deltas, annotation moves beyond a px tolerance, exact RGBA screenshot pixel diffs (with ignore_regions), prose line-change counts, locator changes; --format json|md|text (the markdown form is PR-comment-ready) and a --fail-on warn|fail CI gate. Drift detection is engine-deterministic; the patch proposal stays an explicit agent step (diagnose), never ambient.
  • docsxai export playwright: one self-contained Playwright .spec.ts per flow (extends resolved, environment as test.use() + fixed clock, optional steps try/catch-wrapped, regenerate-don't-hand-edit header): the doc pack doubles as a regression suite.

Backend: GitHub App webhook surface (@docsxai/backend)

Section titled “Backend: GitHub App webhook surface (@docsxai/backend)”
  • POST /v1/github/webhook: HMAC-SHA-256-signature-verified (timing-safe; GitHub's documented test vector pinned), event-filtered, replay-guarded (last 100 delivery ids) webhook endpoint; per-project webhook-config CRUD (repo mapping, events, output strategy, revision pin). Zero YAML in user repos. Config lives in the backend.
  • Run dispatch: per-project serial QueuedDispatcher → SpawnRunner: materializes the configured revision into a temp workspace, runs the engine CLI, appends run history.
  • Output strategies: pr-comment (GitHub REST comment with the run/drift summary), viewer-refresh (re-render recorded as a content-addressed blob), wiki-push (the project's configured publisher plugin via the engine plugin runtime). App registration, webhook URL/secret, and installation tokens are set up by hand (checklist in the backend README).

Backend: persistence, blobs, OAuth, encrypted cache (@docsxai/backend)

Section titled “Backend: persistence, blobs, OAuth, encrypted cache (@docsxai/backend)”
  • Filesystem persistence: FsStore behind the new BackendStore interface (atomic tmp+rename writes, traversal-guarded paths), selected via --data-dir / DOCSX_DATA_DIR; the in-memory store remains the default for tests.
  • Content-addressed blobs: POST/GET/HEAD /v1/blobs (sha256-addressed, deduplicated) with 10 MB JSON / 25 MB blob body limits (413). Screenshots travel as docsxai/screenshots@2 sha256 manifests; the engine HEAD-probes, uploads, and integrity-verifies on pull (base64 payloads are gone).
  • Revision finalisation: POST …/revisions/:rev/finalize; artifact PUTs afterwards are rejected 409 (revision-finalized); docsxai push finalizes: linear-immutable is now enforced, not aspirational.
  • OAuth 2.1 + PKCE: S256-only authorization-code flow with single-use 5-minute codes, refresh-token rotation, sha256-hashed token storage; CI keeps the DOCSX_TOKEN bearer path. docsxai login --oauth runs the loopback handshake and stores tokens at .auth/backend-token.json (0600) with auto-refresh.
  • Encrypted storage-state relay: PUT/GET/DELETE /v1/workspaces/:ws/auth-cache/:role stores client-side AES-256-GCM envelopes (BackendStateCache, key from DOCSX_CACHE_KEY); the backend never sees plaintext session state.
  • Run history wired: docsxai run appends execution records to backend-bound workspaces (offline-tolerant).

Viewer: burn renderer + hardening (@docsxai/viewer)

Section titled “Viewer: burn renderer + hardening (@docsxai/viewer)”
  • burn, durable burned annotations: browser-free Satori → resvg pipeline bakes halo/badge/callout/arrow onto screenshot copies (docs/<flow>/burned/), byte-deterministic, positioned by the same placeCallout as the interactive viewer; vendored Inter (OFL-1.1). The static-delivery path for Confluence/Notion-class surfaces.
  • Single-sourced overlay: the inline viewer script is bundled at build from overlay-runtime.ts importing the real placeCallout; the hand-maintained ES5 port is gone.
  • CSP + safe markdown: every emitted page carries default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'unsafe-inline' (zero network egress), and step write-ups render through micromark in safe mode instead of <pre>.
  • docsxai run applies the merged flow's environment block to every launched session; docsxai lint resolves the workspace plugin registry and runs registered lint-rule plugins after the built-ins (plugin failures degrade to core rules with a warning).
  • Claude Code plugin: calibrate + diagnose skills; run / render / login / push / pull commands.
  • Static bundle validation (validatePluginBundle) cross-checked against the engine CLI surface.
  • Static HTML viewer: pulsing halo + numbered badges + Popper-placed callouts over clean screenshots; per-annotation nudge.
  • Robust two-pass callout sizing measured on a document.body-attached probe (the callout is detached + display:none until :hover at build time, so an in-place measure bakes width:0px and collapses it to a one-character column); no-cache metas + visible render timestamp.
  • Stub service with the concrete REST endpoint list, bearer auth, in-memory linear immutable revisions. (Persistent backing + OAuth interactive flow are post-MVP.)
  • Vendorable .claude/skills/ fallback delegating to the installed plugin.
  • Apache-2.0; OSS-clean; public-release-ready content.
  • ~208 tests across the monorepo; typecheck clean; CI = typecheck + test on Node 20 / pnpm.
  • Browxai is the canonical model-agnostic discovery driver.
  • ESLint flat config with custom rules (no-tracker-ids-in-comments, no-page-eval-stringified-arrow).
  • Strict Prettier + .editorconfig + .githooks/ + extended quality CI workflow (lint / format-check / audit / secret-scan / zizmor / package-contents jobs).
  • Multi-harness configuration: AGENTS.md, .cursor/rules/, .codex/, .agents/skills/, .claude/agents/.
  • docs/ai-context subtree: architecture, agent-process, secrets-and-egress, testing, release-process, investigations, adopter-reports.
  • Governance: SECURITY.md, CODE_OF_CONDUCT.md (Contributor Covenant 2.1), MAINTAINERS.md, THIRD_PARTY_NOTICES.md, expanded CONTRIBUTING.md.
  • Security best practices for adopters.
  • Per-package tsconfig.build.json (sourceMap and declarationMap off; excludes test files).
  • Per-package builds clean dist/ + tsconfig.build.tsbuildinfo first (scripts/clean-dist.mjs), so stale compiled artifacts can never survive a rebuild or leak into a published tarball; scripts/audit-package-contents.mjs now audits the docsxai stub tarball too.
  • Dedicated packages/docsxai/ publishable stub with publishConfig for OIDC trusted publishing.
  • 6-package OIDC publish pipeline in release.yml.
  • release.yml github-release job: creates the GitHub Release for the tag (generated notes) and attaches a CycloneDX SBOM (pinned cdxgen) once both publish jobs succeed; the scoped-publish filter excludes the repo-only packages (@docsxai/{mcp,plugin-confluence,plugin-starlight,website}) explicitly, matching their private: true flags.
  • Public documentation site (docsxai.dev): Astro 6 + Starlight 0.40 workspace package in website/, ember (golden-bronze) brand layer, six-section IA (Start here / Concepts / Guides / Reference / Packages / Project). sync-docs.mjs generates the published ports from the canonical sources (docs/*.md, package READMEs, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md) with per-source-depth link rewriting and per-page strike/replace rules; scripts/prose-guard.mjs bans em/en dashes and stock AI-voice tells from every published page. Netlify deploy config + root docs:dev / docs:build / docs:preview proxies.
  • docs/agent-guidance.md: the reach-for-this-not-that footgun map for calibration agents (ten temptations, why each bites, the right call with a copyable example), synced to the site under Guides, summarised in llms.txt's new ## Guidance section, and cross-linked from "for agents" asides on the flow-file / CLI / troubleshooting / writing-plugins pages.
  • Reference worked examples: every CLI command shows a realistic invocation with its printed output and exit code; per-strategy auth descriptor snippets (env-var names only); a plugins CLI session; MCP call/result pairs per tool family; curl request/response pairs per backend route group. All output shapes transcribed from the engine/backend source, never invented.
  • Sidebar spacing per the family spec: group separation, summary padding, label sizing/tracking/opacity, item padding/line-height, and nested-item sizing aligned with the sibling sites' exact values; selectors verified against the built DOM.
  • caption_style defaults to auto at every width. A themed burn used full for captures 900 px and wider; now a caption with no clear spot (clear of text, header, nav, other captions and badges) falls back to its numbered badge, on desktop too. Desktop captures with no clear spot now show their badge only; set caption_style: full to keep the old behaviour. An explicit full or badge still wins, and a burn with no theme is unchanged. scripts/burn-trackxai.mjs and scripts/burn-probe-batch.mjs no longer pick the style by width.
  • Project-wide rename to docsxai: a single pre-publish clean break (no compatibility aliases): CLI site-docs → docsxai; npm packages @kalebtec/docsxai-* → @docsxai/* on the registered @docsxai org; env vars SITE_DOCS_* → DOCSX_*; workspace config .site-docs.json → .docsxai.json; schema ids site-docs/<thing>@N → docsxai/<thing>@N; API version header Site-Docs-API-Version → Docsxai-Api-Version; page helper window.__siteDocs → window.__docsxai; Claude Code plugin manifest + slash commands /site-docs:* → /docsxai:*. The plugin runtime keeps site-docs in RESERVED_NAMESPACES defensively.
  • Renamed workspace packages @kalebtec/site-docs-* → @kalebtec/docsxai-* (engine, backend, plugin, skill, viewer); workspace root site-docs-monorepo → docsxai-monorepo.
  • CLI bin names site-docs-backend → docsxai-backend, etc.
  • 5 scoped workspace packages flipped from private: true to publishable.
  • Repo root structure: historical closure plans moved to docs/archive/phase-plans/.
  • Lint baseline driven to 0 errors / 0 warnings (load-bearing CI gate).
  • Sourcemap leak gates added; published tarballs verified clean.
  • Updated docs/agent-runbook.md and docs/running-against-an-app-repo.md to use the current viewer / backend bin names (docsxai-viewer, docsxai-backend) after the rename from site-docs-*.
  • Refreshed packages/plugin/README.md: push / pull commands shipped, dropped from the TODO row; style-learn / translate removed entirely (not on the near-term roadmap); MCP-server note recast as a possible future addition rather than a deferred deliverable.
  • Added TypeScript configs for packages and libs and Package formatting scripts sections to docs/ai-context/agent-process/code-quality.md, codifying the per-package tsconfig.json (dev / typecheck) + tsconfig.build.json (emit, excludes tests) split and the root-cwd pnpm format / format:check convention.
  • CLI browser-install hints name the playwright-core commands that match the repo's pinned-install discipline (npx playwright-core install chromium; source checkouts: pnpm -C packages/engine exec playwright-core install chromium) instead of the unpinned npx playwright install chromium.
  • The missing-flows error now names the workspace, the expected flows/ path, and the docsxai init / docsxai calibrate next steps instead of the bare no flows directory at <path>.
  • The website build no longer logs a /404 route conflict on every run: the branded 404 moved from the docs collection to a file-based src/pages/404.astro (still Starlight-framed via <StarlightPage>), Starlight's injected 404 route is disabled, and the page now emits as 404.html, the file Netlify serves for unmatched paths (the collection entry built to 404/index.html, which Netlify ignores).
  • CI build-step ordering (added pnpm -r build before pnpm -r test so engine's workspace-package resolution works).
  • 22-day red CI on main cleared after lockfile + build-step ordering fixes.
  • 9 high-severity zizmor workflow findings cleared (cache-poisoning, excessive-permissions, unpinned-uses, bot-conditions).
  • One no-page-eval-stringified-arrow violation in packages/engine/src/playwright-instrumented-browser.ts, converted to function expression + PageEval type wrapper.
  • Empty examples/ stub directory (real keystone fixtures live at packages/engine/test/fixtures/toy-site/).
  • Workspace-root publishable stub (replaced by dedicated packages/docsxai/ sub-package).
  • Trufflehog secret-scan in CI (replaced gitleaks per universal-baseline rule 28 cost/availability).
  • Bot-identity hardening in dependabot-auto-merge.yml (user.type == 'Bot' + user.login == 'dependabot[bot]' check, not spoofable github.actor).
  • All third-party GitHub Actions SHA-pinned with version comments.
  • release.yml uses OIDC trusted publishing (no NPM_TOKEN); environment-gated; tag-triggered only.
Made by KalebtecGitHubApache-2.0 licensed