Skip to content
UxerProof

Documentation

Everything you need to compose and read a Circuit

Written against the current product. Anything that depends on the execution service is marked.

Execution service not connected. Circuit runs shown here are fictional demo data. The isolated browser workers, queues and AI provider integration are added in the next engineering phase. Nothing on this screen was produced by executing a real website.

Terminology

Circuit
A complete test.
AI User
A simulated participant that performs the journey.
Persona
The behaviour definition an AI User follows.
Project
A website or application under test.
Environment
A target deployment of a Project.
Run
An individual execution of a Circuit.
Finding
A discovered problem.
Baseline
An approved comparison state.
Evidence
A supporting artefact captured during a Run.
Proof Score
The overall, fully decomposed result of a Run.

Circuit modes

  • Public Circuit — Unauthenticated journeys across pages anyone can reach.
  • Authenticated Circuit (planned) — Journeys behind sign-in using short-lived, scoped credentials.
  • Role Circuit (planned) — Multi-role journeys that hand off between requester, reviewer and approver.
  • Mobile Circuit (planned) — The same journey replayed at mobile viewports and input modes.
  • Accessibility Circuit (planned) — Keyboard-only, focus order, contrast and semantics checks along the journey.
  • Regression Circuit (planned) — A Circuit replayed against an approved Baseline to detect drift.

Domain verification

Every Environment must prove control of its domain before it can be executed against. Choose one method:

  1. DNS TXT record

    Add a TXT record at _uxerproof.yourdomain.com containing the token shown in the Environment. Recommended for production.

    _uxerproof.shop.example.com. IN TXT "uxp-verify=8f2c…"

  2. Meta tag

    Add the meta tag to the document head of the Environment's root URL.

    <meta name="uxerproof-verification" content="uxp-verify=8f2c…" />

  3. Well-known file

    Serve the token at /.well-known/uxerproof-verification.txt. Useful for preview deployments.

Verification is re-checked periodically. If the record disappears, execution against that Environment is suspended until it is restored.

Composing a Circuit

A Circuit is an ordered list of steps against one Environment, performed by one or more AI Users. Each step declares a kind, an intent and an expectation. Write expectations as outcomes a person could verify, not as selectors.

  • navigate — arrive somewhere.
  • input — provide information.
  • decision — choose between paths.
  • action — commit to something.
  • verify — check what the system says.
  • handoff — pass the journey to another role.

Reading a report

A report contains the Circuit Canvas, the Evidence Timeline, the Findings and the Proof Score. The score decomposes into five dimensions:

  • Completion — Did the AI User reach the intended outcome of the journey?
  • Friction — How much hesitation, backtracking and repeated effort occurred?
  • Clarity — Were labels, states and system responses understandable in context?
  • Accessibility — Keyboard reachability, focus order, naming and contrast along the path.
  • Consistency — Did patterns behave the same way across steps and roles?

See the sample report for a worked example.

Retention

  • Standard retention

    Structured reports, findings and baselines are kept for your plan's retention window. Raw execution artefacts are deleted within 24 hours of report generation.

  • Ephemeral Mode

    Raw screenshots, traces and execution artefacts are deleted immediately after report synthesis. Structured reports and baselines are retained only when you explicitly choose to retain them.

  • No report retention

    You export the report and all run data is scheduled for deletion. Nothing is kept beyond the usage ledger and audit record.

Credits

1 Circuit credit = one normal Circuit run of up to five minutes of execution time. This is a configurable commercial assumption and will be recalibrated once real infrastructure costs are measured. Runs that fail because of platform infrastructure are restored automatically once billing is implemented; a restoration appears in the usage ledger with its own entry type.

API (planned)

A workspace-scoped API for triggering Regression Circuits from CI, and a webhook for run completion, are planned for the engineering phase. Neither endpoint exists yet; this section will be replaced with the real contract when it ships.

POST /v1/circuits/{circuit_id}/runs      # planned
GET  /v1/runs/{run_id}                   # planned
POST /v1/webhooks/run.completed          # planned