+
+## Mental model
+
+
+
+ Express the computation and its public/private boundary as a Noir package.
+
+
+ Compile the circuit to produce a matching `.pkp` prover key and `.pkv` verifier key.
+
+
+ Combine the prover key with concrete witness inputs from `Prover.toml` or an SDK witness map.
+
+
+ Verify with the matching `.pkv` locally, in a service, in WASM, through FFI, or via recursive verification.
+
+
+
+## Core concepts
+
+| Concept | Description |
+| :--- | :--- |
+| **Noir** | The user-facing circuit language used for ProveKit's primary authoring path. |
+| **ACIR** | Abstract Circuit Intermediate Representation emitted by the Noir frontend. |
+| **R1CS** | Rank-1 Constraint System used by the ProveKit proving pipeline. |
+| **Prover key (`.pkp`)** | Key material used to generate a proof for a prepared circuit. |
+| **Verifier key (`.pkv`)** | Key material used to verify proofs from the matching prepared circuit. |
+| **WHIR proof** | Proof object generated by the prover and consumed by every verification path. |
+| **Recursive export** | `params_for_recursive_verifier` and `r1cs.json` derived from a matching verifier key and proof. |
+
+## Command responsibilities
+
+| Command | Responsibility | Run when |
+| :--- | :--- | :--- |
+| `prepare` | Compile the circuit and write `.pkp` / `.pkv`. | The circuit source, compiler backend, hash choice, branch, or proof format changes. |
+| `prove` | Generate `proof.np` from a prover key and inputs. | Once per witness or proof request. |
+| `verify` | Check a proof against a verifier key. | At every trust boundary. |
+| `show-inputs` | Decode public inputs from a verifier key and proof. | During integration testing and production validation. |
+| `generate-gnark-inputs` | Export recursive-verifier inputs from a verifier key and proof. | Whenever the verifier key or proof changes. |
+
+## The setup boundary
+
+
+
+This page stays at the product-flow level. For deployment controls and the security model, continue with:
+
+- [Artifact lifecycle](/concepts/artifact-lifecycle/)
+- [Security and trust model](/concepts/security-model/)
+- [Production checklist](/reference/production-checklist/)
diff --git a/docs/src/content/docs/concepts/security-model.mdx b/docs/src/content/docs/concepts/security-model.mdx
new file mode 100644
index 000000000..1fa4edc91
--- /dev/null
+++ b/docs/src/content/docs/concepts/security-model.mdx
@@ -0,0 +1,74 @@
+---
+title: Security and trust model
+description: Security boundaries and operational assumptions for teams integrating ProveKit.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+This page documents integration-level security expectations. It is not a cryptographic proof, audit report, or production-readiness certification, use it to decide where artifacts live, who may generate them, and which checks must run before accepting a proof.
+
+
+
+## Trust boundaries
+
+| Boundary | What crosses it | Required control |
+| :--- | :--- | :--- |
+| Circuit authoring → key preparation | Noir source, compiler backend, hash choice | Code review, pinned commit, reproducible command line. |
+| Key preparation → prover runtime | `.pkp` | Access control, integrity checks, recorded provenance. |
+| Prover runtime → verifier runtime | `proof.np` / proof JSON and public inputs | Verification with the matching `.pkv`; public-input review. |
+| Verifier runtime → application decision | Boolean validity plus decoded public inputs | Application-level authorization and policy checks. |
+| Recursive export → Go/gnark wrapper | `params_for_recursive_verifier`, `r1cs.json` | Regenerated from the exact verifier/proof pair; setup keys managed explicitly. |
+
+## What verification proves
+
+A successful ProveKit verification means the proof is valid against the verifier key and public-input binding presented to the verifier. **It does not tell your application what to do with that proof.**
+
+Your application still owns these decisions:
+
+- Whether a user is allowed to submit a proof for a given account or session.
+- Whether public inputs match the expected credential, nullifier, domain separator, or request ID.
+- Whether the proof / key / artifact version is still accepted by the service.
+- Whether replay protection or one-time-use semantics apply.
+
+## Cryptographic assumptions
+
+ProveKit's security rests on different assumptions for the base proof and the optional recursive wrapper. Treat them separately when modeling threats.
+
+| Layer | Underlying primitives | Quantum-resistance |
+| :--- | :--- | :--- |
+| **Base WHIR proof** | Hash-based polynomial commitment scheme (WHIR) + Spartan-style sumcheck. Security reduces to the chosen hash's collision resistance. | **Post-quantum secure** under conjectured hash-function PQ-security. Grover's algorithm imposes a quadratic speedup on preimage finding, so 256-bit hashes retain ~128-bit security against quantum adversaries. |
+| **Recursive Groth16 wrap** | Pairing-based SNARK over BN254. Security relies on the q-SDH / Knowledge-of-Exponent assumptions on pairings. | **Not post-quantum secure.** Shor's algorithm breaks discrete-log on elliptic curves; any Groth16-wrapped proof is vulnerable to a sufficiently capable quantum attacker. |
+
+If post-quantum security is part of your threat model, scope on-chain settlement carefully: verify the base WHIR proof off-chain (post-quantum secure path) rather than relying on the Groth16 outer proof for cryptographic guarantees. The wrapper is appropriate for cost-efficient EVM verification, not as a long-term cryptographic anchor.
+
+## Sensitive material
+
+| Material | Sensitivity |
+| :--- | :--- |
+| Private witness inputs | Sensitive by default. Keep out of logs and client-visible telemetry. |
+| `.pkp` prover keys | Operationally sensitive, they enable proof generation for the prepared circuit. |
+| `.pkv` verifier keys | Usually distributable, but always integrity-protected and versioned. |
+| Proofs | May carry public inputs and metadata that are sensitive in your application context. |
+| Recursive proving keys | Manage explicitly. Development-time generation is not sufficient for production. |
+
+## Operational controls
+
+- Pin the branch, commit, lockfile, toolchain, compiler backend, and hash choice for every artifact release.
+- Verify locally before publishing or accepting any proof artifact.
+- Review public inputs with `show-inputs --hex` for byte-exact comparison.
+- Reject proofs whose provenance is unknown or spans multiple generations.
+- Restrict verifier-server artifact URLs to trusted sources, or proxy downloads through trusted storage.
+- Keep FFI buffer ownership, mobile memory settings, and WASM prover lifecycle under test on real target devices.
+- Add negative tests for mismatched key / proof pairs and corrupted proof payloads.
+
+## Red-team prompts for reviewers
+
+Ask these questions during every integration review:
+
+1. Can a client choose the `.pkv`, `r1cs.json`, proving key, or verifying key used by a verifier service?
+2. Are public inputs bound to the correct account, session, chain, domain, or request?
+3. Can a previously valid proof be replayed after a policy or circuit change?
+4. Could an artifact generated from `main` be accepted by a `v1` deployment by accident?
+5. Are witness values, proofs, or prover keys logged anywhere, CLI wrappers, web servers, mobile crash reporters?
diff --git a/docs/src/content/docs/concepts/what-is-provekit.mdx b/docs/src/content/docs/concepts/what-is-provekit.mdx
new file mode 100644
index 000000000..84d4d27dc
--- /dev/null
+++ b/docs/src/content/docs/concepts/what-is-provekit.mdx
@@ -0,0 +1,99 @@
+---
+title: What is ProveKit?
+description: A developer-friendly introduction to ProveKit, the WHIR proof system it builds on, and the problems it's designed to solve.
+---
+
+import { Aside, Card, CardGrid } from "@astrojs/starlight/components";
+
+ProveKit is a zero knowledge Spartan + WHIR based proof system. You write a circuit in [Noir](https://noir-lang.org/); ProveKit compiles it to R1CS, generates [WHIR](https://eprint.iacr.org/2024/1586.pdf) proofs from your inputs, and verifies those proofs from Rust, WebAssembly, mobile FFI, an HTTP service, or via a Groth16 outer proof for on-chain settlement.
+
+## The problem ProveKit solves
+
+A zero-knowledge proof lets one party (the **prover**) convince another (the **verifier**) that a statement is true, _without revealing the data that makes the statement true_.
+
+A few statements ProveKit can help you prove:
+
+- "I am over 18", without revealing a date of birth.
+- "I own a passport issued by country X", without revealing the passport.
+- "This vote came from a registered voter", without revealing which voter.
+- "This off-chain computation produced this result", without re-running it on-chain.
+
+The workflow is the same shape every time:
+
+1. **Write a circuit** in Noir. A small program defining what counts as "true."
+2. **Prepare** prover and verifier keys from the compiled circuit.
+3. **Prove** a specific instance using your real (private) inputs and the prover key.
+4. **Verify** the proof anywhere using the verifier key and the public inputs.
+
+ProveKit owns steps 2–4 and the runtime that runs them on every platform you ship to. You bring the Noir circuit; ProveKit handles the rest.
+
+## What's in the box
+
+ProveKit is a workspace of focused Rust crates plus tooling. Each piece has one job:
+
+| Crate / tool | Job |
+| :------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`provekit-r1cs-compiler`](https://github.com/worldfnd/provekit/tree/main/provekit/r1cs-compiler) | Lower Noir's ACIR into R1CS, with specialized handling for Poseidon2, SHA-256 compression, range checks, multi-scalar multiplication. |
+| [`provekit-prover`](https://github.com/worldfnd/provekit/tree/main/provekit/prover) | Solve the witness in layers, commit via Merkle hashing, and produce the WHIR proof via Spartan-style sumcheck. |
+| [`provekit-verifier`](https://github.com/worldfnd/provekit/tree/main/provekit/verifier) | Replay the Fiat-Shamir transcript, run sumcheck verification, and bind the public inputs. |
+| [`provekit-cli`](https://github.com/worldfnd/provekit/tree/main/tooling/cli) | The command-line entry point. Subcommands: `prepare`, `prove`, `verify`, plus inspection and recursive-verifier export. |
+| [`provekit-wasm`](https://github.com/worldfnd/provekit/tree/main/tooling/provekit-wasm) | Browser and Node.js bindings using `wasm-bindgen-rayon` for in-browser parallel proving when `SharedArrayBuffer` is available. |
+| [`provekit-ffi`](https://github.com/worldfnd/provekit/tree/main/tooling/provekit-ffi) | C ABI for Swift, Kotlin, Python, and any host that can call a shared library. Includes an mmap-backed allocator for mobile circuits that exceed RAM. |
+| [`verifier-server`](https://github.com/worldfnd/provekit/tree/main/tooling/verifier-server) | An Axum HTTP service that downloads artifacts and orchestrates verification with configurable concurrency and timeouts. |
+| [`recursive-verifier/`](https://github.com/worldfnd/provekit/tree/main/recursive-verifier) | A Go/gnark module that wraps a ProveKit proof in Groth16 so it can be verified by an EVM contract. |
+| [`skyscraper`](https://github.com/worldfnd/provekit/tree/main/skyscraper) | A custom BN254 hash engine with SIMD-accelerated field arithmetic. |
+
+## What makes ProveKit specifically different
+
+- **No trusted setup.** WHIR's commitment scheme is hash-based. The base proof needs no per-circuit ceremony and no toxic-waste handling. You compile a circuit and ship.
+- **Post-quantum secure base proof.** WHIR inherits PQ-security from the chosen hash function (Skyscraper, SHA-256, Keccak, Blake3, or Poseidon2), so its hardness assumptions survive Shor-style attacks. The optional Groth16 wrapper for on-chain settlement uses pairing-based crypto (BN254) and is **not** post-quantum secure, scope on-chain proofs accordingly.
+
+## Before you build
+
+Two pages matter on day one: [Artifact lifecycle](/concepts/artifact-lifecycle/) for how `.pkp` / `.pkv` / `proof.np` are paired and versioned, and [Security and trust model](/concepts/security-model/) for what verification does and doesn't say about authorization.
+
+## A worked picture
+
+The checked-in `noir-examples/basic` circuit proves you know two field elements that hash (via Poseidon2) to a known commitment:
+
+```rust
+use dep::poseidon2;
+
+fn main(plains: [Field; 2], result: pub Field) {
+ let hash = poseidon2::bn254::hash_2(plains);
+ assert(hash == result);
+}
+```
+
+`plains` stays private; only the prover sees it. `result` is the public input that goes into the proof. A successful verification means _the prover knows two field elements that hash to `result`_, and the verifier learns the prover does, without learning `plains`.
+
+That tiny circuit is the same shape as much bigger ones: identity attestation, set membership, off-chain computation, range proofs. Once you can build, prove, and verify this one, every other circuit follows the same workflow.
+
+## Where to go next
+
+
+
+ Five-minute path: prepare, prove, verify the basic example on your machine.
+
+ [Quickstart →](/getting-started/quickstart/)
+
+
+
+ The full proving and verification flow from Noir source to recursive export.
+
+ [Proving flow →](/concepts/proving-flow/)
+
+
+
+ Decide where ProveKit runs in your system: CLI, Rust, WASM, FFI, HTTP service, or recursive.
+
+ [Integrations overview →](/integrations/overview/)
+
+
+
+ A catalog of Noir circuits shipped with the repo, from hash primitives to passport verification.
+
+ [Examples catalog →](/reference/examples/)
+
+
+
diff --git a/docs/src/content/docs/e2e/generate-artifacts.mdx b/docs/src/content/docs/e2e/generate-artifacts.mdx
new file mode 100644
index 000000000..24c800163
--- /dev/null
+++ b/docs/src/content/docs/e2e/generate-artifacts.mdx
@@ -0,0 +1,129 @@
+---
+title: Generate artifacts
+description: Produce reproducible ProveKit keys, proofs, and recursive-verifier exports with explicit paths.
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+Use this guide when you need reproducible artifact paths for tests, demos, CI jobs, release bundles, or downstream integrations.
+
+## Default artifact flow
+
+From `noir-examples/basic`:
+
+```sh
+cargo run --release --bin provekit-cli -- prepare
+cargo run --release --bin provekit-cli -- prove
+cargo run --release --bin provekit-cli -- verify
+```
+
+This writes:
+
+| File | Created by | Consumed by |
+| :--- | :--- | :--- |
+| `basic.pkp` | `prepare` | `prove` |
+| `basic.pkv` | `prepare` | `verify`, `show-inputs`, `generate-gnark-inputs` |
+| `proof.np` | `prove` | `verify`, `show-inputs`, `generate-gnark-inputs` |
+| `target/basic.json` | Noir compilation during `prepare` | ProveKit internals and inspection workflows |
+
+## Explicit artifact directory
+
+
+1. Enter the Noir package and create an output directory.
+
+ ```sh
+ cd noir-examples/basic
+ mkdir -p artifacts
+ ```
+
+2. Prepare key material.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- prepare . \
+ --pkp ./artifacts/basic.pkp \
+ --pkv ./artifacts/basic.pkv
+ ```
+
+3. Generate a proof.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- prove \
+ --prover ./artifacts/basic.pkp \
+ --input ./Prover.toml \
+ --out ./artifacts/proof.np
+ ```
+
+4. Verify the proof.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- verify \
+ --verifier ./artifacts/basic.pkv \
+ --proof ./artifacts/proof.np
+ ```
+
+
+## Hash choice
+
+`prepare` defaults to `skyscraper`. The CLI also accepts `sha256`, `keccak`, `blake3`, and `poseidon2` via `--hash`:
+
+```sh
+cargo run --release --bin provekit-cli -- prepare . --hash blake3
+```
+
+The hash is part of the artifact's identity. Regenerate the prover key, verifier key, and every proof after changing it.
+
+
+
+## Inspect public inputs
+
+Decode public inputs as part of integration testing:
+
+```sh
+cargo run --release --bin provekit-cli -- show-inputs --hex \
+ ./artifacts/basic.pkv \
+ ./artifacts/proof.np
+```
+
+Review the output with the application owner. Verification proves the proof is valid for the verifier key, your application still owns the decision about whether those inputs authorize the requested action.
+
+## Recursive-verifier export
+
+After the proof verifies, export inputs for the Go/gnark recursive verifier:
+
+```sh
+cargo run --release --bin provekit-cli -- generate-gnark-inputs \
+ ./artifacts/basic.pkv \
+ ./artifacts/proof.np \
+ --params ./artifacts/params_for_recursive_verifier \
+ --r1cs ./artifacts/r1cs.json
+```
+
+The command reads the verifier key and proof, then writes the recursive parameters and an R1CS JSON. Keep those outputs paired with the exact `basic.pkv` and `proof.np` that produced them.
+
+## CI evidence template
+
+A release-producing CI job should persist at least:
+
+```text
+commit:
+rust-toolchain:
+lockfile: Cargo.lock
+compiler: noir
+prepare_hash: skyscraper
+commands:
+ - cargo run --release --bin provekit-cli -- prepare ...
+ - cargo run --release --bin provekit-cli -- prove ...
+ - cargo run --release --bin provekit-cli -- verify ...
+artifacts:
+ - artifacts/basic.pkp
+ - artifacts/basic.pkv
+ - artifacts/proof.np
+```
+
+## Cleanup
+
+```sh
+rm -rf artifacts target basic.pkp basic.pkv proof.np params_for_recursive_verifier r1cs.json
+```
diff --git a/docs/src/content/docs/e2e/js-typescript.mdx b/docs/src/content/docs/e2e/js-typescript.mdx
new file mode 100644
index 000000000..c92353a8d
--- /dev/null
+++ b/docs/src/content/docs/e2e/js-typescript.mdx
@@ -0,0 +1,60 @@
+---
+title: JS / TypeScript end-to-end
+description: Drive ProveKit's WASM backend from JavaScript or TypeScript in Node.js and browser applications.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+This guide uses the Verity JS / TypeScript SDK, which wraps ProveKit's WASM backend for browser and Node.js environments. References below are pinned to Verity commit `3f6b8ad6e7c994a740a204fbf35c0a3f3001e4d3`.
+
+
+
+## SDK surface
+
+At the pinned Verity revision:
+
+- `sdks/js/package.json` publishes `@atheon/verity` as an ESM-first package with Node and browser export targets.
+- `sdks/js/src/index.ts` exports `Verity`, `Backend`, `Proof`, and the scheme types.
+- `sdks/js/src/verity.ts` constructs `Verity` via `Verity.create(Backend.ProveKit)` and loads prover and verifier schemes from bytes.
+- `sdks/js/src/types.ts` defines `ProverScheme.prove(inputs: Record | string)` and `VerifierScheme.verify(proof)`.
+- `verity.ts` also exposes `verity.prove(...)` and `verity.verify(...)` convenience delegates, but the scheme methods shown below are the canonical API.
+- `sdks/js/src/backends/provekit.ts` loads the ProveKit WASM module, extracts Noir circuit JSON from `.pkp` bytes, uses `@noir-lang/noir_js` and `@noir-lang/acvm_js` for witness generation, and verifies proofs through the WASM verifier.
+
+## Minimal flow
+
+```ts
+import { Backend, Verity } from "@atheon/verity";
+
+const verity = await Verity.create(Backend.ProveKit);
+
+const prover = await verity.loadProver(proverBytes); // Uint8Array of .pkp
+const verifier = await verity.loadVerifier(verifierBytes); // Uint8Array of .pkv
+
+const proof = await prover.prove({ age: "25", threshold: "18" });
+const valid = await verifier.verify(proof);
+
+if (!valid) {
+ throw new Error("proof did not verify");
+}
+
+prover.dispose();
+verifier.dispose();
+```
+
+`inputs` may be a plain object or a JSON object string. For Noir circuits with arrays or structured inputs, keep the object layout aligned with the circuit ABI and validate it in application tests.
+
+## Build and packaging notes
+
+- Build the ProveKit WASM artifact before running the browser or Node path from the Verity repo: `make core-wasm`.
+- Generate demo/test `.pkp` and `.pkv` fixtures via `bash scripts/generate-js-artifacts.sh` when using the Verity fixture flow.
+- Install the optional Noir peer dependencies for JS witness generation: `@noir-lang/noir_js` and `@noir-lang/acvm_js`.
+- Browser threading depends on `SharedArrayBuffer`. The Verity ProveKit binding falls back to a non-threaded path when worker/thread-pool initialization is unavailable.
+- `proverBytes` and `verifierBytes` are assumed to be `Uint8Array` values already loaded by the application. Fetching, caching, integrity checks, and lifecycle cleanup are the host's responsibility.
+
+## Related pages
+
+- [End-to-end overview](/e2e/overview/)
+- [Generate artifacts](/e2e/generate-artifacts/)
+- [Integrations overview](/integrations/overview/)
diff --git a/docs/src/content/docs/e2e/kotlin.mdx b/docs/src/content/docs/e2e/kotlin.mdx
new file mode 100644
index 000000000..3cd66a81d
--- /dev/null
+++ b/docs/src/content/docs/e2e/kotlin.mdx
@@ -0,0 +1,66 @@
+---
+title: Kotlin end-to-end
+description: Integrate ProveKit on Android via the Verity Kotlin SDK, using the published AAR or a local build.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+This guide uses the Verity Kotlin SDK, which wraps the JNI bridge, shared dispatcher, and ProveKit backend for Android. References below are pinned to Verity commit `3f6b8ad6e7c994a740a204fbf35c0a3f3001e4d3`.
+
+
+
+## SDK surface
+
+At the pinned Verity revision:
+
+- `sdks/kotlin/build.gradle.kts` defines an Android library and currently publishes `arm64-v8a` JNI libraries.
+- `Backend.kt` exposes `Backend.PROVEKIT` for the ProveKit WHIR backend.
+- `Verity.kt` loads `verity_jni`, initializes a backend once, and loads prover/verifier schemes from file paths or `ByteArray`.
+- `Witness.kt` supports TOML files, flat maps of field-element strings, and JSON strings for arrays or nested objects.
+- `ProverScheme.kt`, `VerifierScheme.kt`, and `Proof.kt` expose `prove`, `verify`, serialization, deterministic `close()`, and `use { ... }` cleanup patterns.
+
+## Gradle declaration
+
+```kotlin
+dependencies {
+ implementation("xyz.atheon:verity:0.3.0")
+}
+```
+
+Confirm the published version and ABI coverage for your release. At the pinned revision, the Gradle metadata indicates `arm64-v8a` is the published ABI.
+
+## Minimal flow
+
+```kotlin
+import xyz.atheon.verity.*
+
+val verity = Verity(Backend.PROVEKIT)
+val prover = verity.loadProver("scheme.pkp")
+val verifier = verity.loadVerifier("scheme.pkv")
+
+prover.use { p ->
+ verifier.use { v ->
+ val witness = Witness.of(mapOf("age" to "25", "threshold" to "18"))
+ val proof = p.prove(witness)
+ check(v.verify(proof)) { "proof did not verify" }
+ }
+}
+```
+
+Use `loadProver(ByteArray)` and `loadVerifier(ByteArray)` when the app stores artifacts as Android assets, downloads them, or manages them through encrypted storage.
+
+## Build and packaging notes
+
+- `make test-kotlin` runs Android `connectedAndroidTest` in the Verity repo; fixture generation requires `core-native`.
+- The pinned build notes record that the published Kotlin AAR currently ships `arm64-v8a` JNI libraries only.
+- Local Android builds use `core/build/build-android.sh`, which accepts `VERITY_ANDROID_ABIS=arm64-v8a,x86_64` for additional ABI outputs.
+- Call `Verity.configureMemory(...)` before constructing `Verity` when large ProveKit circuits need Android RAM limits or file-backed memory.
+- The snippet assumes `scheme.pkp` and `scheme.pkv` are readable from the app's filesystem. Package them as assets and copy to a readable path, or load them as bytes, depending on your distribution model.
+
+## Related pages
+
+- [End-to-end overview](/e2e/overview/)
+- [Generate artifacts](/e2e/generate-artifacts/)
+- [Integrations overview](/integrations/overview/)
diff --git a/docs/src/content/docs/e2e/overview.mdx b/docs/src/content/docs/e2e/overview.mdx
new file mode 100644
index 000000000..be477ad72
--- /dev/null
+++ b/docs/src/content/docs/e2e/overview.mdx
@@ -0,0 +1,151 @@
+---
+title: End-to-end overview
+description: How a ProveKit run moves from Noir source to a verified proof and (optionally) a recursive-verifier export.
+---
+
+import { Aside, Card, CardGrid, Steps } from '@astrojs/starlight/components';
+
+A complete ProveKit run starts with one Noir package and ends with a verified proof. The same `.pkp`, `.pkv`, and `proof.np` files flow through every integration path, CLI workflows, SDK examples, the verifier service, and recursive-verifier export.
+
+## The full path
+
+
+
+
Noir package
+
→
+
prepare
+
→
+
.pkp + .pkv
+
+
+
.pkp + Prover.toml
+
→
+
prove
+
→
+
proof.np
+
+
+
.pkv + proof.np
+
→
+
verify
+
+
+
.pkv + proof.np
+
→
+
generate-gnark-inputs
+
→
+
params + r1cs.json
+
+
+
+## Working-directory rule
+
+By default, the CLI resolves the enclosing Noir package from the current directory:
+
+- `prepare` compiles `.` when no package path is provided.
+- `prove` looks for `.pkp` and `./Prover.toml`.
+- `verify` looks for `.pkv` and `./proof.np`.
+
+For `noir-examples/basic`, the defaults are `basic.pkp`, `basic.pkv`, `Prover.toml`, and `proof.np`.
+
+
+
+## Artifact ownership
+
+| File | Owner | Regenerate when |
+| :--- | :--- | :--- |
+| `.pkp` | Prover-side runtime | Circuit, compiler backend, branch/commit, hash, or proving configuration changes. |
+| `.pkv` | Verifier-side runtime | The prover key is regenerated, or verifier configuration changes. |
+| `proof.np` | Proof transport / storage layer | Inputs change, the prover key changes, or a fresh proof is required. |
+| `params_for_recursive_verifier` + `r1cs.json` | Recursive-verifier integration | The verifier key or proof changes. |
+
+## Local command sequence
+
+
+1. Prepare keys.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- prepare
+ ```
+
+2. Generate a proof.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- prove
+ ```
+
+3. Verify locally.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- verify
+ ```
+
+4. *(Optional)* Export recursive-verifier inputs.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- generate-gnark-inputs basic.pkv proof.np
+ ```
+
+
+## Explicit output paths
+
+Create the target directory before writing into it:
+
+```sh
+mkdir -p artifacts
+```
+
+Then run with explicit paths:
+
+```sh
+cargo run --release --bin provekit-cli -- prepare . \
+ --pkp ./artifacts/basic.pkp \
+ --pkv ./artifacts/basic.pkv
+
+cargo run --release --bin provekit-cli -- prove \
+ --prover ./artifacts/basic.pkp \
+ --input ./Prover.toml \
+ --out ./artifacts/proof.np
+
+cargo run --release --bin provekit-cli -- verify \
+ --verifier ./artifacts/basic.pkv \
+ --proof ./artifacts/proof.np
+```
+
+## Pick the next guide
+
+
+
+ Deterministic paths, pinned hash choices, and recursive-verifier export.
+
+ [Generate artifacts →](/e2e/generate-artifacts/)
+
+
+ Load `.pkp` / `.pkv`, prove from TOML, persist `proof.np`, and verify through the ProveKit crates.
+
+ [Rust guide →](/e2e/rust/)
+
+
+ Load `.pkp` / `.pkv` bytes and use WASM-backed proving and verification.
+
+ [JS / TypeScript guide →](/e2e/js-typescript/)
+
+
+ Integrate through the mobile SDKs and their native/FFI packaging.
+
+ [Swift →](/e2e/swift/) · [Kotlin →](/e2e/kotlin/)
+
+
+ Pin artifact provenance and complete pre-launch checks.
+
+ [Production checklist →](/reference/production-checklist/)
+
+
+
+## Related pages
+
+- [Quickstart](/getting-started/quickstart/), runs the default-path flow.
+- [Artifact lifecycle](/concepts/artifact-lifecycle/), pairing and regeneration rules.
+- [CLI overview](/cli/overview/), every command option and hash choice.
diff --git a/docs/src/content/docs/e2e/rust.mdx b/docs/src/content/docs/e2e/rust.mdx
new file mode 100644
index 000000000..5e9bd493f
--- /dev/null
+++ b/docs/src/content/docs/e2e/rust.mdx
@@ -0,0 +1,112 @@
+---
+title: Rust end-to-end
+description: Drive ProveKit directly from Rust, load prepared artifacts, prove from TOML inputs, and verify in process.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Use the Rust path when a service, test harness, or release pipeline can link the ProveKit crates and own artifact loading directly, instead of shelling out to `provekit-cli`.
+
+
+
+## Flow at a glance
+
+The Rust path mirrors the CLI:
+
+1. Generate `.pkp` and `.pkv` via the CLI (or the compiler APIs).
+2. Load `.pkp` into `provekit_common::Prover`.
+3. Generate a `NoirProof` with `provekit_prover::Prove::prove_with_toml`.
+4. Persist the proof with `provekit_common::file::write` when needed.
+5. Load `.pkv` into `provekit_common::Verifier`.
+6. Verify with `provekit_verifier::Verify::verify`.
+
+## Prepare artifacts
+
+Start from the checked-in basic Noir package:
+
+```sh
+cd noir-examples/basic
+mkdir -p artifacts
+
+cargo run --release --bin provekit-cli -- prepare . \
+ --pkp artifacts/basic.pkp \
+ --pkv artifacts/basic.pkv
+```
+
+The Rust program below reads these `.pkp` and `.pkv` files.
+
+## Cargo dependencies
+
+The crates are published on crates.io. Pin exact versions; the current release is `1.0.0` (see [GitHub Releases](https://github.com/worldfnd/provekit/releases) for newer tags).
+
+```toml
+[dependencies]
+provekit-common = "1.0.0"
+provekit-prover = "1.0.0"
+provekit-verifier = "1.0.0"
+```
+
+Use path or Git dependencies only when you are deliberately testing an unpublished checkout.
+
+## Minimal program
+
+Run the program from the repository root so the example paths resolve to `noir-examples/basic/...`.
+
+```rust
+use std::{error::Error, path::Path};
+
+use provekit_common::{
+ file::{read, write},
+ NoirProof, Prover, Verifier,
+};
+use provekit_prover::Prove;
+use provekit_verifier::Verify;
+
+fn main() -> Result<(), Box> {
+ let prover_path = Path::new("noir-examples/basic/artifacts/basic.pkp");
+ let verifier_path = Path::new("noir-examples/basic/artifacts/basic.pkv");
+ let input_path = Path::new("noir-examples/basic/Prover.toml");
+ let proof_path = Path::new("noir-examples/basic/artifacts/proof.np");
+
+ let prover: Prover = read(prover_path)?;
+ let proof = prover.prove_with_toml(input_path)?;
+ write(&proof, proof_path)?;
+
+ let mut verifier: Verifier = read(verifier_path)?;
+ verifier.verify(&proof)?;
+
+ // Optional: confirm the serialized proof round-trips through the same
+ // file format used by the CLI.
+ let persisted_proof: NoirProof = read(proof_path)?;
+ let mut fresh_verifier: Verifier = read(verifier_path)?;
+ fresh_verifier.verify(&persisted_proof)?;
+
+ Ok(())
+}
+```
+
+## Verifier lifecycle
+
+
+
+The sample above intentionally loads `fresh_verifier` for the round-trip check. A long-lived service should make that lifecycle explicit.
+
+## Production notes
+
+- Use absolute, explicit artifact paths. Don't depend on the process current directory in services.
+- Treat `.pkp`, `.pkv`, and `proof.np` as versioned deployment artifacts.
+- Validate public inputs with `show-inputs` during integration testing.
+- Add negative tests for mismatched `.pkv` / proof pairs.
+- Regenerate keys and proofs after any change to circuit, branch, compiler backend, lockfile, toolchain, or `prepare --hash`.
+- Walk through the [Production checklist](/reference/production-checklist/) before shipping a Rust prover or verifier service.
+
+## Related pages
+
+- [End-to-end overview](/e2e/overview/)
+- [Generate artifacts](/e2e/generate-artifacts/)
+- [CLI overview](/cli/overview/)
+- [Artifact lifecycle](/concepts/artifact-lifecycle/)
diff --git a/docs/src/content/docs/e2e/swift.mdx b/docs/src/content/docs/e2e/swift.mdx
new file mode 100644
index 000000000..1c180118b
--- /dev/null
+++ b/docs/src/content/docs/e2e/swift.mdx
@@ -0,0 +1,76 @@
+---
+title: Swift end-to-end
+description: Integrate ProveKit on iOS via the Verity Swift SDK and Swift Package Manager.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+This guide uses the Verity Swift SDK, which wraps the shared Verity dispatcher and the ProveKit backend for iOS. References below are pinned to Verity commit `3f6b8ad6e7c994a740a204fbf35c0a3f3001e4d3`.
+
+
+
+
+
+## SDK surface
+
+At the pinned Verity revision:
+
+- The root `Package.swift` exposes the `Verity` library product. ProveKit targets iOS 15+; the package's macOS platform declaration is upstream-only. The native binary artifacts are iOS-only.
+- `Package.swift` selects `source-only`, `native`, or `release` mode via the `VERITY_SWIFT_SDK_MODE` environment variable (or auto-detection).
+- `sdks/swift/Sources/Verity/Verity.swift` defines `Backend.provekit`, initializes the backend once, and loads prover/verifier schemes from file paths, URLs, or `Data`.
+- `Witness.swift` accepts TOML paths, dictionaries of field-element strings, and JSON strings.
+- `ProverScheme.swift` and `VerifierScheme.swift` expose `prove(witness:)`, `verify(proof:)`, `serialize()`, `save(to:)`, and explicit `close()` lifecycle methods.
+
+## Package declaration
+
+```swift
+// Package.swift
+dependencies: [
+ .package(url: "https://github.com/atheonxyz/verity", from: "0.3.2")
+],
+targets: [
+ .target(name: "MyApp", dependencies: [
+ .product(name: "Verity", package: "verity")
+ ])
+]
+```
+
+## Minimal flow
+
+```swift
+import Verity
+
+let verity = try Verity(backend: .provekit)
+
+let prover = try verity.loadProver(from: "scheme.pkp")
+let verifier = try verity.loadVerifier(from: "scheme.pkv")
+
+let witness = Witness(values: ["age": "25", "threshold": "18"])
+let proof = try prover.prove(witness: witness)
+
+let valid = try verifier.verify(proof: proof)
+precondition(valid, "proof did not verify")
+
+prover.close()
+verifier.close()
+```
+
+Use `loadProver(data:)` and `loadVerifier(data:)` when the app downloads or bundles artifacts as `Data`.
+
+## Build and packaging notes
+
+- `source-only` validates the Swift wrapper and public API without linking the iOS xcframework, it is not a native proof harness on its own.
+- `native` requires a locally built `output/Verity.xcframework`. `release` consumes the published xcframework declared by the package manifest.
+- The pinned build notes record that the native mobile artifact currently bundles the ProveKit backend only.
+- Use Xcode's iOS simulator test runner for native verification.
+- Call ProveKit's memory configuration before constructing `Verity` when the app needs mobile RAM limits or file-backed memory.
+
+## Related pages
+
+- [End-to-end overview](/e2e/overview/)
+- [Generate artifacts](/e2e/generate-artifacts/)
+- [Integrations overview](/integrations/overview/)
diff --git a/docs/src/content/docs/getting-started/installation.mdx b/docs/src/content/docs/getting-started/installation.mdx
new file mode 100644
index 000000000..64f11dcd2
--- /dev/null
+++ b/docs/src/content/docs/getting-started/installation.mdx
@@ -0,0 +1,112 @@
+---
+title: Installation and setup
+description: Install provekit-cli from crates.io, or set up a source checkout for development and bundled examples.
+---
+
+import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+
+There are two ways to get `provekit-cli` on a machine. Use **`cargo install`** when you just need the CLI and have your own circuit. Use a **source checkout** when you want the bundled Noir examples, the WASM/FFI/server crates, or you're contributing to ProveKit.
+
+## Prerequisites
+
+| Requirement | Why it matters |
+| :--- | :--- |
+| **Rust via `rustup`** | Cargo installs and builds the CLI. Source builds use the toolchain pinned in `rust-toolchain.toml`. |
+| **Git** *(source path only)* | Clones the repository and records exact commits for artifact provenance. |
+| **Corepack + pnpm** *(optional)* | Required only to edit or build this docs site. |
+| **Go toolchain** *(optional)* | Required only for recursive-verifier development. |
+
+## Install the CLI
+
+
+
+```sh
+cargo install provekit-cli
+provekit-cli --help
+```
+
+This builds and installs the latest published release into `~/.cargo/bin/`. Use this when you have your own Noir package and don't need the bundled examples or extra tooling.
+
+Pin a specific version for reproducible CI:
+
+```sh
+cargo install provekit-cli --version 1.0.0 --locked
+```
+
+
+```sh
+git clone https://github.com/worldfnd/provekit.git
+cd provekit
+rustup show # confirms the pinned nightly is selected
+cargo run --release --bin provekit-cli -- --help
+```
+
+This gives you the full workspace: examples in `noir-examples/`, WASM bindings in `tooling/provekit-wasm/`, FFI in `tooling/provekit-ffi/`, the verifier server, and the recursive-verifier Go module. Use this when you're contributing to ProveKit or want to run the checked-in examples directly.
+
+
+
+
+
+## Run the example proof
+
+If you installed via `cargo install`, point the CLI at your own Noir package. To run the canonical example, you need a copy of `noir-examples/basic/` from the repository:
+
+
+
+```sh
+cd noir-examples/basic
+cargo run --release --bin provekit-cli -- prepare
+cargo run --release --bin provekit-cli -- prove
+cargo run --release --bin provekit-cli -- verify
+```
+
+
+```sh
+git clone --depth 1 https://github.com/worldfnd/provekit.git
+cd provekit/noir-examples/basic
+provekit-cli prepare
+provekit-cli prove
+provekit-cli verify
+```
+
+The `cargo install` binary doesn't need `cargo run --release --bin provekit-cli --` in front of every command; call `provekit-cli` directly.
+
+
+
+If `verify` returns exit code `0`, your setup is healthy.
+
+## Build the documentation site
+
+The docs live in `docs/` and are built with [Astro Starlight](https://starlight.astro.build/). Source checkout only.
+
+```sh
+cd docs
+corepack enable
+pnpm install
+pnpm check
+pnpm build
+```
+
+Use `pnpm dev` for live preview while authoring.
+
+## Optional host tooling
+
+| Target | Additional tooling |
+| :--- | :--- |
+| **Browser / Node.js** | Build the WASM package in `tooling/provekit-wasm/` and load `.pkp` / `.pkv` artifacts as bytes. |
+| **iOS** | Build or consume the Swift SDK package mode used by your app, then link the required native artifacts. macOS is not supported. |
+| **Android** | Package the JNI libraries required by the Kotlin/Android host and test on target ABIs. |
+| **Verifier server** | Build the Rust HTTP server in `tooling/verifier-server/` and configure the Go verifier binary path. |
+| **Recursive verifier** | Use the Go module in `recursive-verifier/` with the `params_for_recursive_verifier` and `r1cs.json` exported by the CLI. |
+
+All of these require a source checkout.
+
+## Verify your setup
+
+A healthy setup satisfies all of these checks:
+
+- `provekit-cli --help` (or `cargo run --release --bin provekit-cli -- --help` for source builds) prints the CLI help text.
+- The [Quickstart](/getting-started/quickstart/) completes with `verify` returning exit code `0`.
+- For docs work: `pnpm check` and `pnpm build` both pass inside `docs/`.
diff --git a/docs/src/content/docs/getting-started/quickstart.mdx b/docs/src/content/docs/getting-started/quickstart.mdx
new file mode 100644
index 000000000..b3b66ccc0
--- /dev/null
+++ b/docs/src/content/docs/getting-started/quickstart.mdx
@@ -0,0 +1,79 @@
+---
+title: Quickstart
+description: Run the end-to-end ProveKit proof flow against the checked-in example circuit.
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+This quickstart takes you through the shortest reliable path through ProveKit: compile the checked-in `noir-examples/basic` circuit, generate a proof from its prover inputs, and verify the proof locally. About five minutes.
+
+You'll need `provekit-cli` available (`cargo install provekit-cli` or a source checkout) and a copy of `noir-examples/basic/` to run against. See [Installation and setup](/getting-started/installation/) if either is missing.
+
+The commands below assume `provekit-cli` is on your PATH. **Source-checkout users:** substitute `cargo run --release --bin provekit-cli --` for `provekit-cli` in every command.
+
+## Run your first proof
+
+
+1. Enter the example Noir package.
+
+ ```sh
+ cd noir-examples/basic
+ ```
+
+2. Prepare the prover and verifier keys.
+
+ ```sh
+ provekit-cli prepare
+ ```
+
+3. Generate a proof from `Prover.toml`.
+
+ ```sh
+ provekit-cli prove
+ ```
+
+4. Verify the proof locally.
+
+ ```sh
+ provekit-cli verify
+ ```
+
+
+
+
+## What each command reads and writes
+
+| Step | Command | Reads | Writes |
+| :--- | :--- | :--- | :--- |
+| 1 | `prepare` | `Nargo.toml`, `src/main.nr`, Noir dependencies | `basic.pkp`, `basic.pkv`, Noir `target/` artifacts |
+| 2 | `prove` | `basic.pkp`, `Prover.toml` | `proof.np` |
+| 3 | `verify` | `basic.pkv`, `proof.np` | exit status only, no output file |
+
+`basic.pkp`, `basic.pkv`, and `proof.np` are generated. Don't commit them unless a downstream integration explicitly relies on checked-in fixtures.
+
+## Generated artifacts
+
+| Artifact | Purpose | Default location |
+| :--- | :--- | :--- |
+| `basic.pkp` | Prover key written by `prepare`. | Named after the enclosing Noir package. |
+| `basic.pkv` | Verifier key written by `prepare`. | Named after the enclosing Noir package. |
+| `proof.np` | Proof written by `prove`, consumed by `verify`. | `./proof.np` (override with `prove --out`). |
+| `Prover.toml` | Prover inputs for the example circuit. | Checked into `noir-examples/basic/`. |
+
+## Clean up
+
+Return the example directory to a source-only state:
+
+```sh
+rm -f basic.pkp basic.pkv proof.np
+rm -rf target
+```
+
+## Where to go next
+
+- [End-to-end overview](/e2e/overview/), working-directory and artifact rules across every integration path.
+- [Generate artifacts](/e2e/generate-artifacts/), explicit output paths, hash choices, and recursive-verifier exports.
+- [Artifact lifecycle](/concepts/artifact-lifecycle/), pairing, regeneration, and custody rules before sharing files.
+- [Common errors](/troubleshooting/common-errors/), if `prepare`, `prove`, or `verify` can't find expected files.
diff --git a/docs/src/content/docs/getting-started/tutorial.mdx b/docs/src/content/docs/getting-started/tutorial.mdx
new file mode 100644
index 000000000..df42dcf52
--- /dev/null
+++ b/docs/src/content/docs/getting-started/tutorial.mdx
@@ -0,0 +1,194 @@
+---
+title: "Tutorial: prove without revealing"
+description: Build a zero-knowledge "I know a secret that hashes to a public commitment" flow end-to-end, Noir circuit, ProveKit CLI, and a Rust verifier you control.
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+This tutorial walks you through the smallest meaningful zero-knowledge application: a prover convinces a verifier that they know a secret without revealing it. You'll write the Noir circuit, prepare keys, generate a proof, and verify it from your own Rust program.
+
+By the end you'll understand the full ProveKit loop and be ready to apply it to real workloads like credential verification, vote eligibility, or off-chain computation attestation.
+
+**Time:** about 20 minutes. **Prerequisites:** a working ProveKit checkout, see [Installation](/getting-started/installation/).
+
+## What you'll build
+
+A circuit that proves *"I know two field elements whose Poseidon2 hash equals this public commitment"*, and a Rust program that loads the resulting proof, verifies it, and prints the public commitment.
+
+In a real application the "two field elements" might be the components of a private identity key; the "public commitment" is the hash that gets stored on-chain or in a server. Verification proves the prover holds the secret without revealing it.
+
+## Step 1: scaffold the Noir circuit
+
+
+1. Create a new Noir package inside the repo for this tutorial.
+
+ ```sh
+ cd noir-examples
+ mkdir secret-knowledge && cd secret-knowledge
+ ```
+
+2. Add a `Nargo.toml` that pulls in the `poseidon2` dependency.
+
+ ```toml title="Nargo.toml"
+ [package]
+ name = "secret_knowledge"
+ type = "bin"
+ authors = [""]
+ compiler_version = ">=0.22.0"
+
+ [dependencies]
+ poseidon2 = { tag = "v0.5.0-beta.0", git = "https://github.com/TaceoLabs/noir-poseidon", directory = "poseidon2" }
+ ```
+
+3. Write the circuit. Public inputs go in the function signature *after* private ones, but you mark public inputs with the `pub` keyword.
+
+ ```rust title="src/main.nr"
+ use dep::poseidon2;
+
+ fn main(secret: [Field; 2], commitment: pub Field) {
+ let computed = poseidon2::bn254::hash_2(secret);
+ assert(computed == commitment);
+ }
+ ```
+
+ This circuit enforces one constraint: that `poseidon2(secret) == commitment`. Because `secret` is private and `commitment` is public, the resulting proof says "the prover knows a secret that hashes to commitment", and nothing else.
+
+
+## Step 2: pick inputs
+
+You need a valid `(secret, commitment)` pair where `commitment == poseidon2(secret)`. Computing Poseidon2 outside the circuit takes an off-circuit hash implementation; for this tutorial, reuse a precomputed pair from `noir-examples/basic`:
+
+```toml title="Prover.toml"
+secret = ["1", "2"]
+commitment = "0x0e90c132311e864e0c8bca37976f28579a2dd9436bbc11326e21ec7c00cea5b2"
+```
+
+That commitment is Poseidon2(BN254) of `[1, 2]`, already verified by the canonical basic example. Once you've completed the tutorial, swap in your own `(secret, commitment)` pair generated however you like.
+
+Then compile the circuit:
+
+```sh
+cargo run --release --bin provekit-cli -- prepare
+```
+
+`prepare` reads only the Noir source, not `Prover.toml`. It writes `secret_knowledge.pkp` (prover key) and `secret_knowledge.pkv` (verifier key) into the package directory.
+
+## Step 3: prove and verify with the CLI
+
+
+1. Generate a proof. ProveKit reads the prover key (`.pkp`) and your inputs, and writes `proof.np`.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- prove
+ ```
+
+2. Verify it locally, this is the fastest sanity check before integrating elsewhere.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- verify
+ ```
+
+ Exit code `0` means the proof verifies. If you see a failure, the most common cause is a stale `.pkp` / `.pkv` pair, re-run `prepare`.
+
+3. Inspect the public inputs the proof actually exposes.
+
+ ```sh
+ cargo run --release --bin provekit-cli -- show-inputs --hex \
+ secret_knowledge.pkv \
+ proof.np
+ ```
+
+ You'll see only `commitment`, the secret never appears.
+
+
+
+
+## Step 4: verify from your own Rust program
+
+The CLI is great for development. In production, the verifier usually runs inside *your* code, a backend service, a smart-contract gateway, a CLI tool. Let's verify the same proof from a standalone Rust binary.
+
+
+1. Create a new Cargo project alongside (not inside) the repo.
+
+ ```sh
+ cd ../.. # back to repo root
+ cd .. # leave the provekit directory
+ cargo new --bin secret-verifier
+ cd secret-verifier
+ ```
+
+2. Add ProveKit's published verifier crate.
+
+ ```toml title="Cargo.toml"
+ [package]
+ name = "secret-verifier"
+ version = "0.1.0"
+ edition = "2021"
+
+ [dependencies]
+ provekit-common = "1.0.0"
+ provekit-verifier = "1.0.0"
+ ```
+
+3. Write the verifier.
+
+ ```rust title="src/main.rs"
+ use std::path::Path;
+ use provekit_common::{file::read, NoirProof, Verifier};
+ use provekit_verifier::Verify;
+
+ fn main() -> anyhow::Result<()> {
+ // Adjust these paths to wherever you ran `prepare`/`prove`.
+ let pkv_path = Path::new("../provekit/noir-examples/secret-knowledge/secret_knowledge.pkv");
+ let proof_path = Path::new("../provekit/noir-examples/secret-knowledge/proof.np");
+
+ let mut verifier: Verifier = read(pkv_path)?;
+ let proof: NoirProof = read(proof_path)?;
+
+ verifier.verify(&proof)?;
+ println!("Proof verified. Prover knows a Poseidon2 preimage of the published commitment.");
+ Ok(())
+ }
+ ```
+
+4. Add `anyhow` and run it.
+
+ ```sh
+ cargo add anyhow
+ cargo run --release
+ ```
+
+ You should see `Proof verified.`
+
+
+## What you proved
+
+A user with a `Prover.toml` can convince anyone with the matching `.pkv` and `proof.np` that they know two field elements that hash to the commitment, **without ever transmitting those elements**.
+
+That's the whole zero-knowledge claim. Everything else in ProveKit is plumbing around this shape: bigger circuits, more complex public input contracts, different hash configurations, different transport layers.
+
+## Extend this circuit
+
+Try these next:
+
+- **Make the commitment a Merkle root**, then proving `secret` hashes to *some leaf* of the tree, without revealing which leaf. See the [`noir-passport`](https://github.com/worldfnd/provekit/tree/main/noir-examples/noir-passport) example for a production-scale instance.
+- **Add a nullifier**, bind the secret to a context (election ID, session, chain) and expose the resulting hash as a public input. See [Designing circuits for ProveKit](/concepts/designing-circuits/) for ProveKit-specific mechanics.
+- **Verify in a browser**, load the same `.pkv` bytes from a `Uint8Array` and verify in WASM. See [JS/TypeScript end-to-end](/e2e/js-typescript/).
+- **Push to chain**, export recursive-verifier inputs and produce a Groth16 outer proof. See [Recursive verifier](/integrations/overview/#recursive-verifier--gnark).
+
+## Clean up
+
+```sh
+cd ../provekit/noir-examples/secret-knowledge
+rm -f secret_knowledge.pkp secret_knowledge.pkv proof.np
+rm -rf target
+```
+
+## Where to go next
+
+- [Proving flow](/concepts/proving-flow/), the conceptual pipeline behind what you just ran.
+- [Artifact lifecycle](/concepts/artifact-lifecycle/), the rules for treating `.pkp`/`.pkv`/`proof.np` as deployment artifacts.
+- [Integrations overview](/integrations/overview/), pick the host language where ProveKit will run in your system.
+- [Designing circuits for ProveKit](/concepts/designing-circuits/), ProveKit-specific mechanics for shaping your circuit.
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
new file mode 100644
index 000000000..0e5329914
--- /dev/null
+++ b/docs/src/content/docs/index.mdx
@@ -0,0 +1,102 @@
+---
+title: ProveKit Documentation
+description: Compile Noir circuits to R1CS, generate WHIR proofs, and verify them anywhere, from the CLI to browsers, mobile apps, services, and on-chain via a recursive verifier.
+template: splash
+hero:
+ tagline: A zero-knowledge proof toolkit for shipping Noir circuits to production, across native, browser, mobile, server, and on-chain verification.
+ actions:
+ - text: Run the quickstart
+ link: /getting-started/quickstart/
+ icon: right-arrow
+ variant: primary
+ - text: What is ProveKit?
+ link: /concepts/what-is-provekit/
+ icon: open-book
+ - text: View on GitHub
+ link: https://github.com/worldfnd/provekit
+ icon: external
+---
+
+import { Aside, Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+
+ProveKit turns a Noir circuit into a verifiable WHIR proof, then lets you verify that proof wherever you need it, locally, in a Rust service, in the browser, on iOS or Android, or on-chain through a Groth16 recursive verifier.
+
+
+## See it in three commands
+
+From a fresh checkout of the [ProveKit repository](https://github.com/worldfnd/provekit):
+
+```sh
+cd noir-examples/basic
+cargo run --release --bin provekit-cli -- prepare # compile circuit → .pkp + .pkv
+cargo run --release --bin provekit-cli -- prove # .pkp + Prover.toml → proof.np
+cargo run --release --bin provekit-cli -- verify # .pkv + proof.np → exit 0
+```
+
+That's the whole proving pipeline. Every other integration, Rust, WASM, mobile, is the same flow against the same artifacts. [Walk through it step by step →](/getting-started/quickstart/)
+
+## Get started
+
+
+
+ Prepare keys, generate `proof.np`, and verify it locally using the `noir-examples/basic` circuit.
+
+ [Run the quickstart →](/getting-started/quickstart/)
+
+
+ A developer-friendly introduction to zero-knowledge proofs and the problems this toolkit solves.
+
+ [Read the overview →](/concepts/what-is-provekit/)
+
+
+ Choose where ProveKit runs in your system, CLI, Rust, WASM, mobile, or recursive.
+
+ [Integrations overview →](/integrations/overview/)
+
+
+ The provenance, evidence, and operational controls required before accepting proofs in production.
+
+ [Review the checklist →](/reference/production-checklist/)
+
+
+
+## Host integrations
+
+ProveKit runs the same proof artifacts across server, browser, and mobile. For the full menu, including CLI, HTTP verifier, and recursive paths, see [Integrations overview](/integrations/overview/).
+
+
+
+
+
+
+## Core artifacts at a glance
+
+
+
.pkpProver key, produced by `prepare`, consumed by `prove`.
+
.pkvVerifier key, produced by `prepare`, consumed by `verify` and recursive export.
+
proof.npWHIR proof, produced by `prove`, consumed by every verification path.
+
r1cs.jsonRecursive-verifier R1CS, exported from a matching `.pkv` and proof.
+
+
+Every artifact is bound to a specific circuit, commit, compiler backend, and hash choice. Treat them as versioned deployment objects. See [Artifact lifecycle](/concepts/artifact-lifecycle/) for the full pairing rules.
+
+
diff --git a/docs/src/content/docs/integrations/overview.mdx b/docs/src/content/docs/integrations/overview.mdx
new file mode 100644
index 000000000..0af704da7
--- /dev/null
+++ b/docs/src/content/docs/integrations/overview.mdx
@@ -0,0 +1,241 @@
+---
+title: Integrations overview
+description: Pick the integration path that matches where ProveKit will prove or verify in your system.
+---
+
+import { Aside, Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components';
+
+ProveKit ships six integration paths: the CLI, native Rust crates, WebAssembly, a C FFI for mobile, an HTTP verifier service, and a Go/gnark recursive verifier. Choose the path that matches where proof generation or verification needs to run, then keep artifact provenance consistent across boundaries.
+
+**Rust API:** [`provekit-common`](https://docs.rs/provekit-common) · [`provekit-prover`](https://docs.rs/provekit-prover) · [`provekit-verifier`](https://docs.rs/provekit-verifier). New here? Start with [What is ProveKit?](/concepts/what-is-provekit/) and the [glossary](/reference/glossary/).
+
+## The same flow, every host
+
+Every integration runs the same three-step pipeline. Here's what verifying a proof looks like in each:
+
+
+
+```sh
+cargo run --release --bin provekit-cli -- verify \
+ --verifier app.pkv \
+ --proof proof.np
+# exit 0 = valid
+```
+
+
+```rust
+use provekit_common::{file::read, NoirProof, Verifier};
+use provekit_verifier::Verify;
+
+let mut verifier: Verifier = read("app.pkv")?;
+let proof: NoirProof = read("proof.np")?;
+verifier.verify(&proof)?;
+```
+
+
+```ts
+import { Backend, Verity } from "@atheon/verity";
+
+const verity = await Verity.create(Backend.ProveKit);
+const verifier = await verity.loadVerifier(pkvBytes);
+const valid = await verifier.verify(proof);
+```
+
+
+```swift
+import Verity
+
+let verity = try Verity(backend: .provekit)
+let verifier = try verity.loadVerifier(from: "app.pkv")
+let valid = try verifier.verify(proof: proof)
+```
+
+
+```kotlin
+import xyz.atheon.verity.*
+
+val verity = Verity(Backend.PROVEKIT)
+val verifier = verity.loadVerifier("app.pkv")
+verifier.use { v -> check(v.verify(proof)) }
+```
+
+
+```sh
+curl -X POST http://verifier:3000/verify -d '{
+ "pkvUrl": "https://example.com/app.pkv",
+ "r1csUrl": "https://example.com/r1cs.json",
+ "np": { /* NoirProof JSON */ }
+}'
+```
+
+
+
+The same `.pkv` and proof artifact drive every path. Pick by where you want verification to live.
+
+## Decision table
+
+| Path | Repo location | Use when | Primary artifacts |
+| :--- | :--- | :--- | :--- |
+| **CLI** | `tooling/cli/` | You want a command-line prepare/prove/verify workflow or CI artifact generation. | `.pkp`, `.pkv`, `proof.np`, `r1cs.json`, recursive params. |
+| **Rust crates** | `provekit/*`, `tooling/*` | You are embedding ProveKit in Rust services, tools, or tests. | Rust `Prover`, `Verifier`, `NoirProof` values plus `.pkp` / `.pkv` files. |
+| **WASM** | `tooling/provekit-wasm/` | You need proving or verification in a browser or Node.js application. | `.pkp` / `.pkv` bytes, witness map, JSON proof bytes/object. |
+| **FFI** | `tooling/provekit-ffi/` | You need C ABI bindings for Swift/iOS, Kotlin/Android, Python, or another host. | Native library, `provekit_ffi.h`, `.pkp`, TOML inputs, proof file or JSON buffer. |
+| **Verifier server** | `tooling/verifier-server/` | You need an HTTP API that downloads artifacts and orchestrates verification. | `pkvUrl`, `r1csUrl`, JSON `NoirProof`, optional Groth16 `pkUrl` / `vkUrl`. |
+| **Recursive verifier** | `recursive-verifier/` | You need Go/gnark recursive verification and Groth16 wrapping. | `params_for_recursive_verifier`, `r1cs.json`, optional proving/verifying keys. |
+
+## Choose by runtime
+
+
+
+ Use the CLI for auditable release artifact generation and CI checks.
+
+
+ Embed the crates when the service can own artifact loading, verification policy, and the proof/key lifecycle directly.
+
+
+ Use the WASM bindings when proof generation or verification has to happen in JavaScript.
+
+
+ Use the FFI-backed Swift or Kotlin SDK when native packaging, memory limits, and deterministic cleanup matter.
+
+
+
+## Artifact rules
+
+Every integration path follows the same rules:
+
+1. Run `prepare` for the exact circuit source, branch, compiler backend, and hash configuration you plan to deploy.
+2. Keep the generated `.pkp` and `.pkv` together. Never pair a prover key from one build with a verifier key from another.
+3. Generate proofs from inputs intended for that circuit and key pair.
+4. Verify before crossing any trust boundary.
+5. Regenerate recursive-verifier artifacts after the verifier key, proof, circuit, or hash choice changes.
+6. Treat `.pkp`, `.pkv`, proofs, public inputs, `r1cs.json`, and recursive params as versioned deployment artifacts.
+
+
+
+## CLI-driven services
+
+Use the CLI when CI or a build job is responsible for producing deployment artifacts.
+
+```sh
+mkdir -p artifacts
+cargo run --release --bin provekit-cli -- prepare \
+ . \
+ --pkp artifacts/app.pkp \
+ --pkv artifacts/app.pkv
+cargo run --release --bin provekit-cli -- prove \
+ --prover artifacts/app.pkp \
+ --input Prover.toml \
+ --out artifacts/proof.np
+cargo run --release --bin provekit-cli -- verify \
+ --verifier artifacts/app.pkv \
+ --proof artifacts/proof.np
+```
+
+Prefer explicit output paths in automation. Default key names depend on the enclosing Nargo package, which can be surprising in multi-package workspaces.
+
+## Rust embedding
+
+Embed the crates when your application can link ProveKit directly.
+
+- `provekit-common`, shared proof, key, R1CS, file, and serialization types.
+- `provekit-r1cs-compiler`, lowers Noir ACIR into ProveKit proof schemes.
+- `provekit-prover`, exposes the `Prove` trait for proof generation.
+- `provekit-verifier`, exposes the `Verify` trait for proof verification.
+- `provekit-gnark`, writes the Rust-side recursive-verifier bridge artifacts.
+
+Operational notes:
+
+- Native verifier values are consumed by the `Verify` implementation; reload or clone verifier state when verifying multiple proofs in one process.
+- Match CLI behavior in tests by reading and writing artifacts through `provekit_common::file` helpers.
+- Keep the hash configuration explicit in services so deployments don't drift on a changed default.
+
+## WASM / JavaScript
+
+`tooling/provekit-wasm` exports the browser-facing bindings:
+
+| Export | Purpose |
+| :--- | :--- |
+| `initPanicHook()` | Install better panic reporting in the browser console. |
+| `initThreadPool(n)` | Initialize the Rayon-backed WASM thread pool. |
+| `new Prover(pkpBytes)` | Load a `.pkp` prover artifact from binary or JSON bytes. |
+| `Prover.getCircuit()` | Return Noir circuit JSON for `@noir-lang/noir_js`. Noir provers only. |
+| `Prover.getNumConstraints()` | Return the prepared circuit constraint count. |
+| `Prover.getNumWitnesses()` | Return the prepared circuit witness count. |
+| `Prover.proveBytes(witnessMap)` | Generate a JSON-serialized proof as bytes. Consumes the prover. |
+| `Prover.proveJs(witnessMap)` | Generate a proof as a JavaScript value. Consumes the prover. |
+| `new Verifier(pkvBytes)` | Load a `.pkv` verifier artifact from binary or JSON bytes. |
+| `Verifier.verifyBytes(proofJson)` | Verify proof JSON bytes. Verifier is reusable. |
+| `Verifier.verifyJs(proof)` | Verify a proof JavaScript value. Verifier is reusable. |
+
+Witness maps may be `Map` values or plain objects like `{ "0": "0x..." }`. Values must be hex strings that fit BN254 field elements.
+
+## FFI / mobile hosts
+
+`tooling/provekit-ffi` provides a C ABI for hosts that can't link Rust directly.
+
+| Function | Purpose |
+| :--- | :--- |
+| `pk_init()` | Initialize ProveKit before any other FFI call. |
+| `pk_prove_to_file(prover_path, input_path, out_path)` | Generate a proof and write it to a file. |
+| `pk_prove_to_json(prover_path, input_path, out_buf)` | Generate a JSON proof buffer. |
+| `pk_free_buf(buf)` | Free buffers returned by FFI calls. |
+| `pk_set_allocator(alloc, dealloc)` | Configure host allocator callbacks before initialization. |
+| `pk_configure_memory(limit, file_backed, path)` | Configure the mmap allocator before `pk_init()`. |
+| `pk_get_memory_stats(...)` | Read RAM, swap, and peak memory statistics. |
+
+Swift, Kotlin, and Python examples live in `tooling/provekit-ffi/README.md`. For mobile builds, compile the static library for each target architecture and ship `tooling/provekit-ffi/include/provekit_ffi.h` alongside the resulting libraries.
+
+## Verifier server
+
+`tooling/verifier-server` exposes an Axum HTTP service:
+
+| Route | Method | Purpose |
+| :--- | :--- | :--- |
+| `/health` | `GET` | Return server health, version, and timestamp. |
+| `/verify` | `POST` | Verify a JSON proof using downloaded artifacts. |
+
+A verification request looks like:
+
+```json
+{
+ "pkvUrl": "https://example.com/verifier.pkv",
+ "r1csUrl": "https://example.com/r1cs.json",
+ "pkUrl": "https://example.com/proving_key.bin",
+ "vkUrl": "https://example.com/verification_key.bin",
+ "np": { "proof": "NoirProof JSON fields" },
+ "verificationParams": { "maxVerificationTime": 300 },
+ "metadata": { "requestId": "request-123" }
+}
+```
+
+`pkUrl`, `vkUrl`, `verificationParams`, and `metadata` are optional. Artifact URLs must use HTTP or HTTPS. The server defaults to one concurrent verification and a 10 MiB request body limit, tune both through the `VERIFIER_*` environment variables documented in `tooling/verifier-server/README.md`.
+
+## Recursive verifier / gnark
+
+Use `generate-gnark-inputs` to bridge a ProveKit verifier key and proof into the Go/gnark recursive verifier:
+
+```sh
+cargo run --release --bin provekit-cli -- generate-gnark-inputs \
+ artifacts/app.pkv \
+ artifacts/proof.np \
+ --params artifacts/params_for_recursive_verifier \
+ --r1cs artifacts/r1cs.json
+```
+
+Then run the Go CLI or server from `recursive-verifier/` with those files. If you omit the recursive proving and verifying keys, the Go tool can generate them for development, production deployments should manage trusted-setup keys explicitly.
+
+## Production readiness
+
+Before shipping any integration, complete the [Production checklist](/reference/production-checklist/). At a minimum: pin the branch or release, record artifact provenance, define who may generate keys, configure verifier-server limits, and add an end-to-end regeneration test in CI.
+
+## Platform guides
+
+The platform pages cover the supported API paths, default artifact flow, and build constraints. Run the snippets inside a real app or test target before relying on them.
+
+- **[Rust](/e2e/rust/)**, direct crate integration for services, tools, and tests.
+- **[JS / TypeScript](/e2e/js-typescript/)**, browser and Node.js usage via the ProveKit WASM backend.
+- **[Swift](/e2e/swift/)**, Swift Package Manager integration with source-only, native, and release modes.
+- **[Kotlin](/e2e/kotlin/)**, Android integration with JNI packaging guidance.
diff --git a/docs/src/content/docs/reference/changelog.mdx b/docs/src/content/docs/reference/changelog.mdx
new file mode 100644
index 000000000..49c122065
--- /dev/null
+++ b/docs/src/content/docs/reference/changelog.mdx
@@ -0,0 +1,89 @@
+---
+title: Changelog
+description: A curated record of substantive changes to ProveKit. Grouped by theme, derived from the Git history on the `main` and `v1` branches.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Tagged releases live on [GitHub Releases](https://github.com/worldfnd/provekit/releases) — that's the authoritative record of what's in each version. This page summarizes themes alongside the release notes, plus the rolling work on `main` between tags. For the exhaustive log, use the [GitHub commit history](https://github.com/worldfnd/provekit/commits/main).
+
+
+
+## v1.0.0
+
+The first tagged release of ProveKit. Crates published to crates.io: `provekit-cli`, `provekit-common`, `provekit-prover`, `provekit-verifier`, `provekit-r1cs-compiler`, `provekit-gnark`, `provekit-ffi`, `provekit-wasm`.
+
+See the [v1.0.0 release notes](https://github.com/worldfnd/provekit/releases/tag/v1.0.0) for the full change list.
+
+## Unreleased (rolling, `main`)
+
+### Breaking changes
+
+- **CLI subcommand renamed.** `circuit_stats` → `circuit-stats`. Update scripts and CI jobs.
+- **Hash configuration is stored on `WhirR1CSScheme`.** Process-global hash drift is no longer possible; consumers reading scheme types directly should fetch the hash from the scheme instead of process state.
+- **Digest hashers unified, V1 domain separation tag added.** Proof hashing is now consistent across paths.
+
+### CLI
+
+- **Zero-arg defaults for `prepare` / `prove` / `verify`.** Each command runs from the enclosing Noir package without explicit paths, with full `--pkp` / `--pkv` / `--prover` / `--verifier` / `--input` / `--out` overrides still available.
+- Improved CSP benchmark scripts to match the new `prove` / `verify` flags.
+
+### Performance
+
+- **Poseidon2 hot path:** inlined permutation helpers, squaring S-box, zero-allocation byte/field conversion, in-place API.
+- **Native Keccak benchmarks** rebalanced for lower witness count.
+- **NTT** picked up an explicit `roots` method, b51-mode NTT enabled in WASM, and a canonicalized comparison test.
+
+### Hash and proof system
+
+- **Poseidon2 hash config** is now selectable via `--hash poseidon2` alongside Skyscraper, SHA-256, Keccak, and Blake3.
+- **Public-input hashing** is aligned with the chosen `HashConfig`. Mixing public-input encoding across hash choices was previously possible and is now prevented.
+- **Process-global hash drift eliminated.** Hash configuration is stored on the scheme.
+
+### Benchmarks
+
+- **Ethproofs CSP benchmark suite added** under `noir-examples/csp-benchmarks/`. Targets: SHA-256 (128–2048 bytes), Keccak-256 (128–2048 bytes), Poseidon (states 2–16), Poseidon2 (states 2–16), and ECDSA over secp256r1.
+- **Sticky CSP PR comment** in CI reports constraints, witnesses, and deltas vs. the `main` baseline.
+
+### Compiler and tests
+
+- **Noir blackbox hash paths** are preferred where ProveKit lowers them efficiently. The CSP suite documents where native Noir paths win instead.
+- **Verifier-visible public input equalities** are preserved by Noir prepare.
+
+### Documentation
+
+- Restructured docs site (Astro Starlight) with a Diátaxis-aligned IA: Start here / Build and integrate / Concepts / Reference / Operations.
+- Added: *What is ProveKit?* explainer, *Tutorial* (private-knowledge proof), *Designing circuits for ProveKit* (ProveKit-specific circuit mechanics), *Performance*, *Comparison*, *FAQ*, *Examples catalog*, *FFI error codes*, *Starter templates*, *Changelog*.
+
+### WASM
+
+- Re-routed the wasm-demo through Verity without changing the ProveKit UX surface.
+- Raised the SHA-256 demo circuit workload to better exercise the in-browser path.
+
+### Acknowledged work in progress
+
+These are tracked, not yet shipped:
+
+- Tagged releases and SemVer guarantees.
+- Public audit certification.
+- Native (non-Groth16) recursive verification.
+- Hosted rustdoc and generated C-header reference linked from the docs.
+- Release binaries for `provekit-cli`.
+- An official starter-app repository (see [Starter templates](/reference/starter-template/) for the assembly recipe meanwhile).
+
+## Branch policy recap
+
+| Branch | Purpose | Compatibility |
+| :--- | :--- | :--- |
+| `v1` | Current stable interface. | Treat as the reproducibility target. |
+| `main` | Active development. | Formats and APIs may change between commits. |
+
+See [Project status and versioning](/reference/project-status/) for the full policy.
+
+## Where this changelog comes from
+
+Per-release content comes from [GitHub Releases](https://github.com/worldfnd/provekit/releases). The "Unreleased" section above is curated from substantive commits on `main` between tags. It is *not* a complete log; every change is in Git, but most don't belong in a user-facing changelog. The selection criterion: would a user who upgraded benefit from knowing this?
+
+If you spot a missing change that affects users, open an issue or PR against `docs/src/content/docs/reference/changelog.mdx`.
diff --git a/docs/src/content/docs/reference/comparison.mdx b/docs/src/content/docs/reference/comparison.mdx
new file mode 100644
index 000000000..8202cef3c
--- /dev/null
+++ b/docs/src/content/docs/reference/comparison.mdx
@@ -0,0 +1,70 @@
+---
+title: How ProveKit compares
+description: Side-by-side comparison of ProveKit with other zero-knowledge proof systems, Halo2, Plonky2, Circom + SnarkJS, RISC Zero.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+There is no single "best" ZK proof system, choices depend on the frontend you want, the verification target, audit posture, and operational tooling. This page summarizes how ProveKit positions itself against the most common alternatives.
+
+
+
+## Comparison matrix
+
+| Dimension | **ProveKit** | Halo2 (PSE / zcash) | Plonky2 | Circom + SnarkJS / RapidSnark | RISC Zero |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Frontend** | Noir | Rust DSL (in-circuit `Region`/`Gate` API) | Rust DSL | Circom | Rust binary (zkVM) |
+| **Proof system** | WHIR + Spartan-style sumcheck | Plonkish + IPA / KZG | FRI-based PLONK | Groth16 (default) | STARK + Groth16 wrap |
+| **Trusted setup (base proof)** | None | None (IPA) / per-circuit (KZG) | None | Per-circuit ceremony | None |
+| **Post-quantum secure (base proof)** | Yes (hash-based WHIR) | No (IPA = discrete log; KZG = pairings) | Yes (FRI / hash-based) | No (pairings) | Yes (FRI-based STARK) |
+| **Post-quantum secure (on-chain wrap)** | No (Groth16 over BN254) | KZG: no; direct IPA verification not standard on Ethereum | No (Groth16 wrap) | No | No (Groth16 wrap) |
+| **Field** | BN254 | BN254 / Pasta | Goldilocks | BN254 / BLS12-381 | Baby Bear → BN254 wrap |
+| **On-chain target** | Groth16 wrap via Go/gnark | Direct on Ethereum (KZG mode) | Wrap to Groth16 | Direct on Ethereum | Groth16 wrap |
+| **Native host support** | CLI, Rust, WASM, FFI, HTTP server, recursive | Rust | Rust | JS/WASM, native binary | Rust, WASM |
+| **Mobile path** | First-class (Swift + Kotlin SDKs via FFI) | DIY | DIY | DIY | Experimental |
+| **Recursive verification** | Via gnark Groth16 wrapper | Native | Native (fast) | Limited | Native (zkVM-style) |
+| **Audit status** | No public audit yet | Multiple audits | Audited (Polygon) | Multiple audits | Multiple audits |
+| **License** | MIT | MIT / Apache-2 | Apache-2 / MIT | GPL-3 / MIT components | Apache-2 |
+| **Best when** | You want Noir + production-shaped runtime + cheap EVM verification | You want maximum control inside Ethereum tooling | You want fast recursion in pure Rust | You're already invested in Circom or need legacy EVM verifiers | You want to prove arbitrary Rust without writing a circuit |
+
+## Where ProveKit shines
+
+- **Noir frontend.** Higher-level than Halo2's in-circuit API, less constrained than Circom's signal-based model, type-checked unlike most circuit DSLs.
+- **Cross-host runtime out of the box.** CLI, Rust, WASM, FFI, mobile, and recursive paths from one codebase. Most alternatives leave host integration to you.
+- **No trusted setup for the base proof.** WHIR's commitment scheme avoids per-circuit ceremonies; only the optional Groth16 outer wrap involves one.
+- **Production-shaped tooling.** Versioned artifacts, hash-choice control, public-input inspection, memory configuration on mobile, and a verifier service with concurrency controls.
+
+## Where ProveKit is weaker today
+
+- **Audit maturity.** No public audit certification yet. Halo2, Plonky2, and Circom-based stacks have multiple audits behind them.
+- **Recursive verification.** Native recursion isn't yet a first-class operation, the path goes through gnark Groth16 wrapping. Plonky2 and RISC Zero have direct recursion built in.
+- **Established benchmarks.** WHIR is newer than PLONK and FRI families; published numbers from competing systems are not directly comparable yet.
+- **Ecosystem.** Noir's ecosystem is younger than Circom's. Reusable libraries (signatures, primitives) are growing but smaller in scope.
+
+## Choosing between them
+
+| If your priority is... | Consider |
+| :--- | :--- |
+| **Ship a credential or attestation app across web + mobile** | ProveKit. The integration story is the differentiator. |
+| **Verify directly on Ethereum without a wrapper** | Halo2 (KZG mode) or Circom + SnarkJS. Mature on-chain verifiers exist. |
+| **Prove arbitrary Rust binaries without a circuit** | RISC Zero. zkVM approach trades constraint efficiency for developer ergonomics. |
+| **Maximize recursion throughput** | Plonky2. Native fast recursion is the headline feature. |
+| **Battle-tested + Ethereum-native** | Halo2. Most production Ethereum ZK stacks lean on it. |
+| **Audit-mature signature schemes** | Circom ecosystem. The largest catalog of audited primitives. |
+
+## What to verify before committing
+
+For any proof system, validate these before building on top:
+
+1. **Run your real circuit through it.** Synthetic benchmarks rarely predict your workload.
+2. **Confirm the verification target.** Where does the verifier run? On-chain? In a phone? In a browser?
+3. **Check audit status.** Has the proof system, the frontend, and the recursive verifier been independently reviewed?
+4. **Test the deployment story.** Versioning, artifact distribution, key management, these are where most ZK projects struggle, regardless of the proof system underneath.
+
+## Related pages
+
+- [What is ProveKit?](/concepts/what-is-provekit/), the ProveKit overview.
+- [FAQ](/reference/faq/), broader Q&A on capabilities and limits.
+- [Performance](/reference/performance/), how to measure ProveKit honestly.
diff --git a/docs/src/content/docs/reference/error-codes.mdx b/docs/src/content/docs/reference/error-codes.mdx
new file mode 100644
index 000000000..b00f1abfa
--- /dev/null
+++ b/docs/src/content/docs/reference/error-codes.mdx
@@ -0,0 +1,86 @@
+---
+title: FFI error codes
+description: Every PKError returned by the ProveKit FFI, what triggers it, and how to recover.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The ProveKit C FFI (`tooling/provekit-ffi/`) returns a `PKError` code on every function call. `PK_SUCCESS` (0) means success; any other value indicates failure. Hosts (Swift, Kotlin, Python, custom C/C++) should branch on the numeric code in production paths.
+
+The codes below are mirrored from [`provekit_ffi.h`](https://github.com/worldfnd/provekit/blob/main/tooling/provekit-ffi/include/provekit_ffi.h).
+
+## Error code reference
+
+| Code | Constant | Meaning | Common causes | Resolution |
+| :--- | :--- | :--- | :--- | :--- |
+| 0 | `PK_SUCCESS` | Success. |, |, |
+| 1 | `PK_INVALID_INPUT` | Invalid input parameters, for example a null pointer where one was required. | Forgot to populate a path string, passed a null buffer, or pre-init memory configuration left `ram_limit_bytes` at `0`. | Validate non-null pointers and required path arguments before the call. Configure memory before `pk_init()`. |
+| 2 | `PK_SCHEME_READ_ERROR` | Failed to read or deserialize the `.pkp` (prover key) file. | Missing file, wrong path, corrupted artifact, or a `.pkp` from an incompatible ProveKit version. | Verify the path through the host filesystem APIs. Confirm the file came from the matching `prepare` run on the deployed branch. |
+| 3 | `PK_WITNESS_READ_ERROR` | Failed to read or parse the witness / input TOML for this circuit. | Wrong file, mismatched circuit ABI, malformed TOML, or incorrect hex encoding in a witness map. | Run `provekit-cli show-inputs` on the corresponding proof to confirm the expected ABI. Validate witness encoding (hex strings ≤ 32 bytes, BN254 field range). |
+| 4 | `PK_PROOF_ERROR` | Proof generation failed inside the prover. | Inputs that don't satisfy the circuit (constraint violation), exhausted memory, or a bug in a witness builder for unusual inputs. | Reproduce with the CLI using the same inputs. If the CLI fails too, the inputs likely don't satisfy the circuit. Otherwise capture stderr and open an issue. |
+| 5 | `PK_SERIALIZATION_ERROR` | Failed to serialize the output (proof bytes or JSON). | Internal serializer failure, often paired with an unexpected allocator or buffer-size condition. | Free intermediate buffers, check `pk_get_memory_stats()` for allocator pressure, and re-run from a clean state. |
+| 6 | `PK_UTF8_ERROR` | UTF-8 conversion error. | A path or string argument contained bytes that don't form valid UTF-8. | Ensure all `const char *` arguments are valid UTF-8 null-terminated strings. |
+| 7 | `PK_FILE_WRITE_ERROR` | Failed to write an output file. | Path doesn't exist, parent directory is read-only, or disk is full. | Create the output directory first. Check permissions. Verify free space on the target volume. |
+
+
+
+## Functions that return error codes
+
+Every FFI entry point that performs work returns a `PKError` (as `int`):
+
+| Function | Purpose | Returns |
+| :--- | :--- | :--- |
+| `pk_init()` | Initialize the library. Call once before any other operation. | `PK_SUCCESS` on success. |
+| `pk_prove_to_file(prover_path, input_path, out_path)` | Generate a proof and write it to a file. | `PK_SUCCESS` or a `PKError` code. |
+| `pk_prove_to_json(prover_path, input_path, *out_buf)` | Generate a proof as a JSON buffer (when built with JSON support). | `PK_SUCCESS` or a `PKError` code. |
+| `pk_configure_memory(ram_limit_bytes, use_file_backed, swap_file_path)` | Configure the mmap allocator. **Must be called before `pk_init()`.** | `PK_SUCCESS` or `PK_INVALID_INPUT`. |
+| `pk_get_memory_stats(*ram_used, *swap_used, *peak_ram)` | Read RAM, swap, and peak memory statistics. | `PK_SUCCESS`. |
+
+`pk_free_buf` and `pk_set_allocator` return `void`.
+
+## Recovery patterns
+
+### Mobile: branch on the error class
+
+```swift
+let status = pk_prove_to_file(proverPath, inputPath, outputPath)
+switch status {
+case Int32(PK_SUCCESS.rawValue):
+ return .success
+case Int32(PK_SCHEME_READ_ERROR.rawValue),
+ Int32(PK_WITNESS_READ_ERROR.rawValue):
+ // Bad input, re-fetch artifacts, validate paths, retry once.
+ return .reloadArtifacts
+case Int32(PK_PROOF_ERROR.rawValue),
+ Int32(PK_SERIALIZATION_ERROR.rawValue):
+ return .failedProof
+default:
+ return .systemError
+}
+```
+
+### Server: distinguish soft and hard failures
+
+`PK_INVALID_INPUT`, `PK_WITNESS_READ_ERROR`, `PK_UTF8_ERROR` are client-shaped, the request was malformed. Return a 4xx HTTP status.
+
+`PK_PROOF_ERROR`, `PK_SERIALIZATION_ERROR`, `PK_FILE_WRITE_ERROR`, and `PK_SCHEME_READ_ERROR` are environment-shaped, your runtime is unhealthy (missing files, allocator pressure, or a real prover bug). Return a 5xx and alert.
+
+### CLI smoke test for any FFI failure
+
+When an FFI host reports an error, the fastest reproduction is the CLI:
+
+```sh
+cargo run --release --bin provekit-cli -- prove --prover circuit.pkp --input Prover.toml
+cargo run --release --bin provekit-cli -- verify --verifier circuit.pkv --proof proof.np
+cargo run --release --bin provekit-cli -- show-inputs --hex circuit.pkv proof.np
+```
+
+If the CLI fails the same way, the artifact set is the problem. If the CLI succeeds, the FFI host integration is.
+
+## Related pages
+
+- [Common errors](/troubleshooting/common-errors/), broader failure diagnosis across CLI, WASM, FFI, and verifier server.
+- [Integrations overview](/integrations/overview/#ffi--mobile-hosts), FFI surface and lifecycle.
+- [Production checklist](/reference/production-checklist/), FFI lifecycle controls before launch.
diff --git a/docs/src/content/docs/reference/examples.mdx b/docs/src/content/docs/reference/examples.mdx
new file mode 100644
index 000000000..b83ad0451
--- /dev/null
+++ b/docs/src/content/docs/reference/examples.mdx
@@ -0,0 +1,109 @@
+---
+title: Examples catalog
+description: Noir circuits shipped with ProveKit, grouped by what they demonstrate.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The [`noir-examples/`](https://github.com/worldfnd/provekit/tree/main/noir-examples) directory contains circuits that exercise ProveKit's compiler and proving pipeline. Some are minimal demos; others are real-world primitives used to benchmark and validate the system end-to-end.
+
+Each example is a self-contained Noir package. To run any of them:
+
+```sh
+cd noir-examples/
+cargo run --release --bin provekit-cli -- prepare
+cargo run --release --bin provekit-cli -- prove
+cargo run --release --bin provekit-cli -- verify
+```
+
+
+
+## Hash primitives
+
+Circuits demonstrating the hash functions ProveKit can prove over.
+
+| Example | What it demonstrates |
+| :--- | :--- |
+| **`basic`** | Poseidon2 BN254 preimage proof, the canonical "hello world" circuit. |
+| **`basic-2`, `basic-3`, `basic-4`** | Progressive Poseidon variations for compiler testing. |
+| **`poseidon2`** | Direct Poseidon2 hashing primitive in isolation. |
+| **`many_poseidons`** | Stress test with many Poseidon hash calls in one circuit. |
+| **`poseidon-rounds`** | Single-round Poseidon decomposition, useful for understanding round structure. |
+| **`sha256`, `noir_sha256`, `noir-native-sha256`** | SHA-256 variants compiled through Noir's black-box and native paths. |
+| **`partial_sha256`** | SHA-256 with a partial preimage, common for incremental hashing patterns. |
+
+## Elliptic curves and signatures
+
+Circuits exercising scalar multiplication, signature schemes, and curve arithmetic.
+
+| Example | What it demonstrates |
+| :--- | :--- |
+| **`babyjubjub`** | Baby Jubjub curve operations, the standard curve for in-circuit ECC over BN254. |
+| **`eddsa_poseidon2`** | EdDSA signature verification using Poseidon2 for hashing. |
+| **`embedded_curve_msm`** | Multi-scalar multiplication on the embedded curve via Noir's intrinsic. |
+| **`native_msm`** | MSM expressed without the embedded-curve intrinsic, heavier circuit, useful for comparisons. |
+| **`msm_conditional`** | Conditional MSM, pick scalars or points at runtime inside the circuit. |
+| **`msm_conditional_nested`** | Nested conditional MSM, demonstrating composition. |
+| **`p256_std`** | P-256 (secp256r1) signature verification over the standard curve. |
+| **`p256_bigcurve`** | P-256 with bigcurve representation, relevant when proving WebAuthn or hardware-attestation signatures. |
+
+## Identity and credentials
+
+Circuits demonstrating real-world identity workflows.
+
+| Example | What it demonstrates |
+| :--- | :--- |
+| **`noir-passport`** | Passport-style credential verification, the foundation for selective disclosure. |
+| **`noir-passport-examples`** | Variations of the passport flow used for testing different selective-disclosure patterns. |
+| **`noir-passport-monolithic`** | Single-circuit version of the passport workflow, useful for understanding the full constraint cost. |
+| **`oprf`** | Oblivious Pseudorandom Function, a primitive used in private set intersection and de-anonymization defenses. |
+
+## Arithmetic primitives
+
+Small circuits that ProveKit uses internally for testing and benchmarking.
+
+| Example | What it demonstrates |
+| :--- | :--- |
+| **`power`** | Modular exponentiation inside a circuit. |
+| **`rangechecks`** | Range constraints, the building block for bounded arithmetic. |
+| **`noir-r1cs-test-programs`** | A suite of programs used by the R1CS compiler's own test harness. |
+
+## Applications
+
+Larger circuits modeled after real applications.
+
+| Example | What it demonstrates |
+| :--- | :--- |
+| **`zkchase`** | A small game-like circuit demonstrating state transitions and rule enforcement. |
+
+## Benchmarks
+
+| Example | What it demonstrates |
+| :--- | :--- |
+| **`csp-benchmarks`** | Constraint system performance benchmarks. Use these as a baseline when measuring circuit cost. |
+
+## Reading an example
+
+Every example follows the same layout:
+
+```
+noir-examples/basic/
+├── Nargo.toml # Noir package metadata + dependencies
+├── Prover.toml # Witness inputs (private + public)
+└── src/
+ └── main.nr # Circuit definition
+```
+
+The `Prover.toml` is the only file you typically edit to change what's being proven, the circuit is fixed; the inputs vary per proof. To inspect what a verified proof actually exposes:
+
+```sh
+cargo run --release --bin provekit-cli -- show-inputs --hex \
+ .pkv \
+ proof.np
+```
+
+## Contributing examples
+
+Pull requests adding new example circuits are welcome. Keep them minimal, focused on one primitive, and accompanied by a `Prover.toml` that produces a verifiable proof out of the box.
diff --git a/docs/src/content/docs/reference/faq.mdx b/docs/src/content/docs/reference/faq.mdx
new file mode 100644
index 000000000..2620561e6
--- /dev/null
+++ b/docs/src/content/docs/reference/faq.mdx
@@ -0,0 +1,123 @@
+---
+title: Frequently asked questions
+description: Common questions about ProveKit's maturity, scope, performance, and how it compares to other ZK systems.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+## Project and maturity
+
+### Is ProveKit production-ready?
+
+ProveKit is under active development. The proof system, key formats, and integration APIs continue to evolve on `main`. The `v1` branch holds the current stable interface, use it for any work where reproducibility matters. The [Production checklist](/reference/production-checklist/) outlines the controls you should have in place before shipping a user-facing workflow.
+
+### Which branch should I use?
+
+| Use `v1` when | Use `main` when |
+| :--- | :--- |
+| Reproducibility, stable formats, and clean upgrades matter. | You are contributing, testing experimental features, or accept regenerating artifacts as formats change. |
+
+See [Project status and versioning](/reference/project-status/) for the full policy.
+
+### Has ProveKit been audited?
+
+There is no public audit certification yet. Treat ProveKit as alpha-grade cryptographic software for the purpose of risk management. The codebase ships with property-based tests, regression tests, and a documented soundness checklist for reviewers in `CLAUDE.md` at the repo root.
+
+### What's the license?
+
+[MIT](https://github.com/worldfnd/provekit/blob/main/LICENSE.md).
+
+## Capabilities and scope
+
+### What proof system does ProveKit use?
+
+A **Spartan-based protocol** with [WHIR](https://github.com/WizardOfMenlo/whir) as the polynomial commitment scheme. Spartan is a SNARK for R1CS that uses sumcheck rounds; WHIR backs those rounds with a hash-based polynomial commitment. No trusted setup for the base proof. The optional recursive verifier wraps proofs in Groth16 for on-chain settlement.
+
+### Is ProveKit post-quantum secure?
+
+The **base proof is post-quantum secure** under conjectured hash-function PQ-security. WHIR's commitment scheme is hash-based, so soundness reduces to the collision resistance of the chosen `--hash` (Skyscraper, SHA-256, Keccak, Blake3, or Poseidon2). Grover's algorithm imposes a quadratic speedup on preimage finding, so 256-bit hashes still retain roughly 128-bit security against a quantum adversary.
+
+The **optional Groth16 recursive wrapper is not post-quantum secure**. It uses pairing-based cryptography over BN254, which Shor's algorithm breaks. If long-term post-quantum security matters in your threat model, verify the base WHIR proof off-chain instead of relying on the Groth16 outer proof as your cryptographic anchor. See [Security and trust model](/concepts/security-model/#cryptographic-assumptions) for the breakdown.
+
+### What's the BN254 curve doing here?
+
+ProveKit's field arithmetic is performed over the BN254 scalar field. BN254 is well-supported on EVM chains, which makes the recursive Groth16 wrapper natural for on-chain verification. You don't interact with the field directly, Noir handles it.
+
+### Can I verify on-chain?
+
+Yes, through the [recursive verifier](/integrations/overview/#recursive-verifier--gnark): export `params_for_recursive_verifier` and `r1cs.json` with `provekit-cli generate-gnark-inputs`, then feed them into the Go/gnark wrapper in `recursive-verifier/`. The wrapper produces a Groth16 outer proof that can be verified by an EVM contract.
+
+### What hash functions are available?
+
+`--hash` accepts `skyscraper` (default, custom-optimized for BN254), `sha256`, `keccak`, `blake3`, and `poseidon2`. The hash is part of the artifact's identity, keys, proofs, and recursive exports made with one hash are not interchangeable with another. See the [CLI overview](/cli/overview/#prepare) for details.
+
+## Performance and limits
+
+### How big a circuit can ProveKit handle?
+
+There is no architectural cap. Practical limits depend on the host: the mobile FFI ships a file-backed mmap allocator so circuits whose witness exceeds device RAM can still prove. For very large circuits, configure memory before initialization (`pk_configure_memory` on FFI, `Verity.configureMemory` on mobile SDKs).
+
+### How long does proving take?
+
+It depends on circuit size, hash choice, and host. The proving pipeline is parallelized with [Rayon](https://github.com/rayon-rs/rayon); SIMD-accelerated BN254 arithmetic gives an extra boost on `aarch64`. The fastest path is `--hash skyscraper` on native Rust; the slowest paths are typically constrained-memory mobile builds. Benchmark your specific circuit before estimating production timing.
+
+### How fast is verification?
+
+Verification is significantly cheaper than proving and runs on every supported host. The verifier server defaults to a single concurrent verification (`VERIFIER_SEMAPHORE_LIMIT=1`) and a 20-minute request timeout (`VERIFIER_REQUEST_TIMEOUT=1200`, `VERIFIER_TIMEOUT_SECONDS=1200`). Per-request `verificationParams.maxVerificationTime` is capped at 300 seconds. Tune all of those for your circuit. WASM verification is reusable: load a `Verifier` once and verify many proofs without rebuilding state.
+
+### Can I prove in the browser?
+
+Yes. The [WASM bindings](/integrations/overview/#wasm--javascript) load `.pkp` bytes, accept a witness map, and produce a JSON proof. Threading depends on `SharedArrayBuffer`; the binding falls back to a single-threaded path when worker setup isn't available. Note: each `Prover` is consumed by one `prove()` call, instantiate a new one per proof.
+
+## Integration
+
+### Do I need to know Rust to use ProveKit?
+
+Only if you embed it through the Rust crates. The CLI is the primary entry point and works with any language that can shell out. The [WASM bindings](/integrations/overview/#wasm--javascript), [Swift SDK](/e2e/swift/), and [Kotlin SDK](/e2e/kotlin/) wrap ProveKit for non-Rust hosts.
+
+### Can I generate `.pkp` and `.pkv` on one machine and use them on another?
+
+Yes, that is the deployment model. Generate keys in CI, record the [provenance](/concepts/artifact-lifecycle/), distribute the verifier key alongside your application, and keep the prover key on the proving host. The artifacts are independent of platform.
+
+### Can I switch hash configurations after deployment?
+
+Only by regenerating every artifact. `.pkp`, `.pkv`, and the resulting proofs are all tied to the chosen hash. Plan hash choice as a versioned decision, not a runtime knob.
+
+### What happens if I modify the circuit?
+
+Every downstream artifact is invalidated, `.pkp`, `.pkv`, proofs, recursive params, and `r1cs.json`. Re-run `prepare` and propagate the new artifacts. The verifier will not accept proofs from the old keys. See [Artifact lifecycle](/concepts/artifact-lifecycle/) for the regeneration rules.
+
+## Comparisons
+
+### How is ProveKit different from raw Noir?
+
+Noir is a circuit language; ProveKit is a proof system, runtime, and deployment toolkit built around it. Noir defines what you want to prove; ProveKit handles the compilation to R1CS, proof generation, verification, and the host-language integrations. You can think of Noir as your source code and ProveKit as your compiler-plus-runtime.
+
+### How does this compare to Halo2, Plonky2, or Circom?
+
+The big differentiators:
+
+- **Noir frontend.** You write circuits in a high-level language with type checking, not at the constraint level.
+- **WHIR backend.** No trusted setup for the base proof; modern verification cost characteristics.
+- **Cross-host runtime.** First-class CLI, Rust, WASM, FFI, server, and recursive paths from one codebase.
+- **Production tooling.** Memory configuration, artifact versioning, hash selection, and a verifier service.
+
+Performance comparisons depend heavily on circuit shape, benchmark for your workload.
+
+### Do I have to use the recursive verifier for on-chain settlement?
+
+You have to use *some* on-chain verifier. ProveKit's path is the Go/gnark wrapper, which produces a Groth16 proof that's cheap to verify on EVM chains. Other recursion targets (other proof systems, other curves) would require separate engineering.
+
+## Getting help
+
+### Where do I report bugs?
+
+Open an issue on the [GitHub repository](https://github.com/worldfnd/provekit/issues). Include the information from the "Still stuck?" section of [Common errors](/troubleshooting/common-errors/#still-stuck) so the maintainers can reproduce.
+
+### Where do I find the source for a specific component?
+
+The [Repository Map](https://github.com/worldfnd/provekit#repository-map) in the root README lists every crate, its purpose, and its path. The CLI lives in `tooling/cli/`, the proof system in `provekit/`, and the recursive verifier in `recursive-verifier/`.
+
+### Is there a changelog?
+
+Yes. Tagged releases live on [GitHub Releases](https://github.com/worldfnd/provekit/releases); each release page is the authoritative record of what changed. The [Changelog](/reference/changelog/) page in these docs summarizes major themes alongside the release notes.
diff --git a/docs/src/content/docs/reference/glossary.mdx b/docs/src/content/docs/reference/glossary.mdx
new file mode 100644
index 000000000..8f951302d
--- /dev/null
+++ b/docs/src/content/docs/reference/glossary.mdx
@@ -0,0 +1,48 @@
+---
+title: Glossary
+description: Common ProveKit, Noir, R1CS, WHIR, artifact, and integration terms.
+---
+
+Use this glossary when reading ProveKit docs, debugging artifacts, or writing integration runbooks.
+
+## A–C
+
+| Term | Meaning |
+| :--- | :--- |
+| **ACIR** | Abstract Circuit Intermediate Representation emitted by Noir before backend-specific lowering. |
+| **Artifact provenance** | The branch, commit, toolchain, lockfile, command line, feature flags, hash choice, and checksum record for a generated file. |
+| **BN254** | Elliptic-curve scalar field used by the current field-element and witness encoding paths. |
+| **Circuit** | The constrained computation being proven. In the default flow it is authored as a Noir package. |
+| **Compiler backend** | The path used by `prepare` to derive a ProveKit proof scheme from Noir source. |
+
+## D–P
+
+| Term | Meaning |
+| :--- | :--- |
+| **FFI** | Foreign Function Interface. ProveKit exposes a C ABI for mobile and native hosts that cannot link Rust directly. |
+| **Hash choice** | The Merkle commitment hash selected by `prepare --hash`: `skyscraper`, `sha256`, `keccak`, `blake3`, or `poseidon2`. |
+| **Noir** | Circuit language used by ProveKit's primary authoring flow. |
+| **PKP** | ProveKit prover key file (`.pkp`), produced by `prepare`, consumed by provers. |
+| **PKV** | ProveKit verifier key file (`.pkv`), produced by `prepare`, consumed by verifiers. |
+| **Proof** | Serialized proof output, `proof.np` from the CLI, or JSON proof values in WASM and server flows. |
+| **Public inputs** | Values intentionally exposed by the circuit and bound into verification. Your application is responsible for interpreting them. |
+
+## R–Z
+
+| Term | Meaning |
+| :--- | :--- |
+| **R1CS** | Rank-1 Constraint System used by the ProveKit proving pipeline. |
+| **Recursive verifier** | Go/gnark wrapper that verifies a ProveKit proof inside an outer Groth16-style workflow. |
+| **`r1cs.json`** | Recursive-verifier R1CS export generated from a matching verifier key and proof. |
+| **`params_for_recursive_verifier`** | Recursive-verifier parameter file generated from a matching verifier key and proof. |
+| **Skyscraper** | Custom BN254-tuned hash engine used as ProveKit's default Merkle commitment and Fiat-Shamir transcript hash. |
+| **Verifier server** | HTTP service in `tooling/verifier-server` that downloads artifacts and orchestrates proof verification. |
+| **Witness** | Private and public assignment values used to satisfy the circuit during proving. |
+| **WHIR** | Proof system family used by ProveKit for proof generation and verification. |
+
+## Related pages
+
+- [Proving flow](/concepts/proving-flow/)
+- [Artifact lifecycle](/concepts/artifact-lifecycle/)
+- [CLI overview](/cli/overview/)
+- [Common errors](/troubleshooting/common-errors/)
diff --git a/docs/src/content/docs/reference/performance.mdx b/docs/src/content/docs/reference/performance.mdx
new file mode 100644
index 000000000..5f8008163
--- /dev/null
+++ b/docs/src/content/docs/reference/performance.mdx
@@ -0,0 +1,106 @@
+---
+title: Performance
+description: How to measure ProveKit on your circuit, the benchmark suite shipped with the repo, and what shapes performance most.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+ProveKit is fast enough to ship in production for many workloads, but "fast" depends almost entirely on circuit shape. This page tells you how to measure your circuit honestly, what dimensions matter, and where the benchmark suite lives.
+
+
+
+## What drives performance
+
+| Dimension | Effect |
+| :--- | :--- |
+| **Constraint count** | Roughly linear in R1CS row count for the dominant proving phases (witness solve, commitment, sumcheck). |
+| **Hash choice** | `skyscraper` is the fastest option for BN254 Merkle commitments. SHA-256, Keccak, Blake3, and Poseidon2 are slower in different ways, Keccak and SHA-256 have larger constraint footprints inside Noir circuits, while Skyscraper, Blake3, and Poseidon2 are cheaper in-circuit. |
+| **Witness layer count** | Witness builders execute in layers (see [Proving flow](/concepts/proving-flow/)). Deep layer graphs add coordination overhead. |
+| **CPU architecture** | `aarch64` benefits from SIMD-accelerated BN254 arithmetic in `skyscraper/core`. x86_64 falls back to portable arithmetic. |
+| **Parallelism** | Proving uses [Rayon](https://github.com/rayon-rs/rayon). More cores help up to the parallelism inherent in the circuit. WASM threading depends on `SharedArrayBuffer`. |
+| **Host memory** | Mobile FFI hosts can swap to disk via `pk_configure_memory(...)`. File-backed mmap allocation is slower than RAM but unlocks larger circuits. |
+
+## Measuring your circuit
+
+The CLI prints span timings and memory statistics through its tracing layer. The simplest measurement:
+
+```sh
+cargo run --release --bin provekit-cli -- prove --prover circuit.pkp
+```
+
+Inspect the structured timing output it prints. For finer-grained profiling, build with the Tracy feature:
+
+```sh
+cargo run --release --features tracy --bin provekit-cli -- --tracy prove
+```
+
+For programmatic benchmarking, across hash configurations, host variants, and circuit sizes, use the `provekit-bench` crate in `tooling/provekit-bench/`. It hooks into `criterion` and reports proving time, verification time, peak memory, and proof size.
+
+## Inspecting the circuit before proving
+
+Two CLI commands tell you what you're about to prove:
+
+```sh
+# R1CS structure and ACIR statistics.
+cargo run --release --bin provekit-cli -- circuit-stats target/.json
+
+# Size breakdown of the prover key, matrix sparsity, witness builders, hash config.
+cargo run --release --bin provekit-cli -- analyze-pkp .pkp
+```
+
+Use `circuit-stats` to confirm constraint counts match your expectations before committing to a host. A circuit that fits comfortably on a server may exceed practical proving time on mobile.
+
+## The ProveKit benchmark suite
+
+`noir-examples/csp-benchmarks/` contains the [Ethproofs CSP benchmarks](https://ethproofs.org/csp-benchmarks), a standardized suite of client-side proving targets used to compare proof systems on common workloads.
+
+| Target | Circuit sizes | Implementation note |
+| :--- | :--- | :--- |
+| **SHA-256** | 128, 256, 512, 1024, 2048 bytes | Uses `noir-lang/sha256::sha256_var`, lowering compression through Noir's SHA-256 blackbox. |
+| **Keccak-256** | 128, 256, 512, 1024, 2048 bytes | Native Noir Keccak circuit with a witness-focused u32 lane representation. |
+| **Poseidon** | 2, 4, 8, 12, 16 field elements | `noir-lang/poseidon` BN254 native Noir helpers. |
+| **Poseidon2** | 2, 4, 8, 12, 16 field elements | `TaceoLabs/noir-poseidon` for states 2, 8, 12, 16; state 4 intentionally exercises Noir's Poseidon2 blackbox. |
+| **ECDSA** | secp256r1 over a 32-byte digest | `zkpassport/noir-ecdsa` native P-256 verification (P-256 blackbox is not yet lowered by ProveKit). |
+
+To run any benchmark target:
+
+```sh
+cd noir-examples/csp-benchmarks/sha256_512
+cargo run --release --bin provekit-cli -- prepare
+cargo run --release --bin provekit-cli -- prove
+cargo run --release --bin provekit-cli -- verify
+```
+
+Combine that with the CLI's timing output (or the `provekit-bench` harness) to capture proving time, verification time, and memory for each target on your machine.
+
+## What to expect across hosts
+
+The fundamentals don't change between hosts, but resource constraints do:
+
+- **Native Rust on a workstation.** The reference platform. Smallest measured proving time, largest available memory.
+- **WASM in a browser.** Slower than native, the proof system runs single-threaded unless `SharedArrayBuffer` is available, and JavaScript marshalling adds overhead at the boundaries.
+- **WASM in Node.js.** Closer to native than browser WASM, but still single-process unless you orchestrate workers externally.
+- **iOS / Android via FFI.** Bounded by device RAM unless you configure `pk_configure_memory` for file-backed mmap. Modern phones can prove non-trivial credential circuits on-device; budget memory carefully.
+- **Verifier server.** Verification dominates. Concurrency is configurable through `VERIFIER_SEMAPHORE_LIMIT`; the default of one keeps memory usage predictable.
+
+## Recursive verification cost
+
+The Groth16 wrapper through the Go/gnark recursive verifier adds a fixed per-proof cost, typically a one-time setup cost (proving key generation) and a recurring proving cost for the outer proof. The base proof's verification is the inner workload; everything else is the wrapper. Plan for the Groth16 step to dominate end-to-end latency when on-chain settlement is the goal.
+
+## Optimization checklist
+
+If proving is slower than you need:
+
+1. **Run `circuit-stats`.** Confirm constraint count matches expectations. Unexpected blowups usually indicate accidentally-quadratic constraint generation.
+2. **Switch to `skyscraper` if you haven't.** It's the default but worth confirming. Other hashes are slower in-circuit.
+3. **Audit black-box vs native lowerings.** Some Noir black boxes (SHA-256, Keccak) are heavier in ProveKit than their native R1CS implementations. The CSP benchmarks call this out explicitly.
+4. **Profile with Tracy.** Run `cargo run --release --features tracy --bin provekit-cli -- --tracy prove` and inspect span timings. Look for layers that dominate the witness solve.
+5. **Split the circuit if possible.** Two smaller proofs may verify faster than one giant proof, depending on transport overhead and what the verifier needs to check.
+
+## Related pages
+
+- [CLI reference](/cli/overview/), flags for `circuit-stats`, `analyze-pkp`, and Tracy profiling.
+- [Examples catalog](/reference/examples/), circuits you can benchmark against.
+- [Proving flow](/concepts/proving-flow/), the conceptual pipeline being measured.
diff --git a/docs/src/content/docs/reference/production-checklist.mdx b/docs/src/content/docs/reference/production-checklist.mdx
new file mode 100644
index 000000000..eaef96452
--- /dev/null
+++ b/docs/src/content/docs/reference/production-checklist.mdx
@@ -0,0 +1,139 @@
+---
+title: Production checklist
+description: Pre-launch checklist for ProveKit artifact generation, integration, verification, and operations.
+---
+
+Use this checklist before shipping a workflow backed by ProveKit. It is intentionally conservative, ProveKit is still under active development and `main` may change proof, key, recursive-verifier, or API formats between commits.
+
+## 1. Pin the implementation
+
+- Choose the branch or release. Use `v1` for the current stable interface; use `main` only for early-adopter work.
+- Record the Git commit, `Cargo.lock`, and `rust-toolchain.toml` used to generate artifacts.
+- Record exact CLI commands, feature flags, compiler backend, and the `prepare --hash` value.
+- Rebuild from a clean checkout in CI before trusting a new artifact set.
+
+## 2. Control artifact provenance
+
+For every generated artifact, store the path, checksum, source commit, generating command, and owner.
+
+| Artifact | Required provenance |
+| :--- | :--- |
+| `.pkp` | Circuit source, compiler backend, hash, commit, generating command. |
+| `.pkv` | Same generation record as the matching `.pkp`. |
+| `proof.np` or JSON proof | Matching `.pkp`, input file, public inputs, commit. |
+| `params_for_recursive_verifier` | Matching `.pkv` and proof. |
+| `r1cs.json` | Matching `.pkv` and recursive-verifier export command. |
+| Groth16 `pk` / `vk` | Setup ceremony or development-only generation record. |
+
+Do not mix artifacts generated from different branches, commits, hash choices, circuits, or verifier/proof pairs.
+
+## 3. Lock the end-to-end workflow
+
+Add a CI job that runs the exact deployment path:
+
+```sh
+mkdir -p artifacts
+cargo run --release --bin provekit-cli -- prepare \
+ . \
+ --pkp artifacts/app.pkp \
+ --pkv artifacts/app.pkv
+cargo run --release --bin provekit-cli -- prove \
+ --prover artifacts/app.pkp \
+ --input Prover.toml \
+ --out artifacts/proof.np
+cargo run --release --bin provekit-cli -- verify \
+ --verifier artifacts/app.pkv \
+ --proof artifacts/proof.np
+cargo run --release --bin provekit-cli -- show-inputs --hex \
+ artifacts/app.pkv \
+ artifacts/proof.np
+```
+
+If recursive verification is part of the product, add the export step and verify the Go/gnark path with the exact generated files:
+
+```sh
+cargo run --release --bin provekit-cli -- generate-gnark-inputs \
+ artifacts/app.pkv \
+ artifacts/proof.np \
+ --params artifacts/params_for_recursive_verifier \
+ --r1cs artifacts/r1cs.json
+```
+
+## 4. Define trust boundaries
+
+- Decide who is allowed to generate `.pkp` and `.pkv` files.
+- Decide where proofs are generated and where they are verified.
+- Treat public input encoding as an API contract; test it with `show-inputs`.
+- Keep private witnesses, prover keys, and generated proofs out of logs unless explicitly approved.
+- Document whether verification depends on the local CLI, embedded Rust, WASM, FFI, the verifier server, or the recursive verifier.
+
+## 5. Harden integration hosts
+
+### Rust services
+
+- Reload or clone verifier state when verifying multiple proofs in one process.
+- Expose hash, compiler, and backend choices in configuration.
+- Add regression tests that confirm mismatched key/proof pairs are rejected.
+
+### WASM / JavaScript
+
+- Call `initPanicHook()` and `initThreadPool()` before proving when using threaded builds.
+- Create a new `Prover` for each proof, `proveBytes()` / `proveJs()` consume the prover.
+- Validate witness maps before calling `proveBytes()` or `proveJs()`.
+- Load `.pkp` and `.pkv` artifacts from authenticated, integrity-checked sources.
+
+### FFI / mobile
+
+- Call `pk_init()` once before proving.
+- Configure the custom allocator or mmap memory *before* initialization.
+- Free every returned `PKBuf` with `pk_free_buf()`.
+- Test low-memory and cancellation behavior on target devices.
+
+### Verifier server
+
+- Restrict artifact URL sources or proxy them through trusted storage.
+- Tune `VERIFIER_MAX_REQUEST_SIZE`, `VERIFIER_REQUEST_TIMEOUT`, `VERIFIER_TIMEOUT_SECONDS`, and `VERIFIER_SEMAPHORE_LIMIT` for real proof sizes.
+- Monitor `/health`, request IDs, verification latency, timeout rate, and invalid-proof rate.
+- Decide how long downloaded artifacts remain in `VERIFIER_ARTIFACTS_DIR`.
+
+### Recursive verifier
+
+- Manage Groth16 proving and verifying keys explicitly for production.
+- Treat development-time key generation as unsafe unless release-specific setup guidance says otherwise.
+- Re-run the recursive export after changing the proof, verifier key, branch, circuit, or hash configuration.
+
+## 6. Capture operational evidence
+
+Before launch, capture evidence for each check:
+
+| Check | Evidence to retain |
+| :--- | :--- |
+| Build reproducibility | Clean-checkout build logs and artifact checksums. |
+| Local verification | `verify` success output and the command line used. |
+| Public inputs | `show-inputs --hex` output reviewed by the application owner. |
+| Negative tests | Proof/key mismatch or corrupted proof is rejected. |
+| Performance | Proving and verification time and memory for expected circuit sizes. |
+| Recovery | Procedure for regenerating and rolling back artifacts. |
+| Observability | Logs and metrics that identify request ID, artifact version, and failure class. |
+
+## 7. Red flags
+
+Pause deployment if any of these are true:
+
+- Artifact provenance is unknown or spans multiple branches or commits.
+- `verify` fails locally for a proof the service plans to accept.
+- Recursive-verifier params or `r1cs.json` were not regenerated with the current `.pkv` and proof.
+- Public input ordering is undocumented.
+- Verifier-server artifact URLs can be controlled by untrusted clients without filtering.
+- FFI buffers are not freed, or allocator setup happens after `pk_init()`.
+- Browser proving reuses a consumed WASM `Prover` instance.
+- The deployment depends on `main` behavior without a migration or rollback plan.
+
+## Related references
+
+- [CLI overview](/cli/overview/)
+- [Integrations overview](/integrations/overview/)
+- [Artifact lifecycle](/concepts/artifact-lifecycle/)
+- [Security and trust model](/concepts/security-model/)
+- [Common errors](/troubleshooting/common-errors/)
+- [Project status and versioning](/reference/project-status/)
diff --git a/docs/src/content/docs/reference/project-status.mdx b/docs/src/content/docs/reference/project-status.mdx
new file mode 100644
index 000000000..ec5d401a7
--- /dev/null
+++ b/docs/src/content/docs/reference/project-status.mdx
@@ -0,0 +1,68 @@
+---
+title: Project status and versioning
+description: Branch policy, artifact compatibility, and integration maturity for ProveKit.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+ProveKit is under active development. Code, proof and key formats, recursive-verifier inputs, and integration APIs are branch-scoped unless a release note explicitly says otherwise.
+
+
+
+## Branch policy
+
+| Branch | Audience | Documentation expectation |
+| :--- | :--- | :--- |
+| `v1` | Users who need a stable interface today. | The stable docs target this branch first. |
+| `main` | Contributors and early adopters. | May include breaking changes to proof, key, recursive-verifier, or API formats. |
+
+Use `v1` when reproducibility matters more than testing the newest implementation. Use `main` only when you are prepared to regenerate artifacts and adapt to source-level changes.
+
+## Artifact compatibility
+
+Do not assume compatibility across branches or commits unless a release note states the formats are unchanged.
+
+Regenerate every affected artifact after changing any of:
+
+- Git branch, commit, or dependency lockfile.
+- Noir circuit source, package selection, or workspace layout.
+- Compiler version or lockfile pins for Noir dependencies.
+- `prepare --hash` value.
+- Prover inputs (when a new proof is expected).
+- Recursive-verifier export settings or the proof/verifier pair.
+
+The safest deployment record includes the Git commit, `rust-toolchain.toml`, `Cargo.lock`, every CLI command line, artifact checksums, and the public input encoding expected by downstream systems.
+
+## Integration status
+
+| Path | Status | Compatibility notes |
+| :--- | :--- | :--- |
+| CLI `prepare` / `prove` / `verify` | Primary local workflow. | Defaults are package-derived; use explicit paths in CI and production. |
+| Rust crates | Internal integration path. | API names and proof/key types may move while `main` evolves. |
+| WASM bindings | Active browser/JavaScript path. | Provers are consumed after one proof; `getCircuit()` is available for Noir provers. |
+| FFI bindings | Active mobile/native host path. | Hosts must manage initialization, allocator configuration, and buffer ownership. |
+| Verifier server | Active HTTP verification path. | Requires reachable HTTP/HTTPS artifact URLs and tuned request/time/concurrency limits. |
+| Recursive verifier | Active Go/gnark wrapper. | Recursive params and R1CS JSON must be regenerated with the matching verifier/proof pair. |
+
+## Documentation policy
+
+- Stable docs target `v1` unless a page is marked development-only.
+- Examples that require `main`-only behavior are flagged explicitly.
+- Command examples must run from a fresh checkout.
+- Docs aimed at CI, services, or production use explicit artifact paths.
+- Generated Rust API docs are linked separately from task-based user docs when hosted API docs are available.
+- Artifact custody and trust-boundary guidance stays aligned with the [Security and trust model](/concepts/security-model/).
+
+## Known launch gaps
+
+Resolve or explicitly accept each of these before recommending ProveKit for external production users:
+
+- Hosted API docs for the Rust crates and the generated C header.
+- Pre-built binary artifacts for `provekit-cli` attached to GitHub Releases (currently `cargo install` only).
+- Executable app templates or CI-backed fixtures for each supported host language and platform.
+- Release-specific security review notes, audit status, and trusted-setup key handling guidance.
+- A support policy for branch-specific docs and migration notes.
+
+Track deployment-specific readiness in the [Production checklist](/reference/production-checklist/).
diff --git a/docs/src/content/docs/reference/starter-template.mdx b/docs/src/content/docs/reference/starter-template.mdx
new file mode 100644
index 000000000..84bc38d97
--- /dev/null
+++ b/docs/src/content/docs/reference/starter-template.mdx
@@ -0,0 +1,165 @@
+---
+title: Starter templates
+description: Cloneable starting points and deployment recipes for shipping a ProveKit-backed application.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+A ZK application typically has three moving parts: a Noir circuit, a prover that runs near the user (server, browser, or mobile), and a verifier that runs wherever the trust boundary sits (your backend, a chain, or both). This page collects starting points and deployment patterns for each.
+
+
+
+## Starting points by shape
+
+### A Rust service that verifies proofs
+
+Use this when verification happens in your backend (HTTP API, gRPC service, job worker).
+
+**Skeleton:**
+
+```toml title="Cargo.toml"
+[package]
+name = "my-verifier"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+provekit-common = "1.0.0"
+provekit-verifier = "1.0.0"
+axum = "0.7" # or actix, tonic, etc.
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["full"] }
+anyhow = "1"
+```
+
+**Implementation guide:** [Rust end-to-end](/e2e/rust/) shows the verifier setup. Wrap `verify()` behind your transport layer; refer to [Common errors](/troubleshooting/common-errors/) for failure modes to translate into HTTP statuses.
+
+### A browser app that proves locally
+
+Use this when the user's device holds the secret and proves on-device, the canonical privacy-preserving pattern.
+
+**Skeleton:**
+
+```ts title="package.json (dependencies)"
+{
+ "dependencies": {
+ "@atheon/verity": "^0.3.2",
+ "@noir-lang/noir_js": "^0.x",
+ "@noir-lang/acvm_js": "^0.x"
+ }
+}
+```
+
+**Implementation guide:** [JS / TypeScript end-to-end](/e2e/js-typescript/). Notes:
+
+- For Next.js, place WASM artifacts under `public/` and configure headers for `SharedArrayBuffer` (`Cross-Origin-Opener-Policy: same-origin`, `Cross-Origin-Embedder-Policy: require-corp`).
+- For Vite, copy WASM artifacts via `assetsInclude` or a plugin and serve with the same headers.
+
+### A mobile app that proves on-device
+
+Use this when the user is on iOS or Android and the secret never leaves their device.
+
+| Platform | Starting point |
+| :--- | :--- |
+| iOS | [Swift end-to-end](/e2e/swift/), SPM package, three build modes. macOS is not supported. |
+| Android | [Kotlin end-to-end](/e2e/kotlin/), AAR + JNI, ABI packaging guidance. |
+
+Plan ahead for memory configuration (`pk_configure_memory` / `Verity.configureMemory`) before backend initialization, mobile circuits routinely require file-backed mmap.
+
+### A verifier service behind HTTP
+
+Use the bundled HTTP service when you want artifact-driven verification without writing transport glue.
+
+```sh
+# From the repo root.
+cd tooling/verifier-server
+cargo run --release
+```
+
+Configure with the `VERIFIER_*` environment variables documented in `tooling/verifier-server/README.md`. The service downloads `.pkv` and `r1cs.json` from URLs in each request, restrict those URL sources for production.
+
+### An on-chain Groth16 verifier
+
+Use when the verification result needs to settle on-chain.
+
+```sh
+# 1. Produce the recursive-verifier inputs.
+cargo run --release --bin provekit-cli -- generate-gnark-inputs \
+ circuit.pkv proof.np \
+ --params recursive/params --r1cs recursive/r1cs.json
+
+# 2. Run the Go/gnark wrapper.
+cd recursive-verifier
+go run ./cmd/cli ...
+```
+
+Manage Groth16 proving and verifying keys explicitly. Development-time key generation should not be reused in production. The Go module lives in `recursive-verifier/`, its CLI is the entry point for one-shot wrapping; its server mode is the entry point for batched workflows.
+
+## Deployment recipes
+
+### Docker for the verifier server
+
+```dockerfile title="Dockerfile (sketch)"
+FROM rust:1.85 AS build
+WORKDIR /src
+COPY . .
+RUN cargo build --release -p verifier-server
+
+FROM debian:bookworm-slim
+COPY --from=build /src/target/release/verifier-server /usr/local/bin/
+EXPOSE 3000
+ENV VERIFIER_SEMAPHORE_LIMIT=2 \
+ VERIFIER_REQUEST_TIMEOUT=60 \
+ VERIFIER_TIMEOUT_SECONDS=120
+ENTRYPOINT ["/usr/local/bin/verifier-server"]
+```
+
+Adjust the `VERIFIER_*` envs for your circuit profile. The defaults (one concurrent verification, 10 MiB request body) are conservative.
+
+### CI pipeline for artifact generation
+
+A minimal release-producing job (GitHub Actions, GitLab CI, or equivalent):
+
+```yaml
+- name: Prepare keys
+ run: cargo run --release --bin provekit-cli -- prepare . --pkp out/app.pkp --pkv out/app.pkv
+
+- name: Generate test proof
+ run: cargo run --release --bin provekit-cli -- prove --prover out/app.pkp --input fixtures/Prover.toml --out out/proof.np
+
+- name: Verify locally
+ run: cargo run --release --bin provekit-cli -- verify --verifier out/app.pkv --proof out/proof.np
+
+- name: Record public inputs
+ run: cargo run --release --bin provekit-cli -- show-inputs --hex out/app.pkv out/proof.np > out/public_inputs.txt
+
+- name: Publish artifacts with provenance
+ run: sha256sum out/* > out/CHECKSUMS && upload out/
+```
+
+See [Generate artifacts](/e2e/generate-artifacts/) for the full CI evidence template.
+
+### Distributing the verifier key
+
+`.pkv` is typically shipped *with* the application that verifies. Options:
+
+- **Embedded in the binary.** Smallest deployment footprint; requires a release per circuit version.
+- **Loaded from CDN at startup.** Decouples circuit upgrades from app releases; requires integrity checks (subresource integrity or signed manifests).
+- **Pinned per request.** Verifier server pattern: the client supplies the `.pkv` URL alongside the proof. Restrict URL sources or proxy through trusted storage.
+
+## Anti-patterns
+
+Avoid these shortcuts, they cause production incidents:
+
+- **Reusing `.pkp` across circuit versions.** Keys are bound to the circuit; mixing breaks verification silently.
+- **Logging private witnesses or `Prover.toml` contents.** They are secrets by default.
+- **Verifying without checking public inputs.** Verification proves the proof; *your code* proves the proof authorizes the action.
+- **Shipping `main`-branch artifacts without a regeneration plan.** Format changes are possible between commits.
+
+## Related pages
+
+- [Production checklist](/reference/production-checklist/), pre-launch checks for every host.
+- [Integrations overview](/integrations/overview/), the menu of where ProveKit can run.
+- [Security and trust model](/concepts/security-model/), what verification proves and what it doesn't.
diff --git a/docs/src/content/docs/troubleshooting/common-errors.mdx b/docs/src/content/docs/troubleshooting/common-errors.mdx
new file mode 100644
index 000000000..f3d07c29a
--- /dev/null
+++ b/docs/src/content/docs/troubleshooting/common-errors.mdx
@@ -0,0 +1,213 @@
+---
+title: Common errors
+description: Diagnose setup, proving, verification, integration, and deployment failures.
+---
+
+Use this page to diagnose setup, artifact, CLI, WASM, FFI, verifier-server, and recursive-verifier failures. The first question to ask every time: *which artifact was produced by which command, branch, compiler backend, and hash configuration?*
+
+## Rust toolchain mismatch
+
+**Symptom.** Cargo fails before building ProveKit crates, or reports an unexpected nightly/stable compiler.
+
+**Checks.**
+
+```sh
+rustup show
+cargo --version
+cat rust-toolchain.toml
+```
+
+**Fix.** Run commands from a checkout that contains `rust-toolchain.toml` so Cargo selects the pinned toolchain. If the toolchain is missing, install or update it with `rustup` and retry from the repository root.
+
+## Cargo cannot find `provekit-cli`
+
+**Symptom.** `cargo run` reports that the binary target cannot be found, or CLI arguments are parsed by Cargo instead of ProveKit.
+
+**Checks.**
+
+```sh
+cargo metadata --no-deps --format-version 1 | rg 'provekit-cli|tooling/cli'
+cargo run --release --bin provekit-cli -- --help
+```
+
+**Fix.** Run from the workspace root and pass CLI arguments after `--`:
+
+```sh
+cargo run --release --bin provekit-cli -- prepare
+```
+
+## No enclosing Noir package
+
+**Symptom.** `prepare`, `prove`, or `verify` cannot infer default key names, or a Noir command cannot find a package manifest.
+
+**Checks.**
+
+```sh
+pwd
+find .. -name Nargo.toml -maxdepth 4
+```
+
+**Fix.** Run from the Noir package directory, pass `prepare `, or use explicit artifact paths (`--pkp`, `--pkv`, `--prover`, `--verifier`).
+
+## Multiple binary packages with explicit key outputs
+
+**Symptom.** `prepare --workspace --pkp ... --pkv ...` fails because multiple binary packages would write to a single explicit key pair.
+
+**Fix.** Either compile one package with `--package `, or omit `--pkp`/`--pkv` so each binary package uses its package-derived output names.
+
+## Unsupported hash choice
+
+**Symptom.** `prepare --hash ` rejects the hash argument.
+
+**Fix.** Use one of the supported names:
+
+- `skyscraper`
+- `sha256`
+- `keccak`
+- `blake3`
+- `poseidon2`
+
+Regenerate the prover key, verifier key, and every proof after changing the hash.
+
+## Missing or stale artifacts
+
+**Symptom.** `prove` or `verify` cannot find expected `.pkp`, `.pkv`, or `proof.np` files.
+
+**Checks.**
+
+```sh
+ls -lh *.pkp *.pkv proof.np 2>/dev/null || true
+cargo run --release --bin provekit-cli -- prepare --help
+```
+
+**Fix.** Re-run the workflow from `prepare` in the same Noir package directory, or pass explicit paths for every artifact:
+
+```sh
+mkdir -p artifacts
+cargo run --release --bin provekit-cli -- prepare \
+ . \
+ --pkp artifacts/app.pkp \
+ --pkv artifacts/app.pkv
+cargo run --release --bin provekit-cli -- prove \
+ --prover artifacts/app.pkp \
+ --input Prover.toml \
+ --out artifacts/proof.np
+cargo run --release --bin provekit-cli -- verify \
+ --verifier artifacts/app.pkv \
+ --proof artifacts/proof.np
+```
+
+## Verification failure
+
+**Symptom.** `verify` rejects a generated or supplied proof.
+
+**Likely causes.**
+
+- The proof was generated with a different `.pkp` than the `.pkv` used for verification.
+- The circuit source or Noir package changed after `prepare`.
+- The proof was generated from inputs that don't satisfy the circuit.
+- The branch changed between artifact generation and verification.
+- The hash configuration changed.
+- Public inputs were serialized or transported incorrectly.
+
+**Fix.** Regenerate `.pkp`, `.pkv`, and `proof.np` from the same checkout and hash choice. Use `show-inputs` to inspect public inputs:
+
+```sh
+cargo run --release --bin provekit-cli -- show-inputs --hex artifacts/app.pkv artifacts/proof.np
+```
+
+## `show-inputs` reports an ABI/public-input mismatch
+
+**Symptom.** `show-inputs` says the ABI expects more public inputs than the proof contains.
+
+**Fix.** The proof and verifier key are not from the same compiled circuit, or the proof JSON was modified or truncated. Regenerate from `prepare` and avoid manually editing proof JSON.
+
+## `circuit-stats` cannot read the circuit JSON
+
+**Symptom.** `circuit-stats` reports a missing `bytecode` field or a base64 decode error.
+
+**Fix.** Pass the Noir ACIR artifact JSON produced under the Noir target directory, not a `.pkp`, `.pkv`, proof, or recursive-verifier `r1cs.json` file.
+
+## WASM prover has already been consumed
+
+**Symptom.** Browser code receives `Prover has been consumed by a previous prove() call`.
+
+**Fix.** Create a new `Prover` for each proof. The WASM `Verifier` is reusable, but `Prover.proveBytes()` and `Prover.proveJs()` consume the prover state.
+
+## WASM witness map parsing fails
+
+**Symptom.** Browser code reports an empty witness map, unsupported key type, non-string value, invalid hex, or a field element larger than 32 bytes.
+
+**Fix.** Pass a JavaScript `Map` or plain object that maps witness indices to hex strings:
+
+```js
+const witnessMap = new Map([
+ [0, "0x01"],
+ [1, "0x02"],
+]);
+```
+
+Values are reduced as BN254 field elements and must fit within 32 bytes.
+
+## FFI returns an error code
+
+**Symptom.** A C, Swift, Kotlin, Python, or other FFI host receives a non-zero `PKError`.
+
+**Checks.**
+
+- `PK_INVALID_INPUT`, ensure pointers and paths are not null.
+- `PK_SCHEME_READ_ERROR`, confirm the `.pkp` path exists and is readable.
+- `PK_WITNESS_READ_ERROR`, confirm the input TOML path exists and matches the circuit ABI.
+- `PK_PROOF_ERROR`, regenerate artifacts and try the same inputs with the CLI.
+- `PK_SERIALIZATION_ERROR` or `PK_FILE_WRITE_ERROR`, check output paths and permissions.
+
+**Fix.** Call `pk_init()` before proving, free returned buffers with `pk_free_buf()`, and configure custom allocators or mmap memory before initialization.
+
+## Verifier server rejects a request
+
+**Symptom.** `/verify` returns validation errors, `isValid: false`, a timeout status, or an HTTP error.
+
+**Checks.**
+
+```sh
+curl http://localhost:3000/health
+```
+
+Confirm the request body has:
+
+- `pkvUrl`, a non-empty HTTP/HTTPS URL to a `.pkv` artifact.
+- `r1csUrl`, a non-empty HTTP/HTTPS URL to recursive-verifier R1CS JSON.
+- `np`, a non-null JSON `NoirProof` object.
+- Optional `verificationParams.maxVerificationTime`, greater than `0` and at most `300` seconds.
+
+**Fix.** Make artifacts reachable from the server, raise `VERIFIER_MAX_REQUEST_SIZE` for larger requests, tune `VERIFIER_REQUEST_TIMEOUT` and `VERIFIER_TIMEOUT_SECONDS` for long verification runs, and keep `VERIFIER_SEMAPHORE_LIMIT` aligned with available CPU and memory.
+
+## Recursive-verifier input mismatch
+
+**Symptom.** The Go recursive verifier fails with config, R1CS, or key errors.
+
+**Fix.** Re-run `generate-gnark-inputs` from the same `.pkv` and proof you plan to verify:
+
+```sh
+cargo run --release --bin provekit-cli -- generate-gnark-inputs \
+ artifacts/app.pkv \
+ artifacts/proof.np \
+ --params artifacts/params_for_recursive_verifier \
+ --r1cs artifacts/r1cs.json
+```
+
+Pass those exact files to the Go CLI or server. Do not reuse recursive params after changing the proof, verifier key, branch, circuit, or hash configuration.
+
+## Still stuck?
+
+Collect this information before opening an issue or escalating internally:
+
+- Git branch and commit.
+- Rust toolchain from `rustup show`.
+- Full command line and stderr.
+- Whether artifacts were generated on `v1` or `main`.
+- The `prepare --hash` value.
+- File sizes and modification times for `.pkp`, `.pkv`, `proof.np`, `r1cs.json`, and recursive params.
+- Whether the same proof verifies with the local CLI.
+
+Before deploying any fix, walk through the [Production checklist](/reference/production-checklist/).
diff --git a/docs/src/styles/starlight.css b/docs/src/styles/starlight.css
new file mode 100644
index 000000000..e62cfa49e
--- /dev/null
+++ b/docs/src/styles/starlight.css
@@ -0,0 +1,1012 @@
+/* ============================================================
+ PROVEKIT DESIGN SYSTEM — applied to Astro Starlight
+ Light-first. Borders, not shadows. Square corners. Outfit + Geist Mono.
+ Selectors verified against the rendered Starlight DOM.
+ ============================================================ */
+
+@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Geist+Mono:wght@400;500&display=swap');
+
+/* ============================================================
+ 1. Brand tokens
+ ============================================================ */
+
+:root {
+ --pk-ink: #2D2D2B;
+ --pk-ink-alt: #2D2D30;
+ /* Mid-tone between ink (#2D2D2B) and mute (#949494). ~6.4:1 contrast on white,
+ passes WCAG AA for body text without reading as jet-black. Used for nav items. */
+ --pk-ink-soft: #5C5C5A;
+ --pk-mute: #949494;
+ --pk-mute-soft: #B7B7B7;
+
+ --pk-canvas: #F8FEFF;
+ --pk-surface: #FFFFFF;
+ --pk-surface-tint: rgba(190, 225, 255, 0.04);
+
+ --pk-line: #D1F5FF;
+ --pk-line-soft: #EEF7FF;
+ --pk-line-mid: #BCEEFF;
+
+ --pk-brand: #0D74FF;
+ --pk-brand-hover: #0A66E0;
+ --pk-brand-ink: #A2D0FC;
+
+ --pk-font-sans: "Outfit", system-ui, -apple-system, "Segoe UI", sans-serif;
+ --pk-font-mono: "Geist Mono", ui-monospace, "SF Mono", monospace;
+}
+
+/* ============================================================
+ 2. Starlight token map — LIGHT (canonical brand mode)
+ ============================================================ */
+
+:root,
+:root[data-theme='light'] {
+ color-scheme: light;
+
+ --sl-font: var(--pk-font-sans);
+ --sl-font-mono: var(--pk-font-mono);
+
+ --sl-color-text: var(--pk-ink);
+ --sl-color-text-accent: var(--pk-brand);
+ --sl-color-text-invert: #FFFFFF;
+
+ --sl-color-bg: var(--pk-canvas);
+ --sl-color-bg-nav: var(--pk-surface);
+ --sl-color-bg-sidebar: var(--pk-surface);
+ --sl-color-bg-inline-code:var(--pk-line-soft);
+ --sl-color-bg-accent: var(--pk-brand);
+
+ --sl-color-accent-low: #EAF4FF;
+ --sl-color-accent: var(--pk-brand);
+ --sl-color-accent-high: var(--pk-brand-hover);
+
+ --sl-color-hairline-light:var(--pk-line);
+ --sl-color-hairline: var(--pk-line);
+ --sl-color-hairline-shade:var(--pk-line-soft);
+
+ --sl-color-white: var(--pk-ink);
+ --sl-color-black: var(--pk-surface);
+
+ --sl-color-gray-1: var(--pk-ink-alt);
+ --sl-color-gray-2: var(--pk-mute);
+ --sl-color-gray-3: var(--pk-mute);
+ --sl-color-gray-4: var(--pk-mute-soft);
+ --sl-color-gray-5: var(--pk-line-mid);
+ --sl-color-gray-6: var(--pk-line);
+
+ --sl-shadow-sm: none;
+ --sl-shadow-md: none;
+ --sl-shadow-lg: none;
+}
+
+/* ============================================================
+ 3. Starlight token map — DARK (derivative, kept for toggle users)
+ ============================================================ */
+
+:root[data-theme='dark'] {
+ color-scheme: dark;
+
+ --sl-color-text: #EAF4FF;
+ --sl-color-text-accent: var(--pk-brand-ink);
+ --sl-color-text-invert: var(--pk-ink);
+
+ --sl-color-bg: #14171C;
+ --sl-color-bg-nav: #1A1E25;
+ --sl-color-bg-sidebar: #1A1E25;
+ --sl-color-bg-inline-code:#1E242F;
+ --sl-color-bg-accent: var(--pk-brand-ink);
+
+ --sl-color-accent-low: #102542;
+ --sl-color-accent: var(--pk-brand-ink);
+ --sl-color-accent-high: #E3F2FF;
+
+ --sl-color-hairline-light:#2D3648;
+ --sl-color-hairline: #2D3648;
+ --sl-color-hairline-shade:#1F2A3A;
+
+ --sl-color-white: #EAF4FF;
+ --sl-color-black: #14171C;
+
+ --sl-color-gray-1: #EAF4FF;
+ --sl-color-gray-2: #9AA8BC;
+ --sl-color-gray-3: #7B8CA3;
+ --sl-color-gray-4: #4A5A73;
+ --sl-color-gray-5: #2D3648;
+ --sl-color-gray-6: #1F2A3A;
+}
+
+/* ============================================================
+ 4. Body type
+ ============================================================ */
+
+html { scroll-behavior: smooth; }
+
+body {
+ font-family: var(--pk-font-sans);
+ font-weight: 400;
+ letter-spacing: -0.005em;
+}
+
+.sl-markdown-content :is(h1, h2, h3, h4, h5, h6):not(:where(.not-content *)) {
+ font-family: var(--pk-font-sans);
+ font-weight: 500;
+ letter-spacing: -0.02em;
+}
+
+.sl-markdown-content h2:not(:where(.not-content *)) { font-size: 1.65rem; }
+.sl-markdown-content h3:not(:where(.not-content *)) { font-size: 1.22rem; }
+
+.sl-markdown-content .lead {
+ color: var(--sl-color-text);
+ font-weight: 400;
+ font-size: clamp(1.1rem, 1rem + 0.5vw, 1.32rem);
+ line-height: 1.55;
+ margin-top: 0;
+}
+
+:root[data-theme='dark'] .sl-markdown-content .lead {
+ color: #C5D6EE;
+}
+
+/* ============================================================
+ 5. Sidebar — group labels in Geist Mono ALL CAPS
+ Actual DOM: Title
+ ============================================================ */
+
+.sidebar-content .group-label,
+.sidebar-content .group-label .large {
+ font-family: var(--pk-font-mono);
+ text-transform: uppercase;
+ letter-spacing: 0.02em;
+ font-weight: 500;
+ font-size: 0.78rem;
+}
+
+.sidebar-content .top-level > li > details > summary {
+ padding-block: 0.5rem;
+}
+
+/* Sidebar links — mid-tone ink, readable but not pitch black. */
+.sidebar-content ul a {
+ font-family: var(--pk-font-sans);
+ font-size: 0.95rem;
+ color: var(--pk-ink-soft);
+}
+
+:root[data-theme='dark'] .sidebar-content ul a {
+ color: #BFC9D8;
+}
+
+.sidebar-content ul a:hover {
+ color: var(--pk-brand);
+}
+
+:root[data-theme='dark'] .sidebar-content ul a:hover {
+ color: var(--pk-brand-ink);
+}
+
+/* Current page indicator */
+.sidebar-content ul a[aria-current="page"] {
+ background: var(--pk-line-soft);
+ color: var(--pk-brand);
+ border-inline-start: 2px solid var(--pk-brand);
+}
+
+:root[data-theme='dark'] .sidebar-content ul a[aria-current="page"] {
+ background: #102542;
+ color: var(--pk-brand-ink);
+ border-inline-start-color: var(--pk-brand-ink);
+}
+
+/* ============================================================
+ 6. Right sidebar — TOC heading in mono uppercase
+ ============================================================ */
+
+.right-sidebar-panel h2 {
+ font-family: var(--pk-font-mono);
+ text-transform: uppercase;
+ letter-spacing: 0.02em;
+ font-weight: 500;
+ font-size: 0.74rem;
+ color: var(--pk-mute);
+}
+
+/* ============================================================
+ 7. Header
+ ============================================================ */
+
+/* Scoped to the semantic element to avoid double-bordering
+ the inner