docs(readme): rebase onto main and polish for unified CLI

License.md → LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2025 World Foundation
+Copyright (c) 2026 World Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

provekit/common/src/prover.rs

@@ -20,9 +20,15 @@ pub struct NoirProver {
     pub whir_for_witness:       WhirR1CSScheme,
 }
 
-// INVARIANT: Variant order is wire-format-critical (postcard uses positional
-// discriminants). Do not reorder, cfg-gate, or insert variants without
-// verifying cross-target deserialization (native <-> WASM).
+/// On-disk **ProveKit Prover** (PKP) — the prover-side scheme that gets
+/// serialized to a `.pkp` file by `prepare` and loaded by `prove`.
+///
+/// Holds the R1CS, witness builders, WHIR config, and frontend-specific
+/// program data needed to produce a proof.
+///
+/// INVARIANT: Variant order is wire-format-critical (postcard uses positional
+/// discriminants). Do not reorder, cfg-gate, or insert variants without
+/// verifying cross-target deserialization (native <-> WASM).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum Prover {
     Noir(NoirProver),

provekit/common/src/verifier.rs

@@ -7,6 +7,12 @@ use {
     serde::{Deserialize, Serialize},
 };
 
+/// On-disk **ProveKit Verifier** (PKV) — the verifier-side scheme that gets
+/// serialized to a `.pkv` file by `prepare` and loaded by `verify` (or by
+/// `generate-gnark-inputs` for the recursive path).
+///
+/// Holds the R1CS, the WHIR-for-witness commitment configuration, and the
+/// ABI needed to bind public inputs back to their Noir-level names.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Verifier {
     pub hash_config:      HashConfig,

tooling/cli/src/cmd/circuit_stats/mod.rs

@@ -6,7 +6,7 @@
 //! # Example
 //!
 //! ```sh
-//! cargo run --release --bin provekit-cli circuit_stats ./target/basic.json
+//! cargo run --release --bin provekit-cli circuit-stats ./target/basic.json
 //! ```
 
 mod display;
@@ -33,7 +33,7 @@ use {
 #[derive(FromArgs, PartialEq, Eq, Debug)]
 #[argh(
     subcommand,
-    name = "circuit_stats",
+    name = "circuit-stats",
     description = "analyze ACIR circuit statistics and R1CS complexity (Noir only, not supported \
                    for Mavros)"
 )]

tooling/cli/src/cmd/prepare.rs

@@ -91,11 +91,13 @@ pub struct Args {
     #[argh(switch)]
     force: bool,
 
-    /// output path for the prover key (default: `<circuit>.pkp`)
+    /// output path for the ProveKit Prover (PKP) key (default:
+    /// `<circuit>.pkp`)
     #[argh(option, long = "pkp", short = 'p')]
     pkp_path: Option<PathBuf>,
 
-    /// output path for the verifier key (default: `<circuit>.pkv`)
+    /// output path for the ProveKit Verifier (PKV) key (default:
+    /// `<circuit>.pkv`)
     #[argh(option, long = "pkv", short = 'v')]
     pkv_path: Option<PathBuf>,
 

tooling/cli/src/cmd/prove.rs

@@ -17,7 +17,7 @@ use {provekit_common::Verifier, provekit_verifier::Verify};
 #[derive(FromArgs, PartialEq, Eq, Debug)]
 #[argh(subcommand, name = "prove")]
 pub struct Args {
-    /// path to the prover key (default: `<circuit>.pkp`)
+    /// path to the ProveKit Prover (PKP) key (default: `<circuit>.pkp`)
     #[argh(option, long = "prover", short = 'p')]
     prover_path: Option<PathBuf>,
 

tooling/cli/src/cmd/verify.rs

@@ -12,7 +12,7 @@ use {
 #[derive(FromArgs, PartialEq, Eq, Debug)]
 #[argh(subcommand, name = "verify")]
 pub struct Args {
-    /// path to the verifier key (default: `<circuit>.pkv`)
+    /// path to the ProveKit Verifier (PKV) key (default: `<circuit>.pkv`)
     #[argh(option, long = "verifier", short = 'v')]
     verifier_path: Option<PathBuf>,