docs(readme): overhaul README for v1 branch#421
Merged
Conversation
Replaces the flat demo-instructions README with a structured, technical document following the same conventions as the main branch overhaul. - Add quick links row (Getting Started, Examples, Contributing, Issues) - Add Mermaid architecture diagram and crate table - Add end-to-end Example section using noir-examples/basic-4 — all four commands verified locally with nargo v1.0.0-beta.11 - Structured Getting Started as collapsible steps - Profiling section as a table with Tool / Measures / Command columns - Acknowledgements section explaining what each dependency contributes - Fix generate-gnark-inputs to use prover.pkp (correct for v1 CLI) - Fix skyscraper description: M31/CM31 -> BN254
Remove filler intro from Acknowledgements, break the uniform capitalisation pattern in dependency bullets, add explicit nargo version pin, and replace the ### Circuit inspection heading with a contextual prose line.
The v1 README now carries over the product-positioning fixes from the README PR while keeping v1-specific facts intact: Noir compiles to R1CS, WHIR proofs are generated and verified through the Spartan-style R1CS path, SIMD field arithmetic and memory-efficient behavior are highlighted without calling ProveKit mobile-optimized, FFI host languages are named, and recursive verification is described in terms of the v1 prover-key/proof export flow for on-chain Groth16 wrappers.\n\nConstraint: PR #421 targets v1 and uses generate-gnark-inputs with a prover key, not a verifier key.\nRejected: Cherry-pick the main-branch README commits verbatim | the v1 README structure and CLI facts differ.\nConfidence: high\nScope-risk: narrow\nTested: git diff --check -- README.md\nNot-tested: Full README example pipeline; rendered GitHub Markdown preview.
The v1 README now maps the requested workspace crates and relevant repository surfaces explicitly: common, r1cs compiler, prover, verifier, CLI, benchmark, FFI, gnark export, verifier server, NTT, recursive verifier, Skyscraper, and Noir examples. The old combined rows were split and the stale gnark-whir path was replaced with real v1 paths.\n\nConstraint: User requested the repository-map additions for PR #421 and v1 correctness.\nRejected: Keeping a Crates-only heading | noir-examples and recursive-verifier are relevant repository surfaces but not Rust crates.\nConfidence: high\nScope-risk: narrow\nTested: git diff --check -- README.md; verified requested paths exist in v1 worktree.\nNot-tested: Rendered GitHub Markdown preview.
The v1 README now follows the same public structure as the main README: title, product positioning, Why ProveKit, Quick Start, command reference, How It Works, example circuit, repository map, advanced usage, project status, contributing, acknowledgements, and license. The content keeps v1-specific CLI facts intact, including nargo v1.0.0-beta.11, explicit compiled-artifact prepare input, circuit_stats, and generate-gnark-inputs using a prover key plus proof.\n\nConstraint: PR #421 targets v1, whose CLI differs from main and does not use the main branch zero-arg prepare/prove/verify flow.\nRejected: Copy main README verbatim | would introduce incorrect v1 CLI claims such as main-style defaults and verifier-key recursive export wording.\nConfidence: high\nScope-risk: narrow\nTested: git diff --check -- README.md; verified referenced local links and v1-specific CLI command names/arguments.\nNot-tested: Full nargo/provekit example execution; rendered GitHub Markdown preview.
The README PR now merges the latest v1 branch so GitHub can merge it cleanly, while resolving the README conflict in favor of current v1 CLI behavior. The refreshed README documents zero-argument prepare/prove/verify defaults, the circuit-stats command rename, prover-key based gnark input export, and the same public section skeleton used by the main README. Constraint: PR #421 targets v1 after the CLI defaults and compile-flow updates landed. Rejected: Rebase/force-push the PR branch | a normal merge preserves collaborator history and fixes conflicts without rewriting the branch. Confidence: high Scope-risk: narrow Tested: git diff --cached --check; cargo check -p provekit-cli; verified README links and CLI command names against source. Not-tested: Full Noir prepare/prove/verify run; rendered GitHub Markdown preview. Co-authored-by: OmX <omx@oh-my-codex.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the flat demo-instructions README on the
v1branch with a structured, professional document using the same conventions applied tomainin #420.## Examplesection usingnoir-examples/basic-4— all four commands (nargo compile→prepare→prove→verify) verified locally with nargov1.0.0-beta.11assets/on this branch)v1-specific correctness fixes included:
generate-gnark-inputsuses./prover.pkp(v1 CLI takes the prover key, not verifier key)v1.0.0-beta.11--compiler mavrosoption (not present in v1 CLI)Test plan
nargo compileonnoir-examples/basic-4— clean withv1.0.0-beta.11prepare→prove→verifypipeline — exit code 0