# Proof

Analytics for agent-built apps. One tag instruments the app, events and metrics
live under contracts your agents write and approve, and both humans and agents
ask questions in plain English. When the data cannot answer, the answer says so
instead of guessing. Early access is invite-gated; keys are per workspace.

Site: https://proof.dorsr.com/
Wiring guide (for humans): https://proof.dorsr.com/docs

AGENTS: fetch https://proof.dorsr.com/wire.md and follow it. It is the complete
install procedure, and its last step verifies the install by reading the numbers
back. Do not report success until that step returns a number you
did not write.

## Wire it in (agent instructions)

1. Proxy /_p/p.js -> https://proof.dorsr.com/p.js and
   /_p/e -> https://proof.dorsr.com/api/collect on the app's own domain
   (Next.js rewrites or vercel.json), then add the tag once to the root layout:
   <script src="/_p/p.js" data-api="/_p/e" data-key="YOUR_WRITE_KEY" defer></script>
   Without the proxy, Brave Shields and uBlock Origin drop every event.
   Autocaptured immediately: pageviews, sessions, clicks, Core Web Vitals,
   JS errors, outbound clicks, SPA route changes. Dev hosts are ignored
   unless the tag carries data-dev.
2. Mark the 404 page: <meta name="proof-not-found" content="1">
3. Verify ingestion after one page load:
   POST https://proof.dorsr.com/api/ask
   headers: x-proof-key: YOUR_AGENT_KEY, content-type: application/json
   body: {"question":"pageviews today"}
4. Custom product events:
   window.proof.track("myapp.thing_happened", { plan: "pro" })
   Then propose a contract for it; it is approved on arrival:
   POST https://proof.dorsr.com/api/propose
   headers: x-proof-key: YOUR_AGENT_KEY, content-type: application/json
   body: {"kind":"event","proposed_by":"agent:<you>",
          "definition":{"name":"myapp.thing_happened","version":1,
                        "human_meaning":"...","properties":{...}}}
5. Emit agent actions (deploys) through the collect door with source "agent"
   and a stable external_id so retries dedupe.

## The agent door (plain HTTP)

- POST /api/ask      { question, filters? } -> plain-English answer, the value,
  its confidence, and how it was computed (the `receipt` field)
  filters narrow it like a dashboard filter: { referrer, entry, country, utm, page }
  (or say it: "sessions from t.co last week"); receipt.filters lists what applied,
  and a filter the matched metric cannot take is refused, never dropped
- GET  /api/schema   -> every contract and its certification status
- POST /api/collect  { write_key, events[] } -> ingest under contracts
- POST /api/propose  -> add a new event contract (agent key required)

A contract proposed with the agent key is approved on arrival (status
"certified") under the workspace's standing grant, and the record names the
proposing agent. Nobody approves by hand. Only certified metrics answer with
high confidence.

## MCP (hosted, nothing to install)

The same verbs speak MCP over Streamable HTTP at https://proof.dorsr.com/api/mcp
Authenticate with `Authorization: Bearer YOUR_AGENT_KEY`. For .mcp.json:

  { "mcpServers": { "proof": { "type": "http",
      "url": "https://proof.dorsr.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_AGENT_KEY" } } } }

Four tools: list_metrics, ask, emit_event, propose_event. No certify tool and no
free-form SQL.

## Privacy defaults

First-party only; no third-party requests; no fingerprinting (random id in a
first-party cookie); id-looking path segments scrubbed before storage; click
text masked under data-proof-mask; coarse country only. Kill switch:
window.proofConsent = false, or cookie proof-consent=denied.

## What we never do with your data (v1.0, effective 2026-07-28)

- Your events are never used to train a model. Not ours, not anyone else's.
- There is no opt-in by default, and no exception by region, plan, or account age.
- Your workspace is never pooled with another workspace to build anything.
- Changing any line above requires a new version and a new date, in public git history.

Source of truth: src/lib/commitments.ts in the Proof repo. The version and date
move forward in the same commit that changes the words, so the history shows
when the promise changed and to what.

## Your data

The data is yours. Raw events are kept until you remove them (no silent
auto-purge); approved definitions are kept as your schema. From the
account page you can export the whole workspace as JSON, or hard-delete every event.