Skip to content
docsxai

Deterministic screenshot docs

Deterministic screenshot docs

docsxai

Write a flow once. Replay it forever. docsxai walks your running web app, follows written flows, and emits screenshot-rich user docs that re-render byte-identically in CI - no agent in the execution path.

Get startedQuickstart
pnpm add -g docsxai@next

Installs 0.3.0-rc.3, the current prerelease. latest is still 0.2.0. Install steps

What it makes

A screen of trackxai, a Kalebtec app, as docsxai run captured it and as a themed burn draws it, then what a run prints.

The same screenshot of the trackxai Progress page twice. The copy labelled raw is the plain capture. The copy labelled burned adds violet halos and numbered badges and, on wider screens, three callouts joined to their targets by thin lines: the bar splits every task by phase, open tasks group by epic, and a question waiting on you shows up in the task's timeline.The same screenshot of the trackxai Progress page twice. The copy labelled raw is the plain capture. The copy labelled burned adds violet halos and numbered badges and, on wider screens, three callouts joined to their targets by thin lines: the bar splits every task by phase, open tasks group by epic, and a question waiting on you shows up in the task's timeline.

The same capture, raw and burned with a caption theme. Caption themes are on the main branch, not in 0.3.0-rc.3.

A terminal window titled docsxai run, composed from the engine's real output format and the real trackxai flow counts, not a recorded session. The command docsxai run workspace replays the screens flow in eight variants: en-US and es-ES, light and dark, desktop 1280 and mobile 390. Each variant reports 61 or 53 steps and 29 or 18 annotations. The last lines say 8 of 8 flow variants ok, with outputs in workspace/docs. On phones the lines are shortened to one per variant.A terminal window titled docsxai run, composed from the engine's real output format and the real trackxai flow counts, not a recorded session. The command docsxai run workspace replays the screens flow in eight variants: en-US and es-ES, light and dark, desktop 1280 and mobile 390. Each variant reports 61 or 53 steps and 29 or 18 annotations. The last lines say 8 of 8 flow variants ok, with outputs in workspace/docs. On phones the lines are shortened to one per variant.

One flow file with a matrix, replayed in eight variants with no agent in the loop. Output as docsxai run prints it, counts from the trackxai flow.

Why it exists

Screenshot docs rot the moment the UI moves. docsxai treats them as a build artifact: a written flow is the source, the rendered doc pack is the output, and a re-run is the refresh.

// execution

Deterministic CI replay

A frozen clock and a pinned locale, timezone, and viewport: the same flow against the same target state produces byte-identical screenshots. run —verify-determinism runs a flow two to five times and names the first artifact that differs, and diff —fail-on warn gates CI on drift against a committed baseline.

// variants

One flow, many variants

A matrix block expands a flow file into one run per locale, color scheme, and viewport, up to 64 combinations. pack builds the screenshot pack from them and pack —check compares it with the committed one.

// calibration

Agent calibration, any MCP host

An agent authors the flow-file once, through the Claude Code plugin or the standalone MCP server, with lint, diagnose, and actionability probes at write-time. After that, every run is agent-free: no model in the loop, no token bill per refresh.

// output

One doc pack, three deliveries

An interactive viewer with halos and callouts, an Astro Starlight site, or burned captions in plain PNGs for places that cannot run the viewer. Redactions mask sensitive UI before any pixel hits disk. The text the viewer and the site add comes in English or Spanish, set with —lang.

// captions

Themeable burned captions

The halo, numbered badge, callout, and connector follow a burn.theme block: four presets (clean, soft, high-contrast, readable), an optional design-tokens file, and per-key overrides. The interactive viewer reads the same theme. The readable preset scales captions with the screenshot, and display_width takes a second width for narrow captures, so a phone capture and a desktop capture both read at 15 px. A themed burn joins each caption to its target with a 2 px line and can fall back to a numbered badge where no clear spot exists. Caption themes are on the main branch. Read the burn theming guide

// plugins

Publishers and renderers as plugins

Publishers, renderers, lint rules, and auth strategies extend the engine through a namespaced, capability-declared, sha256-locked runtime. First-party publishers cover Confluence, GitBook, Guru, Notion, and SharePoint. SharePoint is on npm as an experimental package since 0.3.0-rc.3. The others are repo-only for now.

Install

Node 26 or newer. The 0.3 prerelease is on the next tag, and latest is still 0.2.0.

// cli

The docsxai CLI

pnpm add -g docsxai@next
npx playwright-core install chromium
docsxai doctor

docsxai@next is 0.3.0-rc.3 today. Without a tag you get 0.2.0, which has no burn, pack, or matrix flows. With pnpm, run pnpm setup once first, or use npm install -g docsxai@next.

// claude code

The Claude Code plugin

/plugin marketplace add kalebteccom/docsxai
/plugin install docsxai@docsxai

Optional. Adds the calibration skills and the /docsxai:* commands. The CLI works without it.

Installation details

First run

Five steps, about ten minutes, against an app running on your machine. Each step shows a line you should see.

  1. // step 1

    Make a workspace

    docsxai init my-docs --app-url http://localhost:3000 --auth none

    Creates the folder docsxai writes into and saves your app’s address in my-docs/.docsxai.json. Keep it outside your app’s repo. If the app needs a login, leave out —auth none and run docsxai capture-auth my-docs before step 3.

    Expectcreated: flows/, docs/, auth/, .auth/, .viewer/, .gitignore, .docsxai.json, flows/example.flow.yaml.sample, README.md

  2. // step 2

    Check the setup

    docsxai doctor my-docs

    Checks Node, Chromium, the config, write access and app_url. A failing line names its fix after next:.

    Expectok: config: .docsxai.json fields are valid

  3. // step 3

    Calibrate with an agent

    /plugin marketplace add kalebteccom/docsxai
/plugin install docsxai@docsxai

    With the plugin installed and your app running, ask Claude Code in plain words, for example “calibrate my-docs: open the Reports page and show the export button”. It writes the flow into my-docs/flows once, and every run after that needs no agent.

    Expectnext: docsxai run my-docs (then: docsxai render my-docs)

  4. // step 4

    Run it

    docsxai run my-docs

    Replays the flow in headless Chromium and writes annotations and screenshots under my-docs/docs.

    Expectrun: 1 of 1 flow ok, outputs in my-docs/docs

  5. // step 5

    Open the docs

    docsxai render my-docs

    Builds the interactive viewer into my-docs/.viewer and prints the page to open in your browser. Hover, tap or tab to a halo to read its callout.

    Expectrender: open /path/to/my-docs/.viewer/index.html

Next: the quickstart

Run your first flow

Read the flow-file format

Made by Kalebtec·GitHub·Apache-2.0 licensed