Changelog
All notable changes to this project. Format loosely follows Keep a Changelog; this project adheres to Semantic Versioning.
Changed
Section titled “Changed”runerrors that stopped with no next step now end with one.--cdpwith a matrix flow says to drop--cdpor pick a flow without a matrix, and an unknown--variantsays to drop it or pick a listed one. The--start-fromusage error no longer calls itself a calibration aid.- Warnings read
warning:everywhere. Three messages saidwarning,(runwith a relative path and noapp_url,pullwith an unknown artifact, and an ignored config or auth file). They now use the samewarning:prefix as the rest. doctorsays less about Node. The passing row isok: node: v26.1.0. A failing row saysv24.0.0, needs 26 or newerand the fix isinstall Node 26 or newer (https://nodejs.org), the same words the start-up message uses.
pack --checksays 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.diffsays when the browser build changed. When both workspaces name one browser build each inannotations.jsonand the names differ, the text and markdown reports start with one line naming both builds, and the JSON report gains an optionalbrowser_build({ a, b }). Severity and exit codes are unchanged. Surface item PACK-24, experimental.- The pack manifest records the browser build.
docsxai packwrites an optional top-levelbrowser_buildintomanifest.jsonwhen every sourceannotations.jsonnames the same build, and leaves it out when none does or they disagree. Validator, JSON Schema anddocs/pack-manifest.mdknow the key. Second step of browser-build-pin.md. Surface item PACK-22, experimental.
Changed
Section titled “Changed”docsxai renderprints only the path to open. The success line wasrender: open <index>plus a parenthetical about halos and hovering; it is nowrender: open <index>. The viewer page explains its own halos.
0.3.0-rc.5 - 2026-11-16
Section titled “0.3.0-rc.5 - 2026-11-16”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.jsonrecords the browser build.docsxai runwrites an optionalbrowser_buildkey (Chromium <version>, as the browser reports it) next todevice_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 indiffandpack --checkfollows. Surface item PACK-21, experimental.- CI recipe: viewer preview per pull request.
docs/ci-recipes.mdshows 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-determinismprints a next step. Under the first difference, the text report adds atry:line and the markdown report aTry: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.ymlat 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 indocs/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.mjsruns prettier, eslint, per-package typecheck, single-file tests and the dash guard on changed files, andscripts/new-wt.shcreates a sibling worktree with an offline install. scripts/layout-audit.mjs --engine chromium|webkit|firefox. Defaultchromium, 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 optionalmaxViewport, and hidden or 1 px clipped boxes no longer count as findings.docsxai doctorsays when an emitted site needsnpm install. A workspace with asite/folder that has no astro installed gets one informationalsiterow (never a failure) withnext: 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 jsoncarries 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,/srvpaths 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. DocumentedDOCSX_*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 anddocs/ai-contextpointers without failing - Screenshots in the emitted Starlight site open full size on tap. Each
AnnotatedShotimage is a link to its own file that the newShotLightboxcomponent 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 --examplemakes a workspace for example.com with no login and writes the README's hello flow toflows/hello.flow.yaml; it exits 2 with--app-url,--auth,--role,--ttl,--capture-triggeror--auth-cookie.render --openopens.viewer/index.htmlin the default browser (open,xdg-openor Explorer, started without a shell) and prints the path instead where none can be opened.docsxaiwith no argument, the README and the quickstart lead with these three commands. Without the new flags,initandrenderprint what they printed before docsxai doctor --format json. One document withschema(docsxai/doctor@1),version,ok,checks(name,ok,info,detail,next) andnext; every key is always present. Exit codes are the same as the text outputdocsxai --versionand-vprint the installed version. They printdocsxai <version>and exit 0, from the engine bin and thedocsxaimeta-package bin;docsxai-viewer --versionprintsdocsxai-viewer <version>- One
npm i -g docsxaireaches every output.docsxai render <workspace> --lang <locale>builds the viewer in that language (esgives 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'ssite. Thedocsxaipackage now ships adocsxai-viewerbin 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 fromDOCSX_DEVICE_SCALE_FACTORwhen the flag is absent; default 1 leaves output byte-identical.annotations.jsongetsdevice_scale_factorabove 1, its boxes and obstacles are in the PNG's device pixels, anddocsxai burntakes its pixel ratio from the filescripts/burn-trackxai.mjs --dprburns 2x captures; the viewer burn takespixelRatio. Raws in device pixels (ratio from--dpr, the sidecar'sdevice_scale_factor, or PNG width over file-name width) burn withdisplay_widthin CSS px, soscale: "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 keepwidthandheightin CSS px and addpng_widthandpng_heightdocsxai-viewer <command> --helpand-hprint that command's usage.build,burn,siteandpackshow their usage lines and flag notes and exit 0, asdocsxai help <command>does;docsxai-viewer --helpand-hprint the full help and exit 0. An unknown flag still exits 2scripts/burn-trackxai.mjs --webpwrites a lossless WebP twin beside each new PNG. It runscwebp -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. WithoutcwebponPATHit 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 runprints 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/showcaseredraws them with satori and resvg and writes the manifest the page reads burnwarns 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 getsmissing_glyphswith the script names, anddocsxai burn --strict-glyphs(also ondocsxai-viewer burn) exits 1 when any caption has one. The fix is a font for the script inburn.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_fallbacklists 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 stateschecks that status lines never shift layout. For each element in the config'sstateslist 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.jsoncovers the copy buttons and the screenshot error line.
Changed
Section titled “Changed”- 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.mjsscans 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.mdlists 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.mjsfails if the list loses a column or an entry lacks a reason or evidence.brand.css,docs/ui-rules.mdand 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.mjsfor Markdown andpackages/engine/test/prose-cadence-strings.test.tsfor 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.txtlink 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 readExecution,Step 1and 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.tsfails if one comes back in a string literal. - Viewer pages: plainer styling.
kbdkeys 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:activestate. The emittedAnnotatedShot.astroand Starlight config comments no longer carry an em dash.packages/viewer/test/viewer-ui-guard.test.tsfails 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 astrackxai/raw-capture-sidecar@1.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsread both names, exit codes are unchanged, and a run that met the old name prints one plain line saying so (inreport.mdfor the probe batch). Docs and examples use the new name. Any other schema string still fails with the file name in the message. caption_styledefaults toautoat every width. A themed burn usedfullfor 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; setcaption_style: fullto keep the old behaviour. An explicitfullorbadgestill wins, and a burn with no theme is unchanged.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsno longer pick the style by width.docsxai add-flowis the command to add a flow;calibrateis retired.calibrateis deprecated since 0.3.0 and will be removed in 0.5.0. Until then it printsdocsxai: calibrate is deprecated since 0.3.0, use add-flow (calibrate will be removed in 0.5.0)on stderr once and runsadd-flowwith the same arguments and exit codes. Output lines now start withadd-flow:.--help, the start screen,next:hints, the workspace README and the doc pages nameadd-flow, anddocsxai help calibrateprints the add-flow help. The plugin skill is renamed to match:/docsxai:add-flowdrives the agent, and/docsxai:calibratestays as a short skill that points to it until 0.5.0.push --kind calibrateis a stored revision kind and stays.- Backend
wiki-pushsettings moved to the operator (breaking). A storedwiki-pushconfig withplugin_config.sources, abase_urlor otherurlkey on a host the operator didn't list, or asecret_envthat isn'tDOCSX_WEBHOOK_SECRETorDOCSX_WEBHOOK_SECRET_<SUFFIX>now fails: aPUTgets 400 naming the field, a stored config fails its runs with the same message, and deliveries signed under an oldsecret_envget 401.path:plugins in a workspacedocsxai.config.jsonare ignored by the backend. To fix: put each publisher directory (absolute path) inDOCSX_BACKEND_PLUGIN_DIRSand dropplugin_config.sources, add eachbase_urlorigin toDOCSX_BACKEND_PUBLISHER_ORIGINS(https:only), list the variables a publisher may read inDOCSX_BACKEND_PUBLISHER_ENV(it used to see the whole backend environment), and rename a customsecret_envtoDOCSX_WEBHOOK_SECRET_<SUFFIX>. Refresh tokens now expire 30 days after they're issued, set byDOCSX_OAUTH_REFRESH_TTL_DAYS; a client idle for longer runsdocsxai loginagain. A bad value stops the server at start. - docsxai.dev tells one install story. The hero copies
npm install -g docsxai@nextand 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 andllms.txtmatch. - Burned captions follow the capture's pixel ratio. Without
scaleinburn.theme(no theme, or theclean,softandhigh-contrastpresets), the caption scale is the pixel ratio fromdevice_scale_factorinstead 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, andpack --checkagainst a pack built from them exits 1: rerundocsxai packand commit, or setburn.theme.scale: 1to keep the old size. An explicitscalenumber is used as written. In codecaptionScaletakes the pixel ratio as its third argument instead of the CSS width, and the resolved theme'sscaleisnullwhen 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.mjstakespageStatesin its config (click, scroll to the bottom, wait for a selector), andscripts/layout-audit.states.jsonholds 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 doctorspeaks the user's language and suggests the real next step. The first line isok: version: docsxai <version>. The viewer row saysfound 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 suggestsinit <workspace-dir> --exampleoutside a workspace,calibratewith an emptyflows/,runwith nothing captured andrender --openonce there are annotations; it used to sayrunevery 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 gainsroute(straight,elbow,none) andconnector_crossingsfor 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 immutableCache-Control. The landing images are hash-named, so the site config caches them like/_astro/*; a test checks the rule and thatpublic/showcaseholds only hash-named images plusmanifest.json. - Landing hero flow diagram: the muted
expect toastline meets 4.5:1 in both themes..dxf-flow code.mutedgoes 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.mjscomputes the pairs. - Guide: themed caption packs.
docs/themed-caption-packs.md(also on docsxai.dev) takes raw captures fromdocsxai runto 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_widthwithnarrow_below),connector_styleandcaption_stylewith the rule for the badge fallback and the legend it needs, reading the burn report andscripts/burn-probe.mjs, a no-overlap test a project can copy, and a worked example with a light and dark tokens pair fromexamples/burn-theme/. scripts/burn-probe-batch.mjschecks 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 fromexamples/burn-theme/, writes the burned PNGs to<out>/previews/and areport.mdwith 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.jsonandremotxai-dark.tokens.jsoncarry a teal docs look (17 px text,display_width800, 390 under 900 px).--project trackxai|remotxaipicks the probe's default tokens, and--tokens-darkand--tokens-lightstill 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, andrenderto open the viewer, each with a copy button and one line of expected output, then a link to the quickstart. The page now names thereadablepreset, the seconddisplay_widthfor narrow captures,--langandpnpm setupfor 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 byscale) 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 takescallout_border_color(inkwithout 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'sobstacles, 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 keycaption_style(full,badge,auto):badgedraws only the numbered badge and ring,autofalls back to it where no caption spot is clear, or where the connector would cross text, and marks it in the burn report. New keyconnector_style(tokenshape.connector):auto(default: the line with a theme, the triangle without),line,chevron(an open chevron at the target) orarrow(the triangle and stem as before).arrow_stylestill picks the side. Burns without a theme keep their bytes. Sample:node scripts/burn-trackxai-sample.mjswith theexamples/burn-theme/trackxai-*.tokens.jsonpair. 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 aburn.theme, a triangle connector over dark pixels is drawn solid incallout_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 (Spanisha,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:runnames theflow variantsand singleflowforms of the summary line and the indentednext:lines,/docsxai:renderandcalibratesayrenderhas no language flag and point atdocsxai-viewer buildandsitewith--lang,/docsxai:doctornames--offline,/docsxai:loginshows itslogin: ok.line,/docsxai:exportnotes that--outapplies toadftoo,/docsxai:pulllists matrix variant paths, andcalibratedrops a pointer to a step that does not exist, addswait_for: load,copy_by_locale, the two-widthdisplay_widthform and an accurateinitnext-step list.diagnosecovers a target hidden by an earlierhidestep. The plugin tests now pin the MCP tool list, theburn.themenumbers, the--langclaims and the summary line wording against the source. - Docs: burn report keys
routeandconnector_crossings, the--badge-onlyflag, anddevice_scale_factoras the burn pixel ratio are documented. The burn and annotation guides cover them, andAGENTS.mdstates the--testTimeout=30000rule for test scripts. - User-facing copy drops internal wording. The backend's
consent_requiredmessage says to ask whoever runs the server to turn on sign-in approval, and no longer names a server setting.docsxai --help, the MCPpull_packdescription and thepullcommand 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 andexamples/burn-theme/describe the example tokens pairs without product names. File, script and--projectnames 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-viewera11y-lint gainslabelledby-heading,glyph-hiddenandbadge-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
:activeand:disabledstates exist on the buttons.scripts/rendered-check.mjschecks contrast, target size, clipped text and horizontal scroll in a real browser, andwebsite/scripts/check-ui-classes.test.mjsfails 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 --examplethenrunworks 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 indoctor,runerrors and--helpno longer names the source-checkout command.docsxai site --buildnames the folder when astro is missing. From a global install it printedcannot resolve the astro package, pass astroBin, .... It now writes the site, then says astro is not installed and to runnpm installandnpm run buildin the site folder. The exit code is still 1.- Docs match the CLI again, and a test keeps them matched. The
flow-treesample showed[5 steps]and depth 1 where children print[+5 steps]and the chain is 2 deep, thelintsample had an old R004 hint,render,inspectandplugins syncsamples dropped lines they print, thedoctorsample counted 10 checks for 9,styleon a bad path quoted the wrong message, and the runbook and viewer README saidsitewarns on a missingdocs/folder when it exits 1.docs-cli-usage.test.tsreads every shell block in the README, package READMEs, plugin commands and skills,docs/*.mdand the docs site against its usage line (arguments, required flags, enumerated values), holds the CLI reference synopsis to the realdocsxai --helpusage 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.tsholds every sample output line in the CLI and plugins references to the line shapes the commands print. The viewer has the same usage check fordocsxai-viewer. - docsxai.dev: flags keep their
--, anchors stay in the column, every code block wraps. The landing hero showed an em dash beforeflowandfail-onbecause 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.mjspins the rules;website/layout-audit.jsonconfiguresscripts/layout-audit.mjsfor the five audited pages renderBurnrejects apixelRatiooutside 1 to 4.0withscale: "auto"ended inInvalid typed array length: Infinity, andNaNor a negative ratio burned at a wrong size without a word; each now throwspixelRatio must be a number from 1 to 4.scripts/burn-probe-batch.mjsburns 2x raw captures at their device scale. A frame whose sidecar hasdevice_scale_factor, or whose PNG is exactly 2 to 4 times its file-name width, now burns, pickscaption_styleand checks phone chrome in device pixels; before, the probe drew every frame at 1x and graded 2x captures wrongly. An out-of-rangedevice_scale_factorfails that frame.docsxai-viewer build|burn|siteread--flag=value, and reject an empty or repeated value.--flow=awas an unknown flag,--out ""and--max-overlap ""fell back to their defaults, and a second--outor--titlesilently won.--flowstill repeats.docsxai-viewer packburns 2x captures at their device scale. A workspaceannotations.jsonwithdevice_scale_factor, or a raw capture sidecar with the same key, now reaches the burner as its pixel ratio, asburnalready 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 runrejects 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 withneeds a value.docsxai run --start-fromno longer merges steps captured at another device scale. Earlier steps in anannotations.jsonrecorded 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 onedevice_scale_factor.- Quickstart flow passes
docsxai lintwith exit 0. Its annotation namestarget: $nav_reports, so lint no longer warns R002 and exits 1 on the page's own example, and the samplerunlines match whatrunprints (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.tspins them docsxai runacceptsfile://URLs again. The URL check added for--base-urlandapp_urlrefusedfile://, which broke runs against a local static site.runtakeshttp://,https://andfile://;ftp:,javascript:,data:,mailto:and garbage still exit 2 (--base-url) or 1 (app_url).init --app-urlandlogin --backend-urlstayhttp(s)only.- Landing page and burn theming guide no longer name
0.3.0-rc.4as the installable prerelease. The install note and the CLI card saiddocsxai@nextis0.3.0-rc.4, and the availability note on the burn theming guide saidburn.themeis available from it throughdocsxai@next;nextis0.3.0-rc.3, as the README and Installation page say. They now name0.3.0-rc.3fornextand sayburn.themeis new in the next release. New tests load everyburnblock indocs/burn-theming.mdand the burn-theme example through the real theme loader, validate the manifest indocs/pack-manifest.md, parse the flow files in the README, quickstart and flow-file reference, and check thedocsxaicommands and flags of the guides and example READMEs againstdocsxai --help. - Burn help and guides match the code.
docsxai burn --helpanddocsxai-viewer burn --helpsay that--no-connector-outlineskips reading the screenshot's pixels, so a themed line keeps the callout's outline colour and no text is estimated, and thatburn.themesets the look. The theming guide coverscaption_style, the clean halo and badge and the phone chrome numbers, and gives the auto factor of a 780 px capture at the defaultdisplay_widthas 1.09 (it said 1.08). The landing page no longer saysdocsxai@nextis0.3.0-rc.4. - A side hint no longer pulls a short callout onto a neighbour. The bonus
arrow_styleorplacement.sidegives 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 syncwith 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:.runstarted both and let them overwrite onedocs/<name>/, andlintandflow-treekept 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 --kindandpull --rev(and the other value flags of those commands,calibrate,diagnose,style,flow-tree,capture-authandplugins) silently fell back to their default, soexport adf --flowexported every flow. They now exit 2 with<flag> needs a value.inspect --wait soonandinit --persist diskexit 2 too, where they used to wait 0 ms and scaffold into the given directory. - Matrix viewport names
screenshots,haltsand Windows device names. A viewport namedscreenshotsorconmade a variant directory thatpullrefuses and Windows cannot create. The flow-file parser now rejectsscreenshots,halts,con,prn,aux,nul,com1tocom9andlpt1tolpt9as viewport names. - Session cache files. Roles
a/banda_bshared.auth/a_b.json, so one role ran with the other's session, and a role namedbackend-tokenoverwrote the OAuth token file. A role with characters outsideA-Za-z0-9_.-, andbackend-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. styleon a path that does not exist. A mistyped workspace path got a newdocs/style.yamltree created under it and exit 0.stylenow exits 1 with<path> is not a directoryand writes nothing.pushwith a doc pack it cannot read. An invaliddocs/style.jsonmadepushthrow 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.jsonthat records the backend ids is written atomically.pullwith an unknown artifact name in a revision. The names a backend listed went into the request path as they came, so../../xreached another endpoint with the bearer token.pullnow requests onlyflows,annotations,screenshots,styleandlocators, and prints a warning for any other name.zipfollowed symlinks in its fixed entries.README.md,.docsxai.json,auth/strategy.yamlordocs/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.zipalso creates the output directory only after it has something to write, and writes the archive atomically.pushread files behind symlinks. A flow file, annotations file, screenshot,style.yaml,style.jsonorlocators.yamlthat 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-backendanswers 400 to a request target the URL parser rejects. A request line such asGET //orGET //[returned a 500 withInvalid URL; it now returns a JSONbad_request.- Webhook run history records the revision that ran and the runs that never started. A
headrevision 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/namediffers only by case from the configured repo got a 404, because GitHub treats the name case-insensitively. Both stores now match it. FsStorelists projects in creation order. It listed them, and picked the project for a webhook repo, in id order;MemoryStoreused 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:andnext:lines. The Quickstart shows the starting linerunprints for each flow, points at theflows/example.flow.yaml.samplethatinitwrites and howcalibrate --fromturns it into a flow, useshttp://localhost:3000, and says a callout opens on hover, tap or Tab. docsxai doctorusage lists--offline. TheUsage:line indocsxai --help,docsxai help doctorand the CLI reference now showdocsxai doctor [<workspace-dir>] [--offline], the flag the handler already read. A new test pins the flags of every command against its usage text, itshelpscreen and the flags its handler reads, so a flag added to one without the other fails the suite. The header comment ofdocsxai-viewerlists the flags its usage text shows.- Unknown and repeated flags.
run --flwo xran every flow, because a flag no command reads was ignored, and--flow a --flow bkept the last.init,calibrate,inspect,run,lint,flow-tree,diagnose,style,zip,baseline,diff,export,plugins,login,push,pull,renderandcapture-authnow exit 2 on a flag they do not take, with adid you meanwhen one is close, and on a flag given twice.burnandpackalready did the first. run --pause <workspace>. The flag took the workspace as its value, sorunreported 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=yesexits 2.- Flow name that differs from its file name.
flows/payment.flow.yamlwithname: checkoutran fine, butextends: paymentfound nothing and the output went todocs/checkout/.lintnow warns (R017) and names both.runis unchanged. pullthat failed partway.writeDocPackwrote 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 adfandexport playwrightfollowed symlinks. A flow file, step markdown file or screenshot that was a symlink to a file outside the workspace was read: its text went intoprojection.json, and its path intoattachments.jsonfor a publisher to upload. Those files are now left out, aszipandpushdo. A symlink to a file inside the workspace still works.doctorwith an unknown or repeated flag.doctor --oflineignored the flag and probedapp_url. It now exits 2 on a flag it does not take, with adid you meanwhen one is close, on--offlinegiven twice, and on--offline=yes.--cdpconnection 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), andclose()dropped nothing.inspect --headed --cdpskipped 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. Acapture-authbrowser launched fresh is also closed when its first navigation fails.run --concurrencylost results when one flow's cleanup threw. A browser that failed to close, or a--pausewait that threw, rejected the whole worker pool:runended 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,burnorpack. 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 printinginterrupted. 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-fromor--stop-afterwith a step id that does not exist. The browser launched first and the run then ended as a failed flow, exit 1 with adoctorhint. Both flags now check the id against the selected flows before anything launches, exit 2 and list the steps the flow has.--stop-afterstill runs when at least one selected flow has the step.- Viewer links and images for names with
#,?or%.docsxai renderpercent-encodes these characters in the screenshot, flow-card, thumbnail and previous/next flow URLs. A step id such asa#bused to point ataand show a broken image. docsxai render --flowwith repeated or unknown names. A flow named twice produced two pages and two index cards, and a name with no folder underdocs/produced an empty page with no message. Each flow now renders once, and an unknown name is skipped with a warning.docsxai renderwith a directory named like a screenshot. A directory called<step>.pngunderscreenshots/crashed the copy. The step now shows the missing-screenshot state.docsxai-viewer sitewith a damagedannotations.json. A file whoseannotationsis not a list, or a record whosestepis not a string, crashed the emit. The site now warns with the same reasonsrendershows, skips the bad records and falls back to the screenshots. A directory named like a screenshot counts as a missing screenshot.docsxai-viewer sitebuilds with quotes,&, spaces,#,?and%in names. A step id with"or&was written as a JSX string without escapes, soastro buildfailed 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-2and a warning), and the heading escapes*,_,[,],&and~. Flow and step titles on the page keep the original names.docsxai-viewer site --buildexplains 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 leftsite: astro build failedwith nothing under it. Each case now prints its reason.docsxai renderanddocsxai-viewer sitewarn about a missingdocs/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 --titlewith 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 toDocumentationand control characters become spaces.docsxai packguard scansgenerated_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 sitewith names that are not plain path parts. A step id such as../../xor a flow name with:or\was joined into the output paths, so an image could land outsidesrc/assets/flows/. These flows and steps are now skipped with a warning, the same rulerenderapplies.docsxai-viewer sitewarns instead of staying silent. A--flowname the pack lacks, and adocs/style.jsonthat is not valid JSON (its accent and logo were dropped without a word), now each produce asite: warning:line.--langwith a language that has no text table warns.docsxai-viewer build --lang franddocsxai-viewer site --lang frwrote English pages and said nothing. They now print a warning that onlyenandeshave tables; the output is unchanged.docsxai-viewer build --flow <flow>renders the variants of a matrix flow.burn --flowalready selected<flow>/<variant>, butbuild --flow loginon a flow with only variant folders wrote an emptyloginpage and none of the variants.buildnow selects them the same way, and a repeated--flowname burns once.docsxai-viewer sitesays when it leaves matrix variants out. A flow that ran amatrix:block keeps its output indocs/<flow>/<variant>/, whichrendershows 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 missingannotations.json. Both now print a warning that names the variant folders.docsxai-viewer siteremoves 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 undersrc/content/docs/flows/andsrc/assets/flows/that it does not write; everything else in the directory stays.docsxai packnames the bad field in a damagedannotations.json. Abounding_boxwith a string forx, aplacement.sidethat is not a side, or a badnudge,obstacles,arrow_styleorindexfailed inside the burner withinputValue.trim is not a functionorCannot 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 thatrenderanddocsxai-viewer siteoffer 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 burnno longer aborts on an annotation whose box is off the image or has no area. Abounding_boxthat 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, andburn --reportlists it withskippedset. A box that only overhangs an edge is clipped to the image.docsxai burnno longer throws on anudgewith 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>/smno longer sets the page language.sm,md,lg,xlandxsread as locale tags, sodocsxai-viewer buildandsiteignored--langfor 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,xsto2xl, a width such as1280,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
renderandsite. Whenannotations.jsonheld 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.jsonstops with an error that names the file. A permissions error or a directory in its place was read as "no annotations":renderandsitecarried on without callouts, andburnsaid the file was missing. All three now report the path and the error code, andburnalso names the file when it is not valid JSON (renderandsitekeep warning and listing the screenshots). - A browser that will not start.
run,inspectandcapture-authprint one reason and onenext:command instead of Playwright's banner and call log: no Chromium binary gives the install command, and a--cdpendpoint nobody listens on givescannot attach to the browser at <endpoint> (ECONNREFUSED)and the--remote-debugging-portflag to start Chrome with.run --cdpno 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-urlandlogin --backend-urlreject a value that is not anhttp://orhttps://URL with exit 2 and the command's usage line (loginno longer asks forDOCSX_TOKENfirst).runstops on anapp_urlin.docsxai.jsonthat is not a URL and names the file.initon a path that is a file says so, and a refusedmkdirpointschmodat the existing parent.run,lintandflow-treeon a workspace whoseflows/was deleted printmkdir <dir>/flows, and on a non-empty directory without.docsxai.jsonsay it is not a workspace; neither suggestsinit, which refuses a non-empty directory. A cached session that is not valid JSON is called corrupt instead of expired. Apluginsentry of the wrong shape shows the two shapes that work. docsxai doctoron a broken workspace. A.docsxai.jsonit cannot read (EACCES) fails withchmod 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 ofschema "undefined"; invalid JSON points at the position in the file instead of suggestinginit --force, which rewrites it; a workspace path that does not exist or is a file fails; a deletedflows/getsmkdir <dir>/flows; and thepluginsrow no longer repeats a config failure theworkspacerow already printed.doctorexits 2 on a flag it does not know (a typo such as--offineused to probe the network), and its usage line lists--offline.- Unreadable
.docsxai.jsoninrunandcapture-auth. A config file that exists but cannot be read now prints thewas ignored (it cannot be read, EACCES)warning with thenext:line. It used to pass as a missing file and say nothing. docsxaion Node 18 and older. The CLI printsdocsxai: Node v18.20.5 is too old to start (the engine requires Node >= 26)and anext:line, and exits 1, before Playwright's own text appears. Node 20 to 25 start as before, anddoctorfails thenoderow for them.- Printed text loses its em dashes.
--helpfor the engine,pluginsand the viewer,doctordetail and fix lines,diagnoserecommendations, therun,push,pull,inspect,capture-authandrenderprogress lines, the browser login page and the generated workspace README use commas, colons or full stops. Thecli.mdand runbook samples match. Generated Playwright specs keep their comments. - Exit code for a missing prerequisite is unchanged.
lint,flow-tree,diff,pushandpullexit 2 andrunexits 1 whenflows/, a baseline orbackend_urlis missing; tests pin both and the runbook documents the split. inspectexits 1 when the page does not load. It printed a warning, listedchrome-error://chromewebdata/and exited 0. It now printsinspect: could not load <url> (<reason>)with anext: start the app, then docsxai inspect <workspace-dir>line and exits 1.run_flowswords a browser that will not start like the CLI. Therun_flowsMCP tool now reportsno Chromium binary foundorcannot attach to the browser at <endpoint> (ECONNREFUSED)inerrorand the install or Chrome command inhint, from the same helperrunuses. Other launch errors keep Playwright's text.describeBrowserLaunchandCHROMIUM_INSTALLare now exported from@docsxai/engine.- A file where
.auth/should be.capture-auth,run,inspect,doctorand therun_flowsMCP tool name the file, say it is a file where a directory is needed (ENOTDIR) and givenext: mv <file> <file>.bak.capture-authused to print Playwright's rawENOTDIR: not a directory, mkdir,runandinspectcalled it a missing session, anddoctorpassed thewritablerow.doctorflags a file atflows/,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,pushandpullprintworkspace doesn't exist: <dir>(or<path> is a file, not a workspace directory) with anext:line and exit 1.export,styleandbaselineused to exit 0 and create the directory with.export/,docs/style.yamlor.baseline/in it, andpushandpullblamed a missing.docsxai.json.baselineon a file path no longer prints a seconddocsxai:line. - Output the disk refuses in
export,zip,styleandbaseline. The message names the path you gave, never the temp file or staging directory the engine writes first, and thenext:line ischmod u+rwxon the directory that denies the write when the target does not exist yet (it used to be achmod -Ron a path that was not there).styleprints astyle:line instead ofdocsxai: cannot access. docsxai-viewersays why a command stopped.build,burn,siteandpack(also throughdocsxai burn,packandrender) printcannot access <path> (EACCES, permission denied)with achmodnext:line where they printedEACCES: permission denied, mkdir '<path>', and name a file that stands where a directory belongs.sitestops with exit 1 on a workspace ordocs/that does not exist (it used to emit a ten-file site and exit 0).buildover a missing or empty docs directory warns that the index is empty, andburnwith no flow to burn ends with anext:line.zip --outandexport --flowfailures.zip --out <directory>says the path is a directory and gives the--out <dir>/<name>.zipcommand, and--outthrough a file names the file and themv; both used to printunexpected error: EISDIRorEEXISTand ask for a bug report.export adf --flow <missing>andexport playwright --flow <missing>print the prefix once and point atdocsxai flow-treeinstead oflint.- 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,diagnoseandinit --app-url|...printed or wrote as if the flag was absent (zip ws --outwrotews.zip,init ws --app-urlmade a workspace without a URL). Each now exits 2 with<command>: --<flag> needs a valueand the command's usage line.init --authand--capture-triggershow the value they got. run --start-fromand--stop-afterwith an unknown step. The message saidstartFrom: no step with id "x", an option name from the library. It now readscannot start from step "x": flow "f" has no such step (steps: a, b), and the same forstop after.calibrate --fromon a flow-file with an error. A.yamlfile with a schema error or broken YAML was reported asnot 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 withnext: fix <the --from file>; it now points at--name.diffreport without absolute paths. The text, Markdown and JSON reports print the baseline as typed (ws/.baseline, or the--againstvalue), not/Users/.../ws/.baseline, so a report pasted into a pull request no longer carries a home directory. Anannotations.jsonthat fails the schema names the first fields, andnot valid JSONno longer uses a dash.- A missing
extendstarget.run,export adf,export playwrightanddiagnoseprintflow "kid" extends "ghost", but flows/ghost.flow.yaml does not existand anext:line.exportused to printENOENT: no such file or directory, open '<abs path>', anddiagnosesaidno flow named "ghost"about the flow you did not ask for. - Flow-file errors in
lint,flow-tree,runanddiagnose.lintandflow-treenamed the file twice (parse error in <path>: f.flow.yaml: invalid flow-file:); they now print<path>: invalid flow-file:once.diagnoseon a YAML error and on an unknown--stepends with anext:line and lists the steps.run --flow xwith no match ends withnext:. pluginsusage errors. An unknown or missing subcommand, a missing workspace or namespace and a bad--formatprint the message, the usage line and the--helppointer, where they printed the whole help text (or nothing for a bad--format).--format xmlshows the value.inspecton an app that does not answer. The warning drops Playwright'spage.goto:prefix, call log and repeated URL, names the network code (net::ERR_CONNECTION_REFUSED) and what to change, and hidesuser:passwordin--url.capture-authwith unusable credentials or descriptor. A missing credential env var and an invalidauth/strategy.yamlend with anext:line (export the variables, or the file to fix).- Notes
runprints while a flow executes. A skipped optional step, a skipped obstacle scan and a skipped annotation capture start withrun:(they started withrunFlow:), 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 anErrorhalts with its text instead ofundefined. The CDP note starts withdocsxai:. - 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 burnwith a damagedannotations.json. The error names the file (it printed the JSON parser's message alone), saysexpected an "annotations" listorannotations[0] has no "step"(it printedstep "undefined") and ends withnext: fix <file>.burn --flow zznames the flow and lists the ones that exist, where it printedburnFlow: no annotations.json under <dir>.docsxai-viewer site. An invalid--accentexits 2 with the value and the usage line (it exited 1). Anannotations.jsonthe site cannot read is asite: warning:line, not silence. A failed--buildprints the first lines of astro's report, without its stack trace ornode_modulespaths, and the command that prints the whole log.docsxai-viewerbin andpack.--help,-handhelpexit 0 (they exited 2). An unknown command prints its name on stderr before the help.packusage errors print the message, the two usage lines and the--helppointer, not the whole pack help.pack <dir>saysdoes not existoris a file, and a raw capture step withoutstep.jsonsays what the file holds and what to do.
Security
Section titled “Security”- Backend
wiki-pushno longer lets a bearer token holder choose code, hosts or secrets. A stored config could name a directory for the backend toimport(), key the webhook signature on any server variable throughsecret_env, and point a publisher'sbase_urlat 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 siteandstarlight:sitewrote step prose into the MDX page as written, so anexport,{expression}or JSX attribute in a<step>.mdran 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-startimportorexportturned 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\uescapes.visual.logoindocs/style.jsonmust name a file inside the workspace, symlinks followed; anything else prints astyle.json visual.logo ... ignoredwarning and the site has no logo. Thelogooption may still be absolute. - Four file-handling fixes.
pullrefuses to writestyle.yaml,style.jsonorlocators.yamlthrough a symlink that leaves the workspace (refusing to write docs/<name>: a symlink leads it outside the workspace). The session cache.auth/<role>.jsonis written as a new 0600 file and renamed over the old one, so an older 0644 copy never holds new cookies. Webhook run summaries sayserver file system errorinstead of carrying a server path. Re-emitting a site skips generated folders that are symlinks instead of deleting through them. pullwrotestyle.yaml,style.jsonandlocators.yamlthrough symlinks. A symlink in the workspace that pointed outside it got the backend's content written to its target.pullnow refuses withrefusing to write docs/<name>: a symlink leads it outside the workspaceand writes nothing.- Session cache written owner-only from the first byte. Saving a role's session over an older
.auth/<role>.jsonwith 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 siteno longer prunes through symlinks. Whensrc/content/docs/flows,src/assetsor 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.
0.3.0-rc.4 - 2026-10-24
Section titled “0.3.0-rc.4 - 2026-10-24”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). Theburn.themeblock of.docsxai.jsonsets the look of the halo, numbered badge, callout and arrow thatdocsxai burnanddocsxai packdraw, 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_yandfont(a TTF or OTF inside the workspace; the bundled Inter without it).presetselectsclean,softorhigh-contrastand any key overrides it;high-contrastis black on white at 21:1.fromnames a tokens file (W3C design tokens, or a nested or flat map) andtokensmaps 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 avar()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/viewerexportsloadBurnTheme,parseThemeConfig,resolveBurnTheme,themedBurner,themeStyleand the preset table. - Burned captions scale with the screenshot (
burn.theme). New keys:scale(a number from 0.5 to 4, orauto),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) andmax_width_ratio(default 0.62).scalemultiplies text, padding, outline, radius, shadow, arrow, badge, halo and callout width;autouses the screenshot width overdisplay_width, between 1 and 4, so a 1440 px capture in a 720 px column gets factor 2. A fourth preset,readable, setsauto, 15 px text, 10 and 14 px padding, a 0.55max_width_ratioand 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 doctorchecks the config, write access,app_urland backend login. New lines:config(field types, URL shape and theburn.themeshape and preset name; the viewer's value and contrast checks stay indocsxai 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,--offlineskips it, a refused connection or timeout fails) andlogin(fails whenbackend_urlis set and neitherDOCSX_TOKENnor stored OAuth tokens exist).- Sample flow in the
initscaffold.flows/example.flow.yaml.sampleparses as a flow-file and is ignored untildocsxai calibrate . --from flows/example.flow.yaml.samplewrites it. The scaffoldedREADME.mdgains an optionalburn.themesection and thedocsxai doctorstep. burnWithWorkspaceThemein@docsxai/viewer. Burns a screenshot with theburn.themeof a workspace's.docsxai.json, loaded once per workspace and cached by path and config mtime. It returns whatburnAnnotationsreturns, lets an explicitoptions.themewin, sends theme warnings tooptions.warnonce per load and throwsBurnThemeErrorfor an invalid block. Guide:docs/burn-theming.md.- First-run help.
docsxaiwith no argument prints three first steps (init,calibrate,run) and the commands grouped by purpose, each with a one-line description.docsxai --helpstarts with the same block, then prints the full usage text.docsxai help <command>anddocsxai <command> --helpprint that command's usage and one example. A mistyped command exits 2 withdid 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, howarrow_styleandplacement.sidehint a side,obstacles, the badge,scaleanddisplay_width, per-image theme overrides throughoptions.theme, and a troubleshooting table. - Screens pack manifest reference.
docs/pack-manifest.md, published as Reference, Screens pack manifest: thedocsxai/screens-pack@2fields and limits, thepack.jsonkeys, and the version policy. - JSON Schema for the screens pack and
pack.json.@docsxai/viewershipsschemas/screens-pack-2.schema.json(manifest.json) andschemas/pack-config-1.schema.json(pack.json), draft 2020-12, importable as@docsxai/viewer/schemas/<file>. Patterns and limits are copied fromvalidatePackandparsePackConfig, and a test checks each schema against the validator on the same good and bad documents.docs/pack-manifest.mdlists the rules a schema cannot say. - Accent contrast warning for the Starlight site.
docsxai-viewer sitechecks the accent against Starlight's light (#ffffff) and dark (#17181c) backgrounds and prints asite: 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_widthtakes a wide and a narrow width. Besides a number it now accepts{ "default": 720, "narrow": 358, "narrow_below": 900 }: a screenshot narrower thannarrow_belowpx (default 900) usesnarrowforscale: "auto", any other usesdefault. 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 resolvedBurnThemegainsdisplayWidthNarrowandnarrowBelow(nullfor the number form), and@docsxai/viewerexportsdisplayWidthForandNARROW_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-labelnames andaria-liveannouncements that the interactive viewer and the Starlight site add now come from oneenandestable (ui-strings.ts). A locale tag picks the language by its primary subtag:es,es-ESandes_MXgive Spanish, any other tag gives English, and the page gets a matchinglang. A matrix variant flow (<flow>/<locale>.<scheme>.<viewport>) takes the locale of its variant id;docsxai-viewer build --lang <locale>sets the rest, anddocsxai-viewer site --lang <locale>(alsobuildViewer({ lang }),config.langand thelangkey of thestarlight:siterenderer) 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.
Changed
Section titled “Changed”caption_styledefaults toautoat every width. A themed burn usedfullfor 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; setcaption_style: fullto keep the old behaviour. An explicitfullorbadgestill wins, and a burn with no theme is unchanged.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsno 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.ymlretired (#115). The GitHub Actions release workflow is removed.- Dependency refresh. Dependencies are updated across the workspace.
- First-run messages.
docsxai initends with anext:line that namescalibrate --from <flow.yaml>and leaves outcapture-authfor an--auth noneworkspace.capture-authin 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 anddocsxai doctor. - Zod 4.
@docsxai/engineand@docsxai/mcpmove tozod ^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 runprints a starting line. Each flow printsrun: <flow>, startingbefore its browser launches, so a log shows which flow is in flight. Ctrl-C (or SIGTERM) stops any command with onedocsxai: interruptedline 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 doctorprintsok:andfail:lines. Every line starts withok:orfail:and carries anext:step where there is one; the✓,✗and−glyphs and the header are gone, and the last line isok: doctor: ...orfail: doctor: .... Exit 1 on anyfail:line, as before.- The scaffolded
README.mdfollows the auth choice. An--auth noneworkspace no longer listscapture-authorauth/strategy.yaml, and the default one points at--auth nonefor an app without a login. readablecaption preset andscale: 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, andreadablelimits 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:doctorfrontmatter is valid YAML (quoted description and argument-hint), the commands point atdocsxai doctoranddiagnoseon failure,rundocuments its starting and interrupted lines,calibrategains a setup order and a burned-captions section (burn.themereadablepreset anddisplay_width), and the plugin README is the one place that names the install command. - Usage lines wrap under 100 columns. The
Usage:block ofdocsxai --helpbreaks long entries onto indented continuation lines. Commands, flags and their order are unchanged. TheExamples: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
navigatewith noapp_urlnow halts with a bracketed cause that namesapp_url,--base-urlor--ignore-https-errors. The scaffolded workspaceREADME.mdno longer shows acalibrate --descriptionflag that does not exist. - Flow-file errors name the field. A wrong type or an unknown key inside
success,wait_fororredactionsprinted a bareInvalid 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,lintandflow-treeon a directory withoutflows/end withnext: docsxai init <dir>.pushandpullwithout a usable token end with thedocsxai login ... --oauth <dir>command.runandcapture-authwarn when.docsxai.jsonexists but was ignored (invalid JSON or the wrongschema), andrunwarns when a flow navigates to a relative path with noapp_url. - Read-only or full disks. A write refused with
EACCES,EPERM,EROFSorENOSPCprintscannot access <path> (<code>, <reason>)and anext:line ininit,zip,baseline,export,runand 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 optionalBrowserDrivermethods, the lint rule range, the plugin status list, theburn.themepreset count, the session-expiry message and theplugin-sharepointpublish 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_styleorplacement.sidehint 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 withoutobstaclesand hint burn the same bytes as before. Guide:docs/burn-theming.md. - CI examples. The GitHub Actions nightly recipe now runs its
teesteps undershell: bash, so a failingdocsxai runordocsxai difffails the job (the default shell has no pipefail). The weekly GitHub and GitLab refresh recipes indocs/ci-recipes.mdinstalldocsxai@nextwith npm: they usedpnpm/action-setupwithout a pnpm version andcorepack, which Node 26 images do not ship. Addedexamples/burn-theme/and a README forexamples/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 doctorURL lines show host and path. Theloginnext-step command, thebackendline and theapp_urlline now printbackend_urlandapp_urlas 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-surfacechecks the copy buttons, table wrappers, step numbers and next links in the build. --stop-afteron an optional step. When the step named by--stop-afterwasoptional: trueand 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
environmentvalue, a rejectedstorageState), 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, anddiff --against,diff --formatandbaseline --outfell back to their defaults. Each now exits 2 with--<flag> needs a value. --flag=valuewas ignored.docsxai run <ws> --flow=tourreadflow=touras an unknown boolean flag and ran every flow. Every command now reads--flag=valuethe 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'sflows/anddocs/. A refresh clears<out>/flowsand<out>/docsbefore copying, so an--outequal to the workspace removed the sources it was about to snapshot. The command now exits 2 and touches nothing.pushpayload 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 --checklisted 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.diffnamed no file for an unreadable screenshot. A screenshot that was cut short or not a PNG (an interrupted run, a failed copy) madediffprint the PNG decoder's own message, such asInvalid file signature, with no hint of which file. The error now starts withdocs/<flow>/screenshots/<file>.docsxai-backendstarts through an installed symlink. The bin comparedprocess.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-backendflag parsing.--port=(empty) picked a random port,--port=70000crashed with a stack trace,--port 4000and--data-dir <dir>were ignored, and a mistyped flag such as--data-dri=started an in-memory server. The bin now reads both--flag=valueand--flag value, and exits 2 with a usage line for a missing value, a port outside 0-65535 or an unknown argument.docsxai-backendstartup errors. A port already in use, a port the user may not bind, and a--data-dirthat 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%Athrew out of the route matcher and returned 500internal; it now returns 400bad_request. - Backend: a 405 carries
Allow. A method the route does not serve (aDELETEon/v1/workspaces, anyOPTIONS) now answers with the methods the path does serve in anAllowheader, as HTTP requires. - Backend: an over-limit chunked upload answers 413. A body sent without
Content-Lengththat grew past the 10 MB or 25 MB limit destroyed the connection, so the client saw a reset instead of the 413payload_too_largebody. The server now answers 413 and drops the rest of the upload. - Backend: 400 only for a bad request. A missing
namecame back asinvalid 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
nullanswers 400.POST /v1/github/webhookwith the JSON bodynullthrew and returned 500; it now returns 400payload missing repository.full_name, like any other payload without a repository. - Backend: run-history bodies are type-checked.
POST .../run-historystored"ok": "false"astrueand a textduration_msasnull. It now returns 400bad_requestnaming the field unlessokis a boolean,duration_msis a non-negative number (default 0) andsummaryis a string (default empty). - Backend: run history is capped at 1000 records per project.
runs.jsonand 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-Lengththat grew past the 10 MB or 25 MB limit destroyed the connection, so the client saw a connection reset and no 413payload_too_largebody. 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-determinismandexport adfwrite 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 truncatedannotations.json. An existing file keeps its mode, and where the rename is refused (Windows) the write falls back to a plain overwrite. docsxai baselinekeeps 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/withoutflows/anddocs/.render,burnandpackforward 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 --pauseandinspect --headedno 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-afterwith 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 withstopAfter: no step with id ..., as--start-fromalready did.- An unresolved locator ref halts as a step failure. With a custom
resolveLocator, atargetor redaction$refthat resolved to nothing threw a plain error with no step id and no halt screenshot. It now halts as aFlowExecutionErrorthat names the step. When a redaction cannot be resolved, no halt screenshot is taken, since it would go out unmasked. run --start-fromwarns when it cannot merge into the existingannotations.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 awarning:line naming the file.run --concurrencyrejects a value that is not a whole number of 1 or more.abc,0,-2and1.5fell back to 1 without a message. They now exit 2 with--concurrency must be a whole number of 1 or more.zipkeeps the outputs of a flow namedhalts. Every path segment namedhaltswas excluded, sodocs/halts/vanished from the archive. Onlyhalts/directories belowdocs/<flow>/are left out now.diffscreenshot severity compares the exact changed ratio. The warn and fail thresholds were compared withpctafter it was rounded to 4 decimals, so 0.99996% counted as 1% and tripped ascreenshot_pct_warnof 1. The reportedpctis unchanged.pushnames the file whendocs/style.jsonis not valid JSON. It failed with a bareSyntaxErrorthat carried no file name. The message is now<path>/docs/style.json: invalid JSON, ....- Halt screenshot and jargon-hit paths use
/on Windows.diagnoseandstyle --checkprinted workspace-relative paths with backslashes there; they now match the POSIX form the other reports use. docsxaianddocsxai-viewerstart through an installed bin symlink. The entry check comparedimport.meta.urlwith the path the shell used, so a bin that npm links intoPATHexited 0 without running. It now also compares the real path, asdocsxai-backenddoes.HEAD /v1/healthanswers 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
authoris rejected (@docsxai/backend).POST .../revisionsstored an object as[object Object]; it now answers 400author must be a string. A missingauthorstill defaults tounknown. FsStoreremoves its temp file when a write fails (@docsxai/backend). A failed write or rename left<file>.tmp-<id>in the data dir.FsStoreno 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 nextcreateWorkspacecould overwriteworkspaces.jsonwith a single entry. Only a missing file reads as empty now; other errors answer 500.
0.3.0-rc.3 - 2026-10-09
Section titled “0.3.0-rc.3 - 2026-10-09”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-sharepointis 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_DEBUGfor errors no command handled. Thedocsxaibin (engine and meta-package) now printsdocsxai: unexpected error: <first line>and anext:line instead of a Node stack, and exits 1. WithDOCSX_DEBUG=1(ortrue,yes) it prints the stack too. URLs in either are printed without user:password or query.doctorknows the variable. The engine CLI entry exportsrunAsBin. -
Static accessibility checks in CI.
pnpm testlints rendered viewer pages and the docs-site build lints four built pages (home, 404, a docs page, a table page) forlang, oneh1, heading order,alt, form labels, landmarks, the skip link target,tabindex, empty links and buttons,aria-*names and roles, labelled scroll regions,prefers-reduced-motionand hidden scrollbars, with no browser. -
Screenshot scripts for the docs site and the viewer.
scripts/visual-capture.mjsrenders 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 intocustomCssahead oftheme.css) and setexpressiveCode: { useThemedScrollbars: false }. Every scroller gets a thin bar whose thumb is--sl-color-whiteat 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 wherescrollbar-coloris missing and the system bar under forced colors orprefers-contrast: more. The tokens--scrollbar-track,--scrollbar-thumband--scrollbar-thumb-hoveroverride it. No scrollbar is hidden. Regenerating a site adds the file and the two config lines; the emitted tree is otherwise unchanged.
Changed
Section titled “Changed”-
caption_styledefaults toautoat every width. A themed burn usedfullfor 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; setcaption_style: fullto keep the old behaviour. An explicitfullorbadgestill wins, and a burn with no theme is unchanged.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsno 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-contentsandsecret-scansteps. Theci,quality,visual-capturesanddependabot-auto-mergeGitHub Actions workflows are removed; Actions runsrelease.ymlonly. 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.
--formatvalues are listed default first everywhere:run --verify-determinismanddiffnow read[--format text|md|json].initreads[--role <role>]likeinspectandcapture-auth, and so does thecapture-authhint 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 withoutscrollbar-colorget a 12 px webkit bar, forced colours andprefers-contrast: morekeep 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.jsonhaspublishConfig.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,pushandpullerror 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/pluginand@docsxai/skilltarballs.0.3.0-rc.1and0.3.0-rc.2of both packages were published without the plugin tree (.claude-plugin/,commands/,skills/) and without the skill bundle (skill/), becausefileslisted onlydist;vendorSkill()from the npm package had nothing to copy.filesnow lists them, andscripts/audit-package-contents.mjsfails when a tarball lacks itsmain, itsbintargets or those trees.- Claude Code plugin and vendored skill. Commands pass
$ARGUMENTSas single-quoted words and say<workspace-dir>;run,export,pushand the skills cover variants,--verify-determinism,export playwright,burnandpack; skill names arecalibrateanddiagnose; the vendored skill triggers only on a docsxai workspace; a test checks every documenteddocsxaiexample 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_flowschecksstartFromandstopAfteragainst the flow's steps and adds ahintper 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_flowsreports a flow with amatrix: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, anddiagnose_haltrefuses such a flow with thedocsxai diagnose ... --variantcommand. 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_flowschecksstartFromandstopAfteragainst the flow's steps and adds ahintper 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.2surface. The pack docs cover matrix sources (sourceswithmatrix,matrixFlow),driftis namedpack --checkeverywhere, and the CLI reference, runbooks and package pages now state thedoctorenv checks and--help, thepullname rules, thatbaselineanddiffdo not read matrix variant directories, the MCP HTTP transport, the egress guard variables, the@nextinstalls, and that the MCP server and every@docsxai/plugin-*package are repo-only; 40 mismatches in all.packages/engine/test/docs-cli-mentions.test.tsfails when the README or a site page shows adocsxaicommand or flag thatdocsxai --helpdoes 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 andtitle_prefixare 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 banda-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 andtitle_prefixare cut to one line, and section names in logs and errors are quoted on one line.
0.3.0-rc.2 - 2026-10-08
Section titled “0.3.0-rc.2 - 2026-10-08”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.
Changed
Section titled “Changed”-
caption_styledefaults toautoat every width. A themed burn usedfullfor 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; setcaption_style: fullto keep the old behaviour. An explicitfullorbadgestill wins, and a burn with no theme is unchanged.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsno longer pick the style by width. -
Interactive viewer: keyboard, screen reader, contrast, motion and error states. Pages from
docsxai renderget 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 underprefers-reduced-motion; image boxes are reserved; a brokenannotations.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#e8590cmeasured 3.58:1; on#c2410cthey 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.
Security
Section titled “Security”- 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 thecannot reach,login: ok,push:andnext: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 suggestednext:commands (workspace dir, flow, step, variant, URL) are single-quoted when they are not plain words.docsxai renderskips a step id or flow name that holds/,\,..,:or a control character (a../../xid read and copied files outside the pack, a flow namedjavascript:...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 nocollectionfailed 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.
requestProblemgave a hostname lookup no time limit, so a stalled resolver left the request pending. A lookup now has 5 seconds (lookupTimeoutMson the guard options) and a request whose lookup times out is refused like any other failed lookup.SECURITY.mdalso says that on a CDP-attached context the guard cannot block service workers. - MCP token file on Windows.
serve --httpprints one stderr warning when it reads a--token-fileon Windows, where the permission check cannot run. The README andSECURITY.mdnow say--token-fileis the preferred source, because the initial environment block stays readable to other processes of the same user even after the variable is cleared. uploadpaths: hidden and reserved files refused. The upload confinement allowed.auth/<role>.json(a captured storage state),.docsxai.jsonandwebhook-job.json, which are inside the workspace. A value with any segment that starts with a dot, or that nameswebhook-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:
cdpandbaseUrlconfined.run_flowsanddiagnose_haltpassedcdpstraight toconnectOverCDP, andrun_flowstook anybaseUrl, so an HTTP client could attach to a browser on the server's host or point a run at a metadata address. Withserve --http,cdpis refused,baseUrl(and a workspaceapp_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=0switches it off;DOCSX_EGRESS_DENY_PRIVATEadds the private ranges). stdio is unchanged.@docsxai/enginenow exports theegress-guardmodule (requestProblem,envFlagOn,envFlagOffand the rest).
- Pack workspace reader: reserved names, symlinked directories, caps, error text. A
pack.jsonsourceskey of__proto__set the prototype and the entry vanished, and a flow or step namedconstructormadeflows[...]lookups throw a rawTypeError;__proto__,constructorandprototypesource names are now refused and flows and steps are read by own keys only.readRegularFilechecks only the last path component, so a symlinkedscreenshots/directory was followed; the flow, variant andscreenshots/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 aSet, a flat source and amatrixFlowwhose 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 underexamples/ci/,docs/ci-recipes.md, the README files and the website install page ran a barenpm install -g docsxai, which resolves to 0.2.0 (latest) and has nopack,--verify-determinismor matrix flows, so the recipes failed on their first docsxai command; 0.3.x is only on thenextdist-tag. The install lines now saydocsxai@nextwith a one-line note that the pin should move to the stable version whenlatestdoes, 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
conflictsreturnedok: truewhile the manifest in the same change request already held the new hashes, so the next push said unchanged. The push now returnsok: falsewith a masked message and resets those hashes in a second change request (config.forceis the fallback when that fails too). Screenshots are capped at 4 MiB per page batch (the rest are captioned and named inwarnings), page markdown at 1 MiB (refused with an error), and the screenshot read at 4 MiB instead of 64 MiB. A 429 is retried afterRetry-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}/attachmentsanswered 405 METHOD_NOT_ALLOWED, because v2 only reads attachments. Uploads now go toPOST /wiki/rest/api/content/{pageId}/child/attachment(multipartfile,comment,minorEdit, headerX-Atlassian-Token: no-check), a changed screenshot is posted to.../child/attachment/{id}/data, and the media file id comes fromextensions.fileIdin the response. A publish that fails after creating a page now throws aConfluencePublishErrorcarryingpartial.pages(and logs apage_mapfragment), 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>:/contentwith 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 tohttpson a*.sharepoint.com(or.us,.cn,.de) host with no credentials and the default port, without theAuthorizationheader; a second redirect or any otherLocationfails, and writes still refuse redirects. The manifest declaresegress:*.sharepoint.comnext toegress: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 banda-b, case-only differences, a flow namedindex) 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 forhttp,httpsandmailtowith(,), whitespace and brackets percent-encoded, titles,title_prefixand alt text lose newlines and control characters and are escaped, and heading levels are clamped to 1 to 6.graph_base_urlis returned as the parsed origin and path, refuses a query or fragment, and accepts only/v1.0or/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.deand thesharepoint.us,.cnand.dedownload domains, but the manifest declared onlyegress:graph.microsoft.comandegress:*.sharepoint.com. It now declares all eight, so a workspace'splugin_capabilitieshas to list all eight to load the plugin. README, AGENTS.md anddocs/public-surface.mdare updated. - SharePoint publisher:
!before a link. A text node ending in!followed by a link-marked node rendered as, 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 usedsafeName(fileName), and analtof..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.sectionas 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
., soa.andawere one file that the collision check treated as two.safeNamenow drops trailing dots (and any dashes left behind), so both come out asaand are refused as a collision. - SharePoint publisher: names that strip to nothing, quoting in logs and errors.
safeNamerefused only all-dot names, so.-.or.-.-passed and the trailing strip left an empty string (a page.md, an upload pathimages/, a folderdocsxai//); an empty result now falls back toitemlike an empty name does. The per-section log line quotes the section name withJSON.stringifyinstead 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_idanddrive_idvalidation. Asite_idordrive_idof.., or one containing/,\,?or#, now fails config validation before any request.encodeURIComponentleft..untouched, so it reached the request path as a dot segment.
docsxai packreads matrix flows.docsxai runon a flow with amatrix:block writesdocs/<flow>/<variant id>/, and a pack variant key is<locale>.<theme>.<viewport width>, sopack.jsoncould not name those directories. Asourcesentry can now carry"matrix": "<variant id>"next toflowandvariant, and amatrixFlowblock ({ flow, map, auto? }) maps every variant directory of one flow, with"auto": truetaking 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 --checkresolves the same way. Flatsourcesentries and the pack built from them are unchanged. Thepack.jsonsurface is markedexperimental.@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, withtitle_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 titleddocsxai manifestnext 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 insecretsEnv.token(defaultNOTION_TOKEN) and masked in every log line and error. Requests sendNotion-Version: 2022-06-28, which accepts database parents. The base URL is pinned tohttps://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 itsRetry-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 areparent_page_idordatabase_id,title_property,base_url,title_prefix,forceandmanifest_page_id. The only declared capability isegress:api.notion.com. The package is"private": truefor 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'srun --verify-determinismanddifflines against it, pluspackandpack --check. The diff and pack steps need no browser; the determinism step skips without Chromium.
Changed
Section titled “Changed”caption_styledefaults toautoat every width. A themed burn usedfullfor 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; setcaption_style: fullto keep the old behaviour. An explicitfullorbadgestill wins, and a burn with no theme is unchanged.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsno 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
--helppointer instead of the whole help text, and<project-dir>is now<workspace-dir>everywhere. Failures inrun,capture-auth,calibrate,lint,diagnose,burn,zip,baseline,login,pushandpullend with anext:line naming the command to run, a refused or rejected backend connection printscannot reach <url>orrejected the tokeninstead of a stack trace, and backend URLs are printed without user:password.runends withrun: N of M flows ok, outputs in <ws>/docs, the closing lines ofdoctor,pullandpushcarry counts and destination, anddocsxai-viewerrejects an unknown flag or a flag with no value (exit 2).--helpgains anExamples:section; theUsage:block, exit codes and every JSON output are unchanged. - Viewer footer is deterministic. Pages from
docsxai renderended withRendered <timestamp>, so two renders of the same pack differed in every page. The footer now readsRendered by @docsxai/viewer <version>and carries no clock; the no-cache metas are unchanged. - CLI: quoted
next:hints anddoctor --help. Thenext:andfix:lines ofinit,calibrate,run,lint,flow-tree,style,zip,baseline,exportanddoctorprinted the workspace directory, flow-guide path and--cdpendpoint bare, so a path with a space or an apostrophe gave a command that did not paste; they now go throughshellQuotelike the backend commands already did.docsxai doctor --helpand-hprint the command's usage and the meaning of its rows and exit 0 (-hused to be read as a workspace directory and--helpran 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-scrollwrapper (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 wrappertabindex="0",role="region"and anaria-labelnaming its section, so a keyboard user can scroll it. Headings and anchors are unchanged.check-agent-surface.mjsfails the build if a rendered table is outside the wrapper.
0.3.0-rc.1 - 2026-10-06
Section titled “0.3.0-rc.1 - 2026-10-06”Prerelease, published under the next dist-tag. 0.2.0 stays latest.
-
Breaking:
uploadsteps are confined to the workspace.PlaywrightDriver.uploadresolved its value against the workspace root and accepted an absolute path, so a flow could hand/proc/self/environor 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 withupload path "..." is outside the workspaceor 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 inpackages/docsxaicompares them. -
Request guard and
navigatefilter for webhook runs. A flow'snavigatestep took any absolute URL, so a tenant flow could screenshothttp://169.254.169.254/...past theapp_urlfilter, and a redirect or a DNS name could do the same. Materialising a revision now reads each flow file and refuses anavigatevalue that resolves (the way Playwright resolves it, so//host/xand/\hostcount) to an absolute URLappUrlProblemrefuses or, when the project has anapp_url, to one outside its origin; relative values pass.launchPlaywrightSessiontakes anegressGuardoption and readsDOCSX_EGRESS_GUARD(1,trueoryes): a context route checks every request, each redirect hop included, resolves a host name withdns.lookupfor 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 nothttp(s),ws(s),data,bloborabout; service workers are blocked on a guarded context.DOCSX_EGRESS_DENY_PRIVATEadds loopback, RFC 1918, CGNAT and unique-local addresses. The backend runner starts every webhook run's engine with the guard on (DOCSX_EGRESS_GUARD=0opts out) and the private ranges on whenDOCSX_BACKEND_DENY_PRIVATE_APP_URLis. A localdocsxai runis unchanged. The address rules gain168.63.129.16, 6to42002::/16and Teredo2001::/32(the embedded IPv4 address is checked, the Teredo client decoded),64:ff9b:1::/48,fec0::/10andlocalhost.localdomain(withip6-localhostandip6-loopback) under the private switch. Both packages carry a byte-identicaladdress-class.tsthat a test inpackages/docsxaicompares.DOCSX_BACKEND_DENY_PRIVATE_APP_URLnow accepts1,trueandyesin any case, anddoctorflags any other non-empty value on it and on the two new switches (0,falseandnocount as off on purpose).@docsxai/backendgains a runtime dependency onyaml, 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 theonBlockcallback. Not covered: DNS rebinding between the guard's lookup and the browser's;SECURITY.mdsays 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 binds127.0.0.1:8765and serves/mcp. A bearer token of at least 32 characters is required, read fromDOCSX_MCP_TOKENor--token-fileand 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--hostneeds--allow-remote, and TLS has to terminate in front. TheHostheader is parsed strictly ashost[:port]and must name a loopback host, the bound host or an--allowed-host. AnOriginmust name one of those on the bound port, or match an--allowed-originentry 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 doctorknowsDOCSX_MCP_TOKEN. Experimental:@docsxai/mcpstays 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, thenPUT /cards/{id}/extended). Screenshots are uploaded withPOST /attachments/uploadand embedded as<img>tags pointing at the Guru-hosted URL. Idempotent: a card titleddocsxai manifestin 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 insecretsEnv.emailandsecretsEnv.token(defaultsGURU_USER_EMAILandGURU_USER_TOKEN), sent as HTTP Basic auth and masked in every log line and error. The base URL is pinned tohttps://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 matchhttps://content.api.getguru.com/files/view/<id>exactly, responses are size-capped and attachment reads stay inside the workspace. Config keys arecollection_id,base_url,title_prefix,share_status,forceandmanifest_card_id. The only declared capability isegress:api.getguru.com. The package is"private": trueand 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: adocsxai-manifest.jsonnext 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 insecretsEnv.token(defaultSHAREPOINT_TOKEN) and masked in every log line and error. Config keys aredrive_idorsite_id,folder,graph_base_url,title_prefixandforce. The only declared capability isegress:graph.microsoft.com. The package is"private": truefor 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, withinsert_files,insert_pageandupdate_pagechanges) 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 inwarningsand replaced by a caption. Idempotent: a hiddendocsxai manifestpage 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 insecretsEnv.token(defaultGITBOOK_TOKEN) and masked in every log line and error. The base URL is pinned tohttps://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_idor the top of the space) and attachment reads stay inside the workspace. Config keys arespace_id,base_url,parent_page_id,title_prefix,forceandmanifest_page_id. The only declared capability isegress:api.gitbook.com. The package is"private": trueand 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 lowercasename. Each variant overridesenvironmenton 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 takeonly:andskip:(a map fromviewport,color_schemeorlocaleto a list; a value no matrix entry can match is a parse error), and annotations takecopy_by_locale(exact tag, then language, elsecopy).matrixis not inherited throughextends. Without a matrix the output layout and every output byte are unchanged. With one,docsxai runstarts one browser per variant and writesdocs/<flow>/<variant>/{screenshots/, annotations.json, halts/};annotations.jsongains an optionalvariantobject (the schema id staysdocsxai/annotations@1), a halt message names the variant ([variant es-ES.dark.mobile] step ...) andFlowExecutionError.variantcarries the id.run --variant <id>runs one variant,diagnose --variant <id>diagnoses one,lintadds R015 (info, lists the variants) and R016 (warning, acopy_by_localekey no variant locale uses),flow-treeprints the variants, andpush/pullcarry variant directories.docsxai-viewer renderandburntreat each<flow>/<variant>as a flow (discoverFlowstakes{ variants: true };burn --flow <flow>also selects its variants). Not covered yet:baseline/diff,export playwright(refuses a matrix flow) and the MCPrun_flowsanddiagnose_halttools (runFlowrejects an unexpanded matrix flow). -
docsxai packanddocsxai 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'srenderBurn, soobstacles,placementand the dark-connector outline apply), optimises the PNG losslessly with the externaloxipngbinary ($DOCSX_OXIPNG_BINor PATH; a missing binary fails withbrew install oxipngunless--no-optimise), names it<flow>/<step>.<hash8>.pngfrom the final bytes and writesmanifest.json. A workspace is read through apack.json(docsxai/pack-config@1: which capture flow feeds which variant, plus alt text); a raw capture directory (<flow>/<step>/<locale>.<theme>.<viewport>.pngwith 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 asburn, so the engine still does not depend on@docsxai/viewer; thedocsxaimeta package needs no change. -
docsxai/screens-pack@2. One manifest shape for both earlier ones (docsxai/screens-pack@1anddocsxai/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/viewerexportsvalidatePack,buildPack,writePack,computeDrift,guardPackand the convertersconvertScreensPackV1(returns the file moves it implies) andconvertScreensManifestV1. -
Public surface inventory and contract tests.
docs/public-surface.mdlists 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 eachstable candidate,experimental,internalorplannedwith the reason, states the compatibility and deprecation policy (aBreaking:CHANGELOG line, one minor of deprecation, schema ids bump), and holds the 1.0 checklist. Eleven contract test files underpackages/{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 indoc-pack.ts(the flow matrix keys and the annotationsvariantincluded), thedocsxai/verify-determinism@1report, theBrowserDriversignatures, the plugin API types and manifest, the backend route table and error codes, the MCP tool names and argument shapes, theDOCSX_*list, the viewer CLI, burn report anddocsxai/screens-pack@2types, and the plugin's command and skill names. They need no browser. A normal run never creates or rewrites a snapshot;UPDATE_CONTRACT_SNAPSHOTS=1rewrites 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.PlaywrightDriverruns 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'stimeout_ms(default 10 s), which is now valid withsettledon 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: trueskips it. It replaces the chains ofwaitsteps authors used for late font swaps and images.lintR014 (info) notes awaitstep that only sleeps and points atsettled;diagnosesuggests it;export playwrightemits a network-idle plusdocument.fonts.readywait. -
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 onlydocsxai-viewer burn. It runs the viewer'sburnthrough the same bin resolution asrender, so the engine still does not depend on@docsxai/viewer;--flowcan repeat. Exit 1 when the workspace has nodocs/directory, 2 on a bad flag. Thedocsxaimeta-package bin now pointsDOCSX_VIEWER_BINat the viewer it depends on when the variable is unset, sorenderandburnalso work in nested installs (pnpm, workspace checkouts) where the engine cannot see its sibling. -
hideandshowsteps.action: hidesetsvisibility: hidden !importanton every element itstargetmatches, for the rest of the flow or until ashow(no target lifts everyhide; a target lifts thehidethat 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 tinytransition-duration(the rule carriestransition: 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.hidewaits for a match to exist and halts if none does, unlessoptional: true. That covers the Next.js dev overlay badge (target: nextjs-portal); there is no general CSS-injection step and nodisplay: noneoption (it would reflow the page).export playwrightemits both steps. -
Per-step
timeout_ms. Any step that waits on atarget(and awaitstep'swait_for: { selector }) acceptstimeout_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):
optionalstep with notimeout_ms. R012 (error):hidewithout atarget. R013 (warning): a step targets, anchors an annotation to, or waits on an element an earlierhidehid.diagnoseadds hints for a haltedhide, for a target hidden by an earlier step, and suggestsoptional+ a shorttimeout_msonnot-found. -
Burned callouts on small screenshots. On annotation records with
obstacles, the callout is at mostmin(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 withoutobstacles, keep the fixed 280 px and burn to the same bytes as before. -
placementon annotations.docsxai/annotations@1records and flow-file step annotations accept an optionalplacementobject, still valid without it:inside(callout inside a target big enough to hold it, no arrow),side(try only that side;arrowstays a soft hint whose corner half is ignored),align(start,center,endalong the edge),pin_arrow(nudgemoves only the callout, the arrow stays on the target),max_width(120 to 560), andobstacle_radius(0 to 2000 CSS px) andobstacle_limit(1 to 40), whichdocsxai runuses for that annotation's obstacle scan instead of 320 px and 40 boxes. Bounded and strict likeobstacles. The interactive viewer ignores it. -
docsxai-viewer burn --report <file>. Writesdocsxai/burn-report@1JSON: per annotation the callout and badge boxes, the px² still coveringobstaclesand other halos, badges and callouts, the overlap as a share of the callout's area, andunplaceable: truewhen that share is above 0.1 (--max-overlap <ratio>). The burner still draws every annotation; the pipeline decides what to drop.burnFlowreturns the same report,renderBurnreturns 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 diffdocsxai diffuses), the first differing text line, or the sizes. Exit 0 identical, 1 differing or a flow halted, 2 bad flags (--runsoutside 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.PlaywrightSessionOptionsgains an optionaloutputRoot, andrun's flow loop moves torun-flows.tsunchanged for a plain run. The engine exportscompareRuns,compareArtefactBytesand the report formatters. -
Nightly drift recipes.
docs/ci-recipes.mdgains copy-paste nightly jobs for GitHub Actions (schedule andworkflow_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 inexamples/ci/(not wired into this repository's own CI), and a test checks that they parse, that every command and flag they use appears indocsxai --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.tsprintsdocsxai: <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 retireddriftcommand. -
login --oauthandinspect --ignore-https-errorsin--help. Both already worked; the usage text, the CLI reference and the contract snapshot now carry them. -
Project
app_url. The backendProjectresource gains an optionalapp_url: the base URL of the running app the project documents, an absolutehttp:orhttps:URL of at most 2048 characters with no embedded credentials.POST /v1/workspaces/:ws/projectstakes{ name, app_url? }, the newPUT /v1/workspaces/:ws/projects/:projecttakes{ app_url: string | null }(null clears it), and an invalid value gets400 bad_requestnamingapp_url.BackendStoregainssetProjectAppUrlandcreateProjectan optional third argument;MemoryStoreandFsStoreimplement both, and existingmeta.jsonfiles read as before. A webhook run writes it into the materialised.docsxai.jsonasapp_url, which is whatdocsxai runuses as the base URL for relativenavigatevalues. This extends the frozen backend core additively: thebackend-apicontract snapshot gains the route and the optional member, no existing field or route changes.
Changed
Section titled “Changed”caption_styledefaults toautoat every width. A themed burn usedfullfor 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; setcaption_style: fullto keep the old behaviour. An explicitfullorbadgestill wins, and a burn with no theme is unchanged.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsno 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) andProjectgains the optionalapp_url. Both are additive;docs/public-surface.mdand the website reference list them. - Driver contract (
settled).BrowserDrivergains an optionalwaitForSettled?(timeoutMs?). Optional, so existing third-party drivers (browxai included) keep compiling; await_for: settledstep on a driver without it halts with a message saying so.PlaywrightDriverimplements it. - Driver contract.
BrowserDrivergains two optional methods,hideElements?(selector, timeoutMs?)andshowElements?(selector | null);nearbyBoxes(from0.2.1-rc.1) becomes optional too. Ahideorshowstep on a driver without the method halts with a message naming it, and so does an annotated step whenannotations.obstaclesis on and the driver has nonearbyBoxes. Seven existing signatures widen with an optional trailingtimeoutMs:click,fill,upload,press,hover,selectOptionandsetChecked.PlaywrightDriverimplements all of it; third-party drivers may ignoretimeoutMsuntil 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 burnnow 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 withoutobstaclesburn byte-identically to before; the same input still yields identical bytes. - Burned arrows and stems stay visible on dark screenshots.
docsxai-viewer burnreads 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) andconnector: "off"(BurnOptions,burnFlow) keep plain ink everywhere; there is no new annotation or schema field.
Deprecated
Section titled “Deprecated”docsxai drift. Replaced bydocsxai pack --checkbefore it shipped in a release. It still works: it prints a deprecation warning (since 0.3.0) and runspack --checkwith the same arguments, and it is not listed in--help.
Security
Section titled “Security”- Flow names are path-safe.
name(andextends) in a flow-file must start with a letter or digit, use only letters, digits,.,_and-, contain no..and be at most 64 characters, andcalibrate --namefollows the same rule. Before,../.docsxai.jsonpassed the schema, andrunorrun --verify-determinismwould 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-determinismrefuses 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
bytesdifference, instead of being read into memory twice. docsxai packchecks the optimiser. The output ofoxipng(or whateverDOCSX_OXIPNG_BINnames) 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 notBearer, or a token in a URL query (?token=,key=,sig=,signature=,access_token=,api_key=) stop the build.
- Hardening from the pack review.
pullchecks 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 underdocs/<flow>[/<variant>]/).pack --check --againstand 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. Therun --verify-determinismreport 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,com1and so on), andrunandpackrefuse two names that differ only by case. - Backend
app_urltarget filter and review follow-ups. The backend refuses a projectapp_urlwhose 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) onPOST/PUTand again when a run writes.docsxai.json; the newDOCSX_BACKEND_DENY_PRIVATE_APP_URL=1also refuses loopback, RFC 1918, CGNAT and unique-local hosts (listed indoctoranddocs/public-surface.md). Materialising a workspace checks a screenshot'ssha256is 64 hex digits before the blob lookup.pulland the backend refuse a variant directory namedannotations.jsonorscreenshots.@docsxai/plugin-sharepointrefuses agraph_base_urlwith 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-sharepointtakesgraph_base_urlonly ashttpsongraph.microsoft.com,graph.microsoft.us,microsoftgraph.chinacloudapi.cnorgraph.microsoft.de(loopbackhttponly through thecreateSharePointPublisher({ 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'sreadRegularFilerefuses a FIFO before opening it and caps the bytes actually read;pullalso 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-determinismalso 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.materializeWorkspacewrote each artifact slot as<slot>.json(flows.json,annotations.json, ...) in the temp dir, a layoutdocsxai runcannot read: it listsflows/*.flow.yamland exits withhas no flows/ directory. It now writesflows/<name>.flow.yaml,docs/<flow>[/<variant>]/annotations.json, the screenshot bytes from the blob store underdocs/<flow>[/<variant>]/screenshots/,docs/style.yaml,docs/style.json,docs/locators.yamland.docsxai.json(app_urlcomes from the project'sapp_url, below), the same layoutpullproduces. Stored file names are checked with the rulespullapplies (flow names as the engine'sFlowName, case collisions refused); a bad name fails the job and the temp dir is removed. A test inpackages/docsxai/testmaterialises a revision and reads it with the engine'slistFlowFiles,parseFlowFileandloadWorkspaceConfig, and holds the backend's copy of the name rules to the engine's. - Backend webhook runner passes the workspace as an argument.
SpawnRunnerrandocsxai run --workspace <dir>and theviewer-refreshstrategy randocsxai 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 withmissing <project-dir>. They now rundocsxai run <dir>anddocsxai render <dir>, andviewer-refreshreads the result from<workspace>/.viewer/index.html, whererenderwrites 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 doctorknowsDOCSX_OXIPNG_BIN. The variabledocsxai packreads to findoxipngwas missing from the doctor's list ofDOCSX_*names, so setting it was flagged as a likely typo.proxy-addr2.0.7 to 2.0.8 in the lockfile. Clears the critical IPv4-mapped-address IP-spoofing advisory (GHSA-jqcg-44mw-7w3h) thatpnpm audit --prod --audit-level=highreported through@docsxai/mcp>@modelcontextprotocol/sdk>express.expressalready allows^2.0.7, so only the lockfile moved; no package manifest or override changed.
0.2.1-rc.1 - 2026-10-05
Section titled “0.2.1-rc.1 - 2026-10-05”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.jsonat the repo root (marketplacedocsxai, 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 passclaude plugin validate, and a plugin test checks that the marketplace parses, lists the plugin and that its source path holdsplugin.json.--plugin-dirstays the local-development path in the root and plugin READMEs. - Obstacle-aware callout placement for the burner.
annotations.jsonrecords (docsxai/annotations@1, still valid without it) accept an optionalobstaclesarray of{ x, y, width, height }boxes the burned callout must not cover.docsxai-viewer burnthen 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 withoutobstaclesburn exactly as before; the same input still yields identical bytes. docsxai runcan write obstacles. Set"annotations": { "obstacles": true }in.docsxai.json(default off) and each annotation record gets anobstaclesarray: 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 burnreads them with no further setup. With the setting off or absent,annotations.jsonand the screenshots are byte-identical to before; with it on, two runs against the same target state still write identical bytes.BrowserDrivergains a requirednearbyBoxes(selector, radius, timeoutMs?)method (implemented byPlaywrightDriver; pre-1.0 that is a minor bump for third-party drivers), and the engine exportsselectObstacles. The MCPrun_flowstool 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.
Changed
Section titled “Changed”caption_styledefaults toautoat every width. A themed burn usedfullfor 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; setcaption_style: fullto keep the old behaviour. An explicitfullorbadgestill wins, and a burn with no theme is unchanged.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsno longer pick the style by width.- Versioning plan stated.
CONTRIBUTING.md,SECURITY.mdand the release-process docs now say what the code already did: in0.xa 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, the1.xsecurity support windows and the maintainer track. No date is set. - Release workflow hardening.
release.ymlbuilds before typecheck (the next tag would have failed onCannot find module '@docsxai/engine'), and a new manualdry-runjob (workflow_dispatch,contents: read, no environment, no OIDC token) packs, audits and dry-runs the publish of all six packages;publishandgithub-releaserun on tag pushes only. A sharedscripts/release-publish.shfails 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 undernext. npm is pinned to 11.5.1.RELEASING.mdnow says0.2.0was 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
.mdtwin (/reference/cli.md, ...) that keeps them.agent-runbookandagent-guidancerender as.mdonly and leave the sidebar.llms.txtlinks the.mdversions. Agent-only notes in canonical sources are blockquotes with an agent label, converted to asides bysync-docs.mjs(shared transform indoc-pipeline.mjs).pnpm docs:buildnow checks the split. End-user pages link to the agent runbook on GitHub. The emitted Starlight sites from@docsxai/viewerare unchanged: they have no agent-aside convention. - Dependency refresh. Bumps
yaml2.9.1,satori0.33,playwright-core1.63,@modelcontextprotocol/sdk1.30,prettier3.9,eslint-plugin-import-x4.17,typescript-eslint8.62, thedev-deps-patchgroup (@eslint/js,@types/node,astro6.4.8,esbuild,sharp), and the pinnedactions/checkout4.4.0,trufflehog3.97.6 andzizmor-action0.6.4 workflow actions.@astrojs/starlight0.41 andstarlight-links-validator0.25 stay put: Starlight 0.41 requires Astro 7. - Astro 7. Moves the docs site and the Starlight site emitter to
astro7.3.5,@astrojs/starlight0.41.2 andstarlight-links-validator0.25. Sites emitted bydocsxai-viewer sitenow pinastro@7.3.5and@astrojs/starlight@0.41.2(Vite 8 and the Rust compiler underneath, Node >=22.12 to build). The page output and--buildflow are unchanged.
api-loginwithmethod: GET. A link-style login (a GET route that sets the session cookie and redirects) threwRequest with GET/HEAD method cannot have body. GET and HEAD now send no body and no content-type.- Doc and code mismatches. The
calibrateskill no longer describesneeds_resolution/resumeengine functions that do not exist; it lists the CLI and@docsxai/mcpsurface it actually has.doctorhelp, the plugin command and the site metadata say Node >= 26. The plugin manifest is0.2.0(matchingpackage.json) and its package description no longer mentions MCP registration./docsxai:logindocuments--oauth.MAINTAINERS.mdno longer calls the backend a stub.@docsxai/plugin-confluenceis documented as repo-only (wire it bypath). 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.mdand the docs site: Node 26+ (not 20) in the CI recipes,CONTRIBUTING.mdand thedoctorreference; the repo is public and0.2.0is published; agent-driven calibration is the plugin'scalibrateskill plus the@docsxai/mcptools (not "not built"), though there is still no one-command calibration; the plugin registers no MCP server;@docsxai/mcpand the two publisher/renderer plugins are repo-only; the release workflow has onepublishjob on Node 26;capture-authis the headed command andrunis headless by default. - CI is green again.
cibuilds beforepnpm -r typecheckandqualitybuilds beforepnpm lint, since both resolve@docsxai/*imports throughdist/. The lockfile moves transitivefast-urito 3.1.8 andip-addressto 10.7.3 (via@modelcontextprotocol/sdk), clearing the high advisoriespnpm audit:prodreported.
0.2.0 - 2026-06-26
Section titled “0.2.0 - 2026-06-26”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.
Bare docsxai meta-package
Section titled “Bare docsxai meta-package”docsxaion npm is the batteries-included CLI package.packages/docsxai/carries abin.mjsthat resolves@docsxai/engine's CLI entry (new@docsxai/engine/cliexport) and runs it in-process (no spawn), plusindex.mjs/index.d.mtsre-exporting the engine's library surface. Dependencies are exactly@docsxai/engine+@docsxai/viewer. The viewer dep is deliberate, so onepnpm add -g docsxaiputsdocsxai-vieweron the path anddocsxai renderworks out of the box through the engine's layered viewer resolution. Gated by a real subprocess test (init+lintagainst a fixture workspace through the wrapper bin).
Engine: docsxai doctor
Section titled “Engine: docsxai doctor”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.jsonfound + parseable (cwd or the arg; informational when absent); every flow-file parses (count; first error fails); auth descriptor parse + cached-session freshness (expired →capture-authfix hint); backend reachability viaGET /v1/healthwhenbackend_urlis configured (with a token-presence note); the plugin declarations through the same stage-1 inspectionplugins listruns: declared/installed/lock/capabilities, no plugin code executed; viewer-bin resolution naming which of the three layers hit; andDOCSX_*env sanity (DOCSX_CACHE_KEYwell-formed when set; unknownDOCSX_*names flagged as likely typos).
MCP server (@docsxai/mcp)
Section titled “MCP server (@docsxai/mcp)”- Standalone stdio MCP server (
docsxai-mcpbin,--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-flowenvironmentpassed into the Playwright session),render_viewer,lint_flows(incl. pluginextraRules),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
InMemoryTransportdrives the whole surface as a non-Claude MCP client, includingrun_flowsagainst the toy-site fixture over real Chromium (loopbacknode:http, Chromium-gated). - Streamable-HTTP transport is not yet implemented; the stdio transport is the supported surface.
Engine: plugins runtime (@docsxai/engine)
Section titled “Engine: plugins runtime (@docsxai/engine)”- Workspace plugin runtime v1: four extension points (publishers, renderers, lint-rules, auth-strategies) via a
docsxaimanifest on a plugin package'spackage.jsonplus aregister(api)module. Resolved once per CLI invocation; mandatory<namespace>:<name>prefixing (reserved:docsxai,site-docs,core,plugins);dependsOntopological load with cycle rejection; capability declarations (egress:<host-glob>) subset-checked against workspaceplugin_capabilities; in-process and unsandboxed:trustis a review signal. docsxai plugins list|info|sync: status table (load/disable reasons), manifest introspection, andplugins-lock.jsonsha256 pinning verified before any register module is imported (mismatch fails closed;syncnever executes plugin code).
Engine: ADF export + Confluence publisher
Section titled “Engine: ADF export + Confluence publisher”docsxai export adf+projectDocPackToAdf: pure, deterministic Confluence ADF projection of the doc pack (zero HTTP): one consolidated document with anchored H2 flow sections (defaultsinglemode) 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-stepmediaSinglenodes 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-infetch, capability-declaredegress:*.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 itssection); idempotent via adocsxai-content-shacontent-property: re-publishing an unchanged projection performs zero mutations, and attachment uploads are skipped when the same-name attachment carries a matchingdocsxai-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 realresolvePluginspath.
Engine: execution determinism + redaction
Section titled “Engine: execution determinism + redaction”environmentblock in the flow-file (clockfreeze,locale,timezone,viewportincl.desktop/tablet/mobilepresets,color_scheme,reduced_motion) applied at session creation; per-key child-winsextendsmerge; 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) orpixelate(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
extendstarget, unused locator, terminal step withoutsuccess, un-guardedoptional, selector-lesselement_stable, annotation anchored to a redacted element) + injectableextraRulesfor lint-rule plugins. - Byte-identical determinism keystone: frozen-clock + redacted flow re-run twice asserts identical screenshot bytes against real Chromium.
BrowserDriver.screenshotgained an optionalredactionsparameter (external driver implementers take note).
Engine: workspace + CLI hygiene
Section titled “Engine: workspace + CLI hygiene”resolveWorkspacePath/resolveWorkspacePathReal: the filesystem chokepoint: every workspace artifact read/write routes through containment checks (separator-boundary prefix + realpath symlink-escape defense); typedWorkspacePathEscapeError.- In-process deterministic
docsxai zip(fflate): no systemzipbinary; 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/viewerbin (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).
Engine (@docsxai/engine)
Section titled “Engine (@docsxai/engine)”- Flow-file format: declarative YAML (
prerequisites/locators/steps[]),extends:composition, schema-validated, hand-editable. Actions:navigate/click/fill/upload(file-input via PlaywrightsetInputFiles) /press/hover/select/check/uncheck/wait. - Deterministic runtime:
docsxai runreplays a doc pack headless with zero agent/LLM involvement; byte-identical re-runs (keystone test). optional: truesteps: 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 indocs/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.yamldescriptor +manual-capturestrategy (security-lowered instrumented Chrome, localstorageStatecache, real-cookie-expiry tracking, persistent profile,--cdpattach). - 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_stepsfor pre-login chrome;options.totpRFC-6238 hop with dep-freegenerateTotp/verifyTotp),email-otp(pluggableInboxProviderpolling:http-jsonbuilt-in,code_patternextraction,registerInboxProviderhook),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 viaresolveCreds),registerAuthStrategyplugin hook consulted before the built-ins,expiresAtderived whenever credible (cookie expiry / JWTexp/expires_in), secret values never echoed. - Style artifact:
docsxai styleinit/validate + derived JSON + jargon-leak scanner (semantic-reshape enforcement). - Hand-off:
docsxai zippackages a reviewer-ready archive (excludes operator-local.auth/, halts,.viewer/). - Backend client:
docsxai login/push/pullagainst 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 flowextendsgraph, theme accent/logo from the style artifact'svisualkeys (--title/--accentoverrides). 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 emittedpackage.json;--buildrunsastro buildagainst the workspace-pinned install via per-package symlinks (zero network at build), real-build E2E gated behindDOCSX_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 realresolvePluginspath in tests.
Engine: drift detection + test export
Section titled “Engine: drift detection + test export”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 (withignore_regions), prose line-change counts, locator changes;--format json|md|text(the markdown form is PR-comment-ready) and a--fail-on warn|failCI 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.tsper flow (extends resolved,environmentastest.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-projectwebhook-configCRUD (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:
FsStorebehind the newBackendStoreinterface (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 asdocsxai/screenshots@2sha256 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 pushfinalizes: 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_TOKENbearer path.docsxai login --oauthruns 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/:rolestores client-side AES-256-GCM envelopes (BackendStateCache, key fromDOCSX_CACHE_KEY); the backend never sees plaintext session state. - Run history wired:
docsxai runappends 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 sameplaceCalloutas 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.tsimporting the realplaceCallout; 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>.
Engine: CLI integration
Section titled “Engine: CLI integration”docsxai runapplies the merged flow'senvironmentblock to every launched session;docsxai lintresolves the workspace plugin registry and runs registered lint-rule plugins after the built-ins (plugin failures degrade to core rules with a warning).
Plugin (@docsxai/plugin)
Section titled “Plugin (@docsxai/plugin)”- Claude Code plugin:
calibrate+diagnoseskills;run/render/login/push/pullcommands. - Static bundle validation (
validatePluginBundle) cross-checked against the engine CLI surface.
Viewer (@docsxai/viewer)
Section titled “Viewer (@docsxai/viewer)”- 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:noneuntil:hoverat build time, so an in-place measure bakeswidth:0pxand collapses it to a one-character column); no-cache metas + visible render timestamp.
Backend (@docsxai/backend)
Section titled “Backend (@docsxai/backend)”- Stub service with the concrete REST endpoint list, bearer auth, in-memory linear immutable revisions. (Persistent backing + OAuth interactive flow are post-MVP.)
Skill (@docsxai/skill)
Section titled “Skill (@docsxai/skill)”- Vendorable
.claude/skills/fallback delegating to the installed plugin.
Cross-cutting
Section titled “Cross-cutting”- 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.
Quality + governance baseline
Section titled “Quality + governance baseline”- 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-contextsubtree: 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, expandedCONTRIBUTING.md. - Security best practices for adopters.
- Per-package
tsconfig.build.json(sourceMapanddeclarationMapoff; excludes test files). - Per-package builds clean
dist/+tsconfig.build.tsbuildinfofirst (scripts/clean-dist.mjs), so stale compiled artifacts can never survive a rebuild or leak into a published tarball;scripts/audit-package-contents.mjsnow audits thedocsxaistub tarball too. - Dedicated
packages/docsxai/publishable stub withpublishConfigfor OIDC trusted publishing. - 6-package OIDC publish pipeline in
release.yml. release.ymlgithub-releasejob: creates the GitHub Release for the tag (generated notes) and attaches a CycloneDX SBOM (pinnedcdxgen) once both publish jobs succeed; the scoped-publish filter excludes the repo-only packages (@docsxai/{mcp,plugin-confluence,plugin-starlight,website}) explicitly, matching theirprivate: trueflags.
Docs site (@docsxai/website)
Section titled “Docs site (@docsxai/website)”- 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.mjsgenerates 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.mjsbans em/en dashes and stock AI-voice tells from every published page. Netlify deploy config + rootdocs:dev/docs:build/docs:previewproxies. 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 inllms.txt's new## Guidancesection, 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.
Changed
Section titled “Changed”caption_styledefaults toautoat every width. A themed burn usedfullfor 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; setcaption_style: fullto keep the old behaviour. An explicitfullorbadgestill wins, and a burn with no theme is unchanged.scripts/burn-trackxai.mjsandscripts/burn-probe-batch.mjsno longer pick the style by width.- Project-wide rename to
docsxai: a single pre-publish clean break (no compatibility aliases): CLIsite-docs→docsxai; npm packages@kalebtec/docsxai-*→@docsxai/*on the registered@docsxaiorg; env varsSITE_DOCS_*→DOCSX_*; workspace config.site-docs.json→.docsxai.json; schema idssite-docs/<thing>@N→docsxai/<thing>@N; API version headerSite-Docs-API-Version→Docsxai-Api-Version; page helperwindow.__siteDocs→window.__docsxai; Claude Code plugin manifest + slash commands/site-docs:*→/docsxai:*. The plugin runtime keepssite-docsinRESERVED_NAMESPACESdefensively. - Renamed workspace packages
@kalebtec/site-docs-*→@kalebtec/docsxai-*(engine, backend, plugin, skill, viewer); workspace rootsite-docs-monorepo→docsxai-monorepo. - CLI bin names
site-docs-backend→docsxai-backend, etc. - 5 scoped workspace packages flipped from
private: trueto 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.mdanddocs/running-against-an-app-repo.mdto use the current viewer / backend bin names (docsxai-viewer,docsxai-backend) after the rename fromsite-docs-*. - Refreshed
packages/plugin/README.md:push/pullcommands shipped, dropped from the TODO row;style-learn/translateremoved 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 libsandPackage formatting scriptssections todocs/ai-context/agent-process/code-quality.md, codifying the per-packagetsconfig.json(dev / typecheck) +tsconfig.build.json(emit, excludes tests) split and the root-cwdpnpm format/format:checkconvention.
- CLI browser-install hints name the
playwright-corecommands 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 unpinnednpx playwright install chromium. - The missing-flows error now names the workspace, the expected
flows/path, and thedocsxai init/docsxai calibratenext steps instead of the bareno flows directory at <path>. - The website build no longer logs a
/404route conflict on every run: the branded 404 moved from the docs collection to a file-basedsrc/pages/404.astro(still Starlight-framed via<StarlightPage>), Starlight's injected 404 route is disabled, and the page now emits as404.html, the file Netlify serves for unmatched paths (the collection entry built to404/index.html, which Netlify ignores). - CI build-step ordering (added
pnpm -r buildbeforepnpm -r testso engine's workspace-package resolution works). - 22-day red CI on
maincleared 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-arrowviolation inpackages/engine/src/playwright-instrumented-browser.ts, converted to function expression +PageEvaltype wrapper.
Removed
Section titled “Removed”- Empty
examples/stub directory (real keystone fixtures live atpackages/engine/test/fixtures/toy-site/). - Workspace-root publishable stub (replaced by dedicated
packages/docsxai/sub-package).
Security
Section titled “Security”- 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 spoofablegithub.actor). - All third-party GitHub Actions SHA-pinned with version comments.
release.ymluses OIDC trusted publishing (noNPM_TOKEN); environment-gated; tag-triggered only.