Quickstart

This page takes you from nothing to a rendered doc pack against your own app. It assumes docsxai is on your PATH (Installation) and your app is running somewhere reachable, say https://localhost:3000.

1. Scaffold a workspace

A workspace holds everything docsxai produces. Put it outside the app’s source repo - docsxai documents a running app from the outside and never writes into the app’s checkout:

docsxai init ~/docsxai/my-app --app-url https://localhost:3000 --auth manual-capture --ttl 1h

This creates flows/, docs/, auth/strategy.yaml, .auth/, .viewer/, and a .docsxai.json config holding app_url, so later commands need no flags. Add --ignore-https-errors if the app runs on a self-signed dev cert.

2. Capture an authed session (skip if the app has no login)

docsxai capture-auth ~/docsxai/my-app

An instrumented Chrome opens. Log in the way you normally would - SSO, MFA, whatever - then run window.__docsxai.capture() in the devtools console. The session is cached to .auth/<role>.json and capture-auth prints the captured cookie jar. Pin the app’s real session cookie so the cache tracks its true expiry: docsxai capture-auth ~/docsxai/my-app --auth-cookie session. The full auth story, including ten scripted strategies for unattended CI re-auth, is in Auth strategies.

3. Author a first flow

A flow-file is YAML: named locators, ordered steps, optional waits and success checks. Write ~/docsxai/my-app/flows/open-reports.flow.yaml:

name: open-reports
locators:
  nav_reports: '[data-testid="nav-reports"]'
  report_table: '[data-testid="report-table"]'
steps:
  - id: open-app
    action: navigate
    value: /dashboard
    wait_for: load
  - id: open-reports
    action: click
    target: $nav_reports
    wait_for: { selector: $report_table }
    success: { visible: $report_table }
    annotation: { copy: "Open Reports to see this month's numbers", arrow: top-right }

To find good locators on the live, authed page, use docsxai inspect ~/docsxai/my-app - it loads the cached session and prints the page’s [data-testid] elements. To author with an agent instead of by hand, follow the agent runbook. Before running, catch authoring mistakes statically:

docsxai lint ~/docsxai/my-app

4. Run it

docsxai run ~/docsxai/my-app --flow open-reports

Headless Chromium loads the cached session, replays the steps, and writes docs/open-reports/annotations.json plus a clean screenshot per annotated step. No agent, no LLM calls; the run halts with a [cause: ...] prefix if a locator or success check fails (Troubleshooting). While iterating on a single step, run --flow open-reports --stop-after open-app --pause keeps the headed browser open mid-flow.

5. Render and open the viewer

docsxai render ~/docsxai/my-app
open ~/docsxai/my-app/.viewer/index.html

The viewer index links each flow; every flow page shows the screenshots with pulsing halos - hover one to read its callout.

Where to next

• Agent runbook - hand calibration to a coding agent end to end.
• CI recipes - refresh the pack in your pipeline, gate on drift with baseline + diff.
• Flow-file format - every field, including extends, environment, and redactions.
• The doc pack - what just landed in your workspace.