docs: add the public repository README

[selezenart]

Summary

Adds the root README.md. The repository had none.

plan.md section 5b lists it as an Arc qualification artifact — the row
"Architecture diagram | Diagrams exported from this plan into the public
repository README" — and the Gate P6 checklist verifies it exists. So this is a
submission requirement, not just polish.

Written for someone arriving at the public repository, not for the team. It
opens with the concrete failure OneShot prevents (an agent that cannot tell a
lost response from a lost payment), then the architecture, the invariants, and
how to run it. The delivery plan stays in plan.md and milestones/, linked
rather than duplicated.

Scope and acceptance criteria

• The change is limited to the stated milestone or issue.
• Acceptance criteria are listed and satisfied.
• No unrelated cleanup is included.

One new file. Nothing else touched.

• Architecture diagram and durable state machine as Mermaid, rendered by the
  Markdown and Mermaid CI job.
• Solid edges mark implemented components, dashed mark planned, so the
  diagram cannot be read as claiming the Subgraph MCP adapter and recovery
  agent exist. They do not.
• State machine matches the durable transitions in milestones/CONTRACTS.md
  section 6.

Product and security invariants

• Tenant isolation remains fail-closed.
• Sponsor authorization, auditability, and daily caps remain enforced where applicable.
• Recipients cannot modify sponsor controls or access sponsor-only data.
• No secret, token, production identifier, or personal data is committed.
• Any non-applicable invariant is explained below.

Invariant notes:

Documentation only; no code, schema, or configuration changes, so the isolation
and sponsor-control rows are not applicable.

The invariant that does apply here is the sponsor-qualification rule: no claim
may rest on fixtures alone. A public README is exactly where such a claim would
do damage, so the status section states plainly that no live settlement has
been executed, that no Privy application, wallet, policy, or funded account
has been provisioned, that the adapters are proven against simulators and
therefore demonstrate the logic and not the providers' behaviour, and that the
Privy and Arc integrations are NOT VERIFIED. It does not contradict
docs/settlement/LIVE_EVIDENCE.md.

It also records that Arc Mainnet is unconfigured and its profile deliberately
carries no chain ID, RPC, explorer, or token value.

Validation

Every documented command, path, and endpoint was run or checked before being
listed:

markdownlint-cli2       : PASS (84 files, 0 errors)
prettier --check        : PASS
eslint .                : PASS
mermaid-cli 11.17.0     : PASS, both diagrams render
arc-adapter probe       : runs, fails closed naming the missing variable

Checking the routes actually registered in apps/api/src/app.ts turned up the
recovery-view and metrics endpoints missing from my first draft; the API
table now matches the code.

Independent review evidence

Gate A — exact candidate tree before push

• Reviewed target: feature/root-readme @ b6e4609
• Reviewer tool: free-pi-cli 0.2.19
• Reviewer model: glm-5.3-flash
• Verdict: PASS (README_PASS)
• Blocking findings: None

The reviewer was asked to judge it hard on accuracy, and specifically to verify
against the repository that the endpoints match the registered routes, the
layout matches the packages that exist, the quick-start commands match the root
scripts and declared Node/pnpm versions, the probe script exists as documented,
the solid-versus-dashed claim is truthful, the state machine matches
CONTRACTS.md section 6, and the status section makes no sponsor claim resting
on fixtures.

Evidence caveat: the literal VERDICT: line was lost to terminal viewport
truncation. Captured evidence is REVIEWED_TARGET: feature/root-readme @ b6e4609, an empty blocking-findings section, and the terminal README_PASS
token.

Risk and rollback

• The README describes a moving project. The status table and the
  solid-vs-dashed diagram will need updating as the recovery agent and frontend
  land, and as live evidence replaces LIVE_NOT_RUN.
• plan.md assigns the README to lane A. It is written here because lane B is
  parked waiting on Gate P4, and it is a submission requirement that was
  missing.

Rollback: delete the file. Nothing references it.

Human merge

• A human owner has reviewed the evidence and will perform the merge.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	oneshot	b6e4609	Sep 07 2026, 10:22 PM