# Combined Server-Surface Census — TextForAgents LLC

One snapshot that pins endpoint identity, tool contract, and skill digests together, under one signature — and composed successor verdicts that separate a tool change from a skill change.

## Start (self-serve, no operator step)
1. POST /register {"operator": "your-name"} -> {"account_id", "token"} — keep the token; it is your per-customer credential and the ONLY billing/data identity (identity fields in request bodies are ignored for scoping). Identity is canonicalised (NFKC, casefolded, format characters stripped, whitespace collapsed): registering again under a case/whitespace/unicode variant returns the same account and does NOT re-grant the trial.
2. Trial: ONE free verdict query per operator, ever. Your first /verdict call burns it; after that the standard $0.01/call x402 price applies. No perpetual free tier.
3. POST /snapshot {"url": "<endpoint>", "registry_name": optional, "mode": "pin"|"verify"} — a one-time combined snapshot, $1.99 via x402. Pin mode (manifest-only, the census default) pins manifest digests as served. Verify mode fetches the real file bytes and digests them itself before a skill enters the verified set; a file served without real bytes is UNVERIFIABLE (no_real_bytes), never verified on the server's say-so. The snapshot is stored under your account and returned signed (HMAC over the unified field set; the snapshot records the key era it was signed under — verify at POST /snapshots/verify, accepted key fingerprints at GET /verify-key). GET /snapshots lists your snapshots; GET /snapshot?id=<id> returns one of yours.
4. POST /verdict — the composed verdict query, $0.01/call (first one free): {"old_snapshot": {...}, "new_url": "<endpoint>", "mode": ...} probes the new address and diffs; {"old_url": ..., "new_url": ...} uses your latest stored snapshots where present (probing the new address when no stored snapshot exists); {"old_snapshot": {...}, "new_snapshot": {...}} diffs two supplied signed snapshots (both signatures verified first — a mutated field or a forged/missing signature is rejected). Verdicts: MOVED-LIVE-SAME-SURFACE, MOVED-TOOL-SAME-SKILL-CHANGED, MOVED-SKILL-SAME-TOOL-CHANGED, MOVED-BOTH-CHANGED, MOVED-DEAD, and the downgrade MOVED-LIVE-SAME-PINNED-UNVERIFIABLE-PRESENT when either side carries dynamic/no-manifest skills — a surface carrying dynamic/no-manifest skills on either side is never blessed plain SAME-SURFACE.
5. Surface watch: POST /subscribe {"tier": "watch", "endpoint": "<url>"} with an x402 X-PAYMENT header of $4.99 activates a 30-day watch entitlement for that endpoint; then POST /watch {"url": ..., "successor": optional}. GET /watches lists your watches and alerts. Watches are checked at cadence at most hourly (or POST /watch/check to check now); an alert fires on a status or surface change, with the successor verdict attached when a successor is registered. No dedicated high-cadence flat tier is offered at any price.
6. GET /stats — the public census aggregate: snapshot volume by depth (pin / verify), verdict volume by composed verdict (including the UNVERIFIABLE-PRESENT downgrade share), endpoint classification mix (LIVE / AUTH_GATED / DEAD), and the measured skill-serving share among live endpoints.
7. MCP: POST /mcp (JSON-RPC) — tools combined_verdict, take_snapshot, list_snapshots, add_watch, list_watches — same account token and billing (an X-PAYMENT header on the /mcp request pays for that call).
8. Receipts: paid and trial verdict/snapshot/subscribe responses carry an HMAC-signed receipt (verify at POST /receipts/verify).

## Classification and limits
LIVE = initialize + tools/list answered. AUTH_GATED = HTTP 401/403 on the probe — classified, never probed with credentials the operator did not supply for that endpoint. DEAD = connection failure or other HTTP error. A failing or HTTP-500 skills/list classifies as skills_error on a LIVE snapshot, never crashes the pass. Private / loopback / link-local / reserved targets are refused (REFUSED_PRIVATE) before any charge, and redirects to private targets are refused. Request bodies capped at 64 KB. Pin mode trusts manifest digests as served. Support: support@textforagents.com.

## Prices
Combined verdict query $0.01/call (x402) · Surface watch $4.99/endpoint/mo · One-time combined snapshot $1.99. One free verdict query per operator, ever. No perpetual free tier.