@clearproof/content 0.5.0

package/content/topics/quickstart.md

@@ -0,0 +1,77 @@
+---
+title: Quick Start
+category: getting-started
+order: 1
+cli-topic: quickstart
+---
+
+# Quick Start
+
+This is a development setup guide, checked September 25, 2026. Use synthetic data and testnet funds. There is no guaranteed setup or proving time.
+
+## Public package access
+
+The [main source repository](https://github.com/repfigit/clearproof) is public. Public npm packages are available at version 0.3.0:
+
+```bash
+npm install @clearproof/proof@0.3.0
+```
+
+Proof generation requires compatible circuit WASM and proving-key files. Verification requires the matching verification key. Inspect package contents before relying on exported artifact paths; installing the SDK alone does not create a complete proving environment.
+
+The 0.3.0 packages predate the pilot and cover the legacy 16-signal profile only. The source checkout (0.4.0, unpublished) contains the pilot. Do not assume they are the same.
+
+The published CLI currently cannot be installed from the public registry because its `@clearproof/content` dependency is unavailable. The standalone proof SDK installation was verified. Use a source checkout for CLI evaluation. The source setup below was verified from a clean clone of `main` on September 15, 2026 at commit `1c8d385` (locked workspace install, workspace build, built-CLI `--help`, Python sync and the Python unit suite); it covers the documented commands, not the circuit compilation path shown later, which additionally requires circom and Powers of Tau inputs.
+
+## Source setup for the unreleased pilot
+
+Prerequisites: Git, Python 3.11+ with uv (the locked install uses 3.12), Node.js 20+ with npm, Circom 2.2.2 and PostgreSQL 18 for the pilot acceptance run.
+
+```bash
+git clone --branch main https://github.com/repfigit/clearproof.git
+cd clearproof
+npm exec --yes --package=npm@11.9.0 -- npm ci
+uv sync --frozen --extra dev --python 3.12
+npm run build
+node packages/cli/dist/index.js --help
+```
+
+To generate development artifacts for both proof profiles and run the pilot end to end, follow the [local acceptance guide](https://github.com/repfigit/clearproof/blob/main/docs/operations/local-pilot-acceptance.md):
+
+```bash
+curl --fail -L -o /absolute/ppot_0080_17.ptau \
+  https://pse-trusted-setup-ppot.s3.eu-central-1.amazonaws.com/pot28_0080/ppot_0080_17.ptau
+.venv/bin/python scripts/test_development_circuits.py /absolute/new-development-artifacts \
+  --prepared-ptau /absolute/ppot_0080_17.ptau
+.venv/bin/python scripts/test_pilot_local.py /absolute/new-development-artifacts/pilot \
+  /absolute/new-pilot-run --postgres-bin /usr/lib/postgresql/18/bin
+```
+
+Check the file's SHA-256 against the one pinned in the guide before using it. Locally generated development keys are not production keys. `bash scripts/compile_circuits.sh` still builds the legacy profile on its own.
+
+## API exploration
+
+For a disposable local evaluation:
+
+```bash
+export AUTH_MODE=api-key
+export API_KEY="$(openssl rand -hex 32)"
+export PII_MASTER_KEY="$(openssl rand -hex 32)"
+uv run uvicorn src.api.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+Open [the local OpenAPI UI](http://localhost:8000/docs). Protected requests use `X-API-Key` in this mode. Keep keys stable and protected for any evaluation whose encrypted records need to survive restart.
+
+Starting the server does not establish a working proof workflow. The pilot routes need PostgreSQL, storage keys, tenant trust configuration and compatible artifacts; `/health` reports process liveness only. Do not treat synthetic output as a live transfer authorization.
+
+## Checks
+
+```bash
+make test
+npm run test:ts
+npm run build
+```
+
+At this checkout, root `npm test` runs Python tests; `npm run test:ts` runs the TypeScript workspaces. Database integration tests need an isolated PostgreSQL instance. Real circuit checks have additional artifact/toolchain requirements.
+
+See [project status](/docs/status) before planning an integration.

package/content/topics/sdk.md

@@ -0,0 +1,56 @@
+---
+title: TypeScript SDK
+category: reference
+order: 6
+cli-topic: sdk
+---
+
+# TypeScript SDK
+
+`@clearproof/proof` provides proof generation, cryptographic verification and counterparty discovery. Published version: **0.3.0**, checked September 25, 2026. That release predates the pilot: it covers the legacy 16-signal profile only. The pilot functions described below exist in the source checkout (0.4.0, unpublished). Confirm the installed version before using its types.
+
+## Installation
+
+```bash
+npm install @clearproof/proof@0.3.0
+```
+
+## Legacy proof API (in the published 0.3.0 package)
+
+```typescript
+import { generateProof, verifyProof, type ComplianceInput } from '@clearproof/proof';
+
+// Supply a complete, authenticated input with witnesses matching your circuit.
+async function evaluate(input: ComplianceInput, wasm: string, zkey: string, vkey: string) {
+  const generated = await generateProof(input, wasm, zkey);
+  const verified = await verifyProof(generated.proof, generated.publicSignals, vkey);
+  return { generated, verified };
+}
+```
+
+The caller supplies compatible artifacts. The SDK maps camelCase fields to Circom signal names; it does not create issuer or sanctions witnesses for you. Field encodings, amount units and public-signal ordering must match the exact proof version.
+
+`verified.valid` describes cryptographic verification. `isCompliant` and `sarReviewFlag` interpret circuit outputs; they do not establish full registry acceptance, current policy authorization or legal compliance. Additional trust, freshness, revocation, domain and replay checks remain necessary.
+
+## Pilot functions (source checkout)
+
+| Function | Purpose |
+| --- | --- |
+| `inspectCurrentProof` | Read-only inspection of a `pilot-transfer-v3` proof through the authenticated API |
+| `authorizeCurrentProof` | Request consumption of one authorization; returns the receipt |
+| `createObservation`, `readObservation`, `listObservations`, `reportObservationCohort` | Non-authorizing observations and cohort reports |
+| `requestReport`, `reportEndpoint` | Authenticated report requests |
+| `canonicalBytes`, `recordDigest` | Canonical encoding and domain-separated digests, matching the Python implementation |
+| `walletOwnershipSigningMessage` | Build the exact EIP-191 message for the wallet ownership challenge |
+
+These use server-selected trust: the API owns current roots, policy and consumption. The client validates response shape and profile (`pilot-transfer-v3`) but does not independently establish current state.
+
+## Discovery
+
+`discoverVASP(domain)` and `supportsChain(domain, chainId)` read self-declared well-known metadata. A domain response is not independent issuer/VASP authorization. Python and TypeScript discovery compatibility and destination/key validation are active hardening work.
+
+## Input and privacy limitations
+
+The current SDK validates selected fields, including proof expiry relative to the transfer timestamp and a nonzero credential nullifier. A zero domain chain ID currently emits a warning; it is not a safe production configuration.
+
+Do not log complete witnesses or sensitive proof metadata. Use the installed package's declarations for exact types and dependencies, and review [status](/docs/status) before integration.

package/content/topics/security.md

@@ -0,0 +1,33 @@
+---
+title: Security
+category: operations
+order: 7
+cli-topic: security
+---
+
+# Security and assurance
+
+Last reviewed: September 25, 2026.
+
+clearproof is **pre-production, pilot-stage software**. Independent circuit and contract audits have not been completed. Current proving artifacts use a development-only trusted setup. Testnet deployment and passing tests do not establish production safety.
+
+## Current boundaries
+
+- A cryptographically valid proof is not an accepted transfer. In the pilot, the authorization service checks current roots, revocation, policy and signed facts before consuming an authorization in PostgreSQL. Pairing alone checks none of these.
+- Credential, holder, jurisdiction and transfer binding are enforced by the `pilot-transfer-v3` statement and the authorization service, tested locally. They rely on trusted issuers, root publishers and a trusted registry publisher; the contract cannot detect a publisher that lies about private records.
+- Recipient HPKE envelopes are the default; the legacy shared-key AES-256-GCM mode is only used when an operator selects it. Key rotation and altered-envelope rejection are tested locally. Live key discovery between institutions is not yet validated.
+- Current proofs publish eight values (commitments, roots, a nullifier, times and the chain and registry binding) but no amount, tier, jurisdiction or review flag. Those values can still be correlated with other records. The legacy 16-signal demo profile publishes more, including a review flag.
+- Domain, expiry, root and replay checks depend on correct configuration of the authorization service and registry. The site does not claim that replay is universally impossible.
+- Tenant-scoped encrypted storage, restart recovery and retry isolation are tested locally with PostgreSQL. They have not been independently reviewed.
+
+## Controls to evaluate
+
+Use synthetic records and testnet funds. Check approved issuer/root/artifact provenance, recipient identity, key purpose, freshness, revocation, transfer binding and duplicate handling. Confirm that sensitive inputs remain inside authorized encrypted data flows and do not appear in logs or exports.
+
+`PII_MASTER_KEY` startup validation checks accepted encoding and minimum length. It cannot establish that a supplied value has adequate randomness. Generate secrets securely and manage retention, backup and rotation deliberately.
+
+## Vulnerability reporting
+
+The repository security policy lists **security@clearproof.dev** as its reporting address. Share reproduction steps and impact privately; do not post sensitive exploit details or personal information in a public issue. This documentation does not verify mailbox operation or promise a response-time SLA.
+
+No active paid bug-bounty program is announced here. See [project status](/docs/status) for the implementation and assurance work that remains.

package/content/topics/troubleshooting.md

@@ -0,0 +1,109 @@
+---
+title: Troubleshooting
+category: operations
+order: 8
+cli-topic: troubleshooting
+---
+
+# Troubleshooting
+
+Common issues and fixes for clearproof development and deployment.
+
+## Circuit compilation fails
+
+**Symptom:** `bash scripts/compile_circuits.sh` exits with a circom error.
+
+**Fix:** Ensure circom 2.2.2+ is installed and on your PATH:
+
+```bash
+circom --version
+# Expected: circom compiler 2.2.2 or higher
+```
+
+If you see `command not found`, follow the [circom install guide](https://docs.circom.io/getting-started/installation/).
+
+## `PII_MASTER_KEY` validation error at startup
+
+**Symptom:** API startup rejects a missing or insufficiently long `PII_MASTER_KEY`.
+
+**Fix:** Supply 64 hex characters or at least 32 UTF-8 bytes. Generate a random value for a disposable local evaluation:
+
+```bash
+export PII_MASTER_KEY="$(openssl rand -hex 32)"
+```
+
+The startup check validates encoding and length, not randomness. Protect and retain the key when encrypted records must survive restart; changing it can prevent decryption of existing records.
+
+## Proof generation returns 500
+
+**Symptom:** `POST /proof/generate` fails because runtime state or proving artifacts are unavailable.
+
+Check that the requested credential, trusted issuer root, sanctions witnesses and compatible artifacts are available to the running process. Starting the API, issuing one development credential or building an offline sanctions tree does not alone establish a complete generation workflow. See the quickstart and current project status.
+
+## Sanctions oracle is stale
+
+**Symptom:** On-chain `verifyAndRecord()` reverts with `SanctionsOracleStale`.
+
+**Fix:** The oracle's grace period defaults to 24 hours. Update the sanctions root:
+
+```bash
+python scripts/relay_sanctions_root.py --network sepolia
+```
+
+Check the configured grace period and actual root update time on each intended chain. Test fixtures may deliberately exercise stale state; do not bypass freshness checks to authorize a transfer.
+
+## Nullifier already spent
+
+**Symptom:** The development `verifyAndRecord()` path reverts with `ProofAlreadyUsed` or `TransferAlreadyRecorded`.
+
+**Cause:** The nullifier or transfer reference has already been recorded in the target registry.
+
+**Fix:** Inspect the original transaction and transfer state before retrying. Preserve the same transfer identity across retries; do not create a new idempotency key just to bypass duplicate protection. API/registry transfer-hash consistency remains planned work.
+
+## WASM prover not found
+
+**Symptom:** `@clearproof/proof` throws `ENOENT: no such file or directory` for `compliance.wasm`.
+
+**Fix:** Compile circuits first:
+
+```bash
+bash scripts/compile_circuits.sh
+```
+
+Pass the actual compatible WASM, proving-key and verification-key paths to the SDK. The repository's development build writes the WASM under `artifacts/compliance_js/`; public package installation alone is not a complete proving setup.
+
+## Hardhat tests fail with `HH700`
+
+**Symptom:** `npx hardhat test` errors with `HH700: Artifact not found`.
+
+**Fix:** Compile contracts before running tests:
+
+```bash
+cd packages/contracts
+npx hardhat compile
+npx hardhat test
+```
+
+## CORS errors in browser
+
+**Symptom:** Browser console shows `Access-Control-Allow-Origin` errors when calling the API.
+
+**Fix:** Set `CORS_ALLOWED_ORIGINS` to your frontend origin:
+
+```bash
+export CORS_ALLOWED_ORIGINS="http://localhost:3000"
+```
+
+Using `*` with credentials enabled will trigger a startup warning and may not work in all browsers.
+
+## TypeScript build errors after pulling
+
+**Symptom:** `npm run build` fails with type errors after `git pull`.
+
+**Fix:** Clean install and rebuild:
+
+```bash
+rm -rf node_modules packages/*/dist
+npm install
+npm run build
+```

package/content/updates/2026-09-09-adoption-roadmap.md

@@ -0,0 +1,27 @@
+---
+id: UP-2026-001
+title: Adoption roadmap and documentation split published
+date: 2026-09-09
+publishAfter: 2026-09-09T00:00:00Z
+sourceCommit: d57aac12493ea585ad38e85d070385e9fa34d905
+claimRefs:
+  - docs/ADOPTION_ROADMAP.md
+  - docs/PUBLISHING.md
+  - README.md
+status: approved
+summary: The repository now carries a public adoption roadmap and publishing boundaries; internal commercial planning moved out of the public tree.
+---
+
+The main repository now includes [docs/ADOPTION_ROADMAP.md](https://github.com/repfigit/clearproof/blob/main/docs/ADOPTION_ROADMAP.md),
+which describes how teams can evaluate Clearproof as pilot-stage software: what
+the circuits and contracts check today, what stays outside that scope, and what
+a careful evaluation record looks like.
+
+A companion [docs/PUBLISHING.md](https://github.com/repfigit/clearproof/blob/main/docs/PUBLISHING.md)
+states the project's publication boundaries: source-backed claims, verified
+project-owned destinations, and no unsupported audit, customer or compliance
+statements.
+
+Clearproof remains pilot-stage software. Circuits and contracts have not
+completed an independent audit, and current proving artifacts use a
+development-only trusted setup. Use synthetic data and testnet funds.

package/content/updates/2026-09-12-full-walkthrough.md

@@ -0,0 +1,31 @@
+---
+id: UP-2026-002
+title: A complete transfer walkthrough exists in the source docs
+date: 2026-09-12
+publishAfter: 2026-09-12T14:30:00Z
+sourceCommit: 57222b0bcad7e8dc06796fb870105a41ac87b844
+claimRefs:
+  - packages/content/content/recipes/full-walkthrough.md
+  - packages/content/content/topics/quickstart.md
+  - README.md
+status: approved
+summary: The merged pilot source includes a documented end-to-end walkthrough, from building the sanctions tree through issuing a credential, generating a proof and recording it on a testnet registry.
+---
+
+The source repository includes a [full end-to-end walkthrough](https://github.com/repfigit/clearproof/blob/main/packages/content/content/recipes/full-walkthrough.md)
+covering the complete pilot flow: build the sanctions tree, issue a zkKYC
+credential, generate a Groth16 compliance proof, verify it off-chain, and record
+the verified result on a Sepolia [ComplianceRegistry](https://github.com/repfigit/clearproof/blob/main/packages/contracts/contracts/)
+where a `ProofVerified` event can be checked with the bundled script.
+
+Running it requires a local setup: the API with API-key auth, compiled circuit
+artifacts, deployed contracts and a Sepolia RPC endpoint. The
+[quickstart](https://github.com/repfigit/clearproof/blob/main/packages/content/content/topics/quickstart.md)
+documents the prerequisites honestly — there is no guaranteed setup or proving
+time, and the workflow uses synthetic data and testnet funds.
+
+This walkthrough is a development pilot, not a production transfer
+authorization. Circuits and contracts have not completed an independent audit,
+and local proving artifacts use a development-only trusted setup. If you want to
+see exactly what a Travel-Rule transfer-evidence flow looks like before
+evaluating the cryptography, the walkthrough is the shortest supported path.

package/content/updates/2026-09-12-npm-status.md

@@ -0,0 +1,27 @@
+---
+id: UP-2026-003
+title: What npm can install today, and what it cannot
+date: 2026-09-12
+publishAfter: 2026-09-12T14:30:00Z
+sourceCommit: 57222b0bcad7e8dc06796fb870105a41ac87b844
+claimRefs:
+  - packages/content/content/topics/quickstart.md
+  - README.md
+status: approved
+summary: Public @clearproof packages exist at 0.3.0, but the CLI cannot install from the registry and the development checkout is already 0.4.0. Here is what each path supports.
+---
+
+Clearproof's public npm packages are at **0.3.0** while the development checkout
+is **0.4.0** — they are not the same thing. Verified against the npm registry on
+September 12, 2026:
+
+- [`@clearproof/proof`](https://www.npmjs.com/package/@clearproof/proof) 0.3.0 — SDK install verified, but proof generation still requires matching circuit WASM and proving-key files supplied by the caller.
+- [`@clearproof/circuits`](https://www.npmjs.com/package/@clearproof/circuits) 0.3.0 — inspect package contents; installation alone is not a proving setup.
+- [`@clearproof/cli`](https://www.npmjs.com/package/@clearproof/cli) 0.3.0 — public install is currently blocked because its `@clearproof/content` dependency is unavailable on the registry (confirmed returning "Not found").
+- `@clearproof/content` — not published at all.
+
+The practical path for evaluating current capabilities is a
+[source checkout](https://github.com/repfigit/clearproof/blob/main/packages/content/content/topics/quickstart.md):
+clone, build, and run the documented checks. The README's installation table is
+kept current with what each package actually supports; nothing there claims a
+one-command production install, because that does not exist yet.

package/content/updates/2026-09-12-proof-boundaries.md

@@ -0,0 +1,40 @@
+---
+id: UP-2026-004
+title: What the compliance proof actually verifies
+date: 2026-09-12
+publishAfter: 2026-09-12T14:30:00Z
+sourceCommit: 57222b0bcad7e8dc06796fb870105a41ac87b844
+claimRefs:
+  - packages/content/content/topics/circuits.md
+  - packages/content/content/recipes/verify-proof.md
+  - packages/content/content/topics/security.md
+status: approved
+summary: The Groth16 circuit checks sanctions non-membership, credential validity and the amount tier — and it is worth being precise about what stays outside that boundary.
+---
+
+> **Correction, September 25, 2026:** this post described the legacy 16-signal
+> `compliance.circom` demo circuit as if it were current. The current pilot
+> profile, `pilot-transfer-v3`, publishes eight values with no public amount
+> tier or review flag, and screens both wallets. See the
+> [circuits page](https://docs.clearproof.world/docs/circuits).
+
+[The circuit documentation](https://github.com/repfigit/clearproof/blob/main/packages/content/content/topics/circuits.md)
+describes the three checks the legacy Groth16 circuit enforces:
+
+1. **Sanctions non-membership** — a sorted-tree gap construction shows the queried value lies between neighboring leaves. This establishes a fact about the supplied tree; authenticity, completeness and freshness of the screening source are separate requirements.
+2. **Credential validity** — checks performed against the credential commitment and issuer tree supplied to the circuit.
+3. **Amount tier** — the amount is compared against three ordered public thresholds and the claimed tier is checked.
+
+The public-signal array exposes all sixteen signals, including an advisory
+`sar_review_flag` that is tier-derived — it is not a suspicious-activity
+determination or filing instruction.
+
+What the proof does not do: a cryptographically valid proof is not an accepted
+transfer. Registry acceptance checks, credential authenticity, holder authority,
+actual transfer binding and replay/expiry handling depend on the verifier and
+its configuration — see the
+[security boundaries](https://github.com/repfigit/clearproof/blob/main/packages/content/content/topics/security.md)
+page. These components are unaudited development work, and the
+[off-chain verification recipe](https://github.com/repfigit/clearproof/blob/main/packages/content/content/recipes/verify-proof.md)
+shows exactly which four checks a verify call performs so you can compare them
+against what your own acceptance policy needs.

package/content/updates/2026-09-21-sanctions-schedule.md

@@ -0,0 +1,43 @@
+---
+id: UP-2026-005
+title: Sanctions-tree refresh now runs on a daily schedule with a change gate
+date: 2026-09-21
+publishAfter: 2026-09-22T15:30:00Z
+sourceCommit: 4a58f129e8640c65ad37074a37dd49114ce9db74
+claimRefs:
+  - .github/workflows/sanctions-update.yml
+  - scripts/build_sanctions_tree.py
+  - packages/content/content/recipes/update-sanctions.md
+status: approved
+summary: The sanctions dataset behind on-chain proof checks is refreshed daily by a scheduled workflow, with a leaf-count sanity gate and a reviewable PR when the tree changes — but the on-chain relay stays a deliberate operator step.
+---
+
+Clearproof proofs commit to a Merkle root of a sanctions dataset that the
+on-chain `SanctionsOracle` stores. Keeping that root current is an operational
+contract of the project — after any root update, all deployed chains must be
+re-relayed consistently. The repository now runs the dataset refresh on a
+schedule instead of leaving it entirely manual.
+
+What the workflow does:
+
+- `Update Sanctions Tree` runs daily at 06:00 UTC in GitHub Actions (scheduled
+  just after the OFAC SDN list typically updates), with a manual
+  `workflow_dispatch` trigger kept for operator use.
+- Each run fetches the public sanctions sources and rebuilds the deterministic
+  Poseidon Merkle tree with `scripts/build_sanctions_tree.py`.
+- A change gate compares the built tree against the committed baseline.
+- A safety check aborts the run if the leaf count drops by more than 50% — a
+  guard against silently building from a broken or partial data source.
+- When the tree actually changed, the workflow opens a reviewable branch and
+  pull request showing the previous and new leaf counts, rather than pushing
+  anything straight to the default branch.
+
+What the workflow deliberately does not do: it does not relay a new root to
+deployed chains on its own. The relay job runs on explicit `workflow_dispatch`,
+so an operator still drives the on-chain update after reviewing the tree PR —
+matching the documented rule that the sanctions relay is never skipped after a
+root update. The [sanctions update recipe](https://github.com/repfigit/clearproof/blob/main/packages/content/content/recipes/update-sanctions.md)
+walks through that operator flow.
+
+The workflow source is readable in full in the repository at
+`.github/workflows/sanctions-update.yml`.

package/content/updates/2026-09-25-pilot-transfer-v3.md

@@ -0,0 +1,60 @@
+---
+id: UP-2026-006
+title: Circuit profile pilot-transfer-v3 replaces v2 with production-scale tree depths
+date: 2026-09-25
+publishAfter: 2026-09-25T12:00:00Z
+sourceCommit: a67caef
+claimRefs:
+  - specs/pilot-transfer-v3.md
+  - docs/adr/0011-production-tree-depths.md
+  - src/registry/pilot_tree.py
+  - tests/unit/test_registrar_depths.py
+status: approved
+summary: The pilot circuit now fixes Merkle tree depths at 32/20/20 (issuance, authorized issuers, sanctions), raising capacity from 256 leaves per tree to production-scale sizes. Groth16 verification cost is unchanged; the keys are still development-only.
+---
+
+The development circuit profile for the pilot, `pilot-transfer-v2`, fixed every
+Merkle tree at depth 8: at most 256 leaves per tree. That ceiling is irrelevant
+for a demo but unusable for the deployments the pilot profile models — a large
+custodial VASP issues credentials to tens of millions of customers, a global
+authorized-issuer set has thousands of issuers, and consolidated sanctions
+address lists run to hundreds of thousands of EVM addresses.
+
+`pilot-transfer-v3` (merged this week, PR #49) fixes the depths at
+`PilotCompliance(32, 20, 20)` in the Circom circuit itself:
+
+| Tree | v2 depth | v3 depth | v3 capacity |
+| --- | --- | --- | --- |
+| Issuance (credentials under an issuance root) | 8 | 32 | 2^32 credentials per issuance root |
+| Authorized issuers | 8 | 20 | 2^20 issuer leaves |
+| Sanctions (raw EVM addresses) | 8 | 20 | 2^20 − 2 addresses (two leaves are the `0` and `2^160` sentinels) |
+
+Depths live in one place, `src/registry/pilot_tree.py`, and every consumer —
+witness builder, registrar, proof preparation, issuance tree service and root
+verification — reads them from there. Signed root snapshots must state the exact
+depth for their kind; any other depth rejects.
+
+Because tree depth is fixed by the circuit and therefore by the proving and
+verification keys, the profile name changes even though the public signal order
+and meaning are unchanged from v2. Keys are profile-specific: a v2 manifest
+cannot be proved or verified with v3 keys. Current artifact and context checks
+reject v1 and v2 as historical profiles; read-only pairing inspection can still
+use independently pinned v1/v2 keys and reports the profile explicitly.
+
+What changed in practice: constraints grow from 51,728 (v2) to 95,408 (v3), the
+local development setup now uses a `2^17` powers-of-tau, and the development
+zkey grows from roughly 23 MB to 44 MB. Groth16 verification cost is unchanged —
+it depends only on the public signal count, which is identical to v2.
+
+Two honest boundaries, stated plainly in [ADR 0011](https://github.com/repfigit/clearproof/blob/main/docs/adr/0011-production-tree-depths.md):
+
+- The v3 keys remain development-unapproved — no audit or production setup has
+  approved this circuit, and no existing Sepolia deployment implements v3.
+- Depth is only one of the production-scaling limits. The registrar still
+  configures 1–16 issuers, issuance-tree construction scans at most 256
+  enrollments per refresh, and the in-memory sparse tree builds at roughly
+  210 µs per hash — production scale needs an incremental persisted tree
+  service. Those are ordinary software, upgradeable without new keys.
+
+Read the full public statement at
+[specs/pilot-transfer-v3.md](https://github.com/repfigit/clearproof/blob/main/specs/pilot-transfer-v3.md).

package/dist/explainers.d.ts

@@ -0,0 +1,29 @@
+export interface ExplainerMeta {
+    id: string;
+    slug: string;
+    title: string;
+    date: string;
+    /** UTC timestamp after which the explainer may be published. */
+    publishAfter: string;
+    /** Source revision the claims were validated against. */
+    sourceCommit: string;
+    claimRefs: string[];
+    status: 'draft' | 'validated' | 'approved' | 'published';
+    summary: string;
+    /** Canonical site path for this explainer, e.g. /explainers/what-clearproof-does. */
+    canonical: string;
+    /** Editorial template version; approval is bound to template + body. */
+    templateVersion: string;
+}
+export interface Explainer extends ExplainerMeta {
+    body: string;
+}
+/**
+ * List all explainers with metadata (no body), sorted newest first by ISO date.
+ */
+export declare function listExplainers(): ExplainerMeta[];
+/**
+ * Get a single explainer by slug, including the markdown body.
+ */
+export declare function getExplainer(slug: string): Explainer | null;
+//# sourceMappingURL=explainers.d.ts.map

package/dist/explainers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainers.d.ts","sourceRoot":"","sources":["../src/explainers.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAU,SAAQ,aAAa;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AA2CD;;GAEG;AACH,wBAAgB,cAAc,IAAI,aAAa,EAAE,CAShD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQ3D"}

package/dist/explainers.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listExplainers = listExplainers;
+exports.getExplainer = getExplainer;
+const parser_js_1 = require("./parser.js");
+const EXPLAINER_FIELDS = [
+    'id',
+    'title',
+    'date',
+    'publishAfter',
+    'sourceCommit',
+    'status',
+    'summary',
+    'canonical',
+    'templateVersion',
+];
+function requiredStringFields(frontmatter) {
+    return EXPLAINER_FIELDS.filter((field) => typeof frontmatter[field] !== 'string' || frontmatter[field] === '');
+}
+function normalizeStatus(value) {
+    return ['draft', 'validated', 'approved', 'published'].includes(value)
+        ? value
+        : 'draft';
+}
+function toMeta(slug, frontmatter) {
+    const missing = requiredStringFields(frontmatter);
+    if (missing.length > 0)
+        return null;
+    const claimRefs = frontmatter['claimRefs'];
+    return {
+        id: frontmatter['id'],
+        slug,
+        title: frontmatter['title'],
+        date: frontmatter['date'],
+        publishAfter: frontmatter['publishAfter'],
+        sourceCommit: frontmatter['sourceCommit'],
+        claimRefs: Array.isArray(claimRefs) ? claimRefs.filter((ref) => typeof ref === 'string') : [],
+        status: normalizeStatus(frontmatter['status']),
+        summary: frontmatter['summary'],
+        canonical: frontmatter['canonical'],
+        templateVersion: frontmatter['templateVersion'],
+    };
+}
+/**
+ * List all explainers with metadata (no body), sorted newest first by ISO date.
+ */
+function listExplainers() {
+    const slugs = (0, parser_js_1.listContentSlugs)('explainers');
+    const explainers = [];
+    for (const slug of slugs) {
+        const { frontmatter } = (0, parser_js_1.readContentFile)(`explainers/${slug}.md`);
+        const meta = toMeta(slug, frontmatter);
+        if (meta)
+            explainers.push(meta);
+    }
+    return explainers.sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : a.slug.localeCompare(b.slug)));
+}
+/**
+ * Get a single explainer by slug, including the markdown body.
+ */
+function getExplainer(slug) {
+    try {
+        const { frontmatter, body } = (0, parser_js_1.readContentFile)(`explainers/${slug}.md`);
+        const meta = toMeta(slug, frontmatter);
+        return meta ? { ...meta, body } : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=explainers.js.map

package/dist/explainers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainers.js","sourceRoot":"","sources":["../src/explainers.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { parseFrontmatter, readContentFile, listContentSlugs, CONTENT_DIR } from './parser.js';
+export type { Frontmatter, ParsedFile } from './parser.js';
+export { listTopics, getTopic } from './topics.js';
+export type { TopicMeta, Topic } from './topics.js';
+export { listRecipes, getRecipe, getRecipeSteps } from './recipes.js';
+export type { RecipeMeta, Recipe, RecipeStep } from './recipes.js';
+export { listSignals, getSignal } from './signals.js';
+export type { Signal } from './signals.js';
+export { listUpdates, getUpdate } from './updates.js';
+export type { UpdateMeta, Update } from './updates.js';
+export { listExplainers, getExplainer } from './explainers.js';
+export type { ExplainerMeta, Explainer } from './explainers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/F,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}