ProveKit docs for integration

README.md

@@ -8,17 +8,17 @@
 [![Rust](https://img.shields.io/badge/rust-nightly-e32828?style=flat-square&logo=rust)](https://rustup.rs/)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE.md)
 
-[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Examples](./noir-examples/) · [Repository Map](#repository-map) · [Contributing](./CONTRIBUTING.md)
+[Quick Start](#quick-start) · [Docs](./docs/) · [How It Works](#how-it-works) · [Examples](./noir-examples/) · [Repository Map](#repository-map) · [Contributing](./CONTRIBUTING.md)
 
 </div>
 
-ProveKit is a zero-knowledge proof system toolkit that compiles [Noir](https://noir-lang.org/) programs to R1CS constraints and generates and verifies [WHIR](https://github.com/WizardOfMenlo/whir) proofs using a Spartan-based protocol. It includes custom SIMD-accelerated field arithmetic and memory-efficient algorithms for resource-constrained environments, with a complete proving and verification stack plus recursive verification support for on-chain Groth16 applications.
+ProveKit compiles [Noir](https://noir-lang.org/) programs to R1CS constraints and generates and verifies [WHIR](https://github.com/WizardOfMenlo/whir) proofs using a Spartan-based protocol. The repository includes SIMD-accelerated field arithmetic, memory-conscious proving code, CLI tooling, host-language bindings, and recursive-verifier export for Go/gnark and Groth16 workflows.
 
 ## Why ProveKit
 
 - **Noir frontend:** write circuits in Noir and use ProveKit to prepare keys, prove, and verify with one CLI.
-- **Post-quantum secure proofs:** produce WHIR proofs designed around post-quantum security assumptions.
-- **Integration-ready surface:** use ProveKit from Swift, Kotlin, JavaScript, and Rust, or use the C-compatible FFI when you need another language.
+- **WHIR proof backend:** produce and verify WHIR proofs from prepared ProveKit artifacts.
+- **Host integrations:** use ProveKit from Rust, JavaScript, Swift, Kotlin, or any host that can call the C-compatible FFI.
 - **Recursive verifier for on-chain Groth16:** export verifier/proof data for a recursive verifier when an on-chain Groth16 wrapper is required.
 
 ## Quick Start
@@ -33,9 +33,9 @@ The smallest end-to-end path is the [`noir-examples/basic`](./noir-examples/basi
 
 ```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
+cargo run --release --bin provekit-cli -- prepare
+cargo run --release --bin provekit-cli -- prove
+cargo run --release --bin provekit-cli -- verify
 ```
 
 `prepare` writes a **ProveKit Prover** key (`.pkp`) and a **ProveKit Verifier** key (`.pkv`). `prove` reads the PKP plus `Prover.toml` and writes `proof.np`. `verify` reads the PKV and the proof.
@@ -89,6 +89,10 @@ fn main(plains: [Field; 2], result: Field) {
 
 For larger circuits and integration experiments, see [`noir-examples/`](./noir-examples/).
 
+For the full end-to-end handbook, including artifact generation, Rust, JS/TypeScript,
+Swift, Kotlin, troubleshooting, and deployment checklists, see
+[`docs/`](./docs/).
+
 ## Repository Map
 
 | Layer | Path | Crate/package | Purpose |

docs/.gitignore

@@ -0,0 +1,9 @@
+# Local website build artifacts
+node_modules/
+dist/
+.astro/
+
+# Root .gitignore ignores *.json because the Rust workspace emits proof artifacts.
+# Keep the website's source/config JSON files trackable.
+!pnpm-lock.yaml
+!tsconfig.json

docs/README.md

@@ -0,0 +1,48 @@
+# ProveKit Docs Website
+
+Standalone documentation website for ProveKit, built with Astro and Starlight.
+
+The public docs are organized by task:
+
+- **Start here:** installation, setup, and first proof.
+- **Build and integrate:** end-to-end artifact generation and host-language integration paths.
+- **Concepts:** proving flow, artifact lifecycle, and trust boundaries.
+- **Reference:** CLI commands, versioning policy, glossary, and production readiness.
+- **Troubleshooting:** failure diagnosis and recovery steps.
+
+## Commands
+
+```sh
+cd docs
+corepack enable
+pnpm install
+pnpm check
+pnpm dev
+pnpm build
+```
+
+Run `pnpm check` and `pnpm build` before publishing documentation changes.
+
+## Content layout
+
+Documentation source lives in `src/content/docs/`.
+
+- `index.mdx` is the docs homepage.
+- Section folders map to URL paths, for example `getting-started/quickstart.mdx` -> `/getting-started/quickstart/`.
+- Sidebar structure is configured in `astro.config.mjs`.
+- Custom theme polish lives in `src/styles/starlight.css`.
+- Conceptual pages live under `concepts/`.
+- Integration and end-to-end pages live under `e2e/` and `integrations/`.
+- Reference pages live under `reference/`.
+- Troubleshooting pages live under `troubleshooting/`.
+
+The repository root `README.md` remains the project entry point for contributors and the CLI quick start.
+
+## Writing standards
+
+- Keep runnable commands copy-pasteable from a fresh checkout.
+- Prefer explicit artifact paths in production and CI examples.
+- State generated files, owners, and regeneration rules.
+- Separate tutorials, how-to material, conceptual explanation, and reference content.
+- Mark active-development caveats instead of implying stable guarantees.
+- Link to source files or reference pages when a claim depends on implementation details.

docs/astro.config.mjs

@@ -0,0 +1,102 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  site: 'https://docs.provekit.dev',
+  publicDir: '../assets',
+  integrations: [
+    starlight({
+      title: 'ProveKit Docs',
+      description:
+        'Documentation for compiling Noir programs to R1CS, generating WHIR proofs, and integrating ProveKit across native, browser, mobile, service, and recursive-verifier environments.',
+      tagline: 'Noir to WHIR proofs, from first proof to production integration.',
+      favicon: '/favicon.svg',
+      logo: {
+        // Dark wordmark for light mode (ink #2D2D2B), pale brand-ink for dark mode.
+        light: './src/assets/logo-light.svg',
+        dark: './src/assets/logo.svg',
+        alt: 'ProveKit',
+        replacesTitle: true,
+      },
+      customCss: ['./src/styles/starlight.css'],
+      // Force light as the canonical theme on first visit (brand is light-only).
+      // Toggle still works for users who switch.
+      head: [
+        {
+          tag: 'script',
+          content: `(()=>{try{if(!localStorage.getItem('starlight-theme'))localStorage.setItem('starlight-theme','light');}catch(e){}})();`,
+        },
+      ],
+      lastUpdated: true,
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 3,
+      },
+      editLink: {
+        baseUrl: 'https://github.com/worldfnd/provekit/edit/main/docs/',
+      },
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/worldfnd/provekit',
+        },
+      ],
+      sidebar: [
+        {
+          label: 'Start here',
+          items: [
+            { label: 'Overview', link: '/' },
+            { slug: 'concepts/what-is-provekit', label: 'What is ProveKit?' },
+            { slug: 'getting-started/installation' },
+            { slug: 'getting-started/quickstart' },
+            { slug: 'getting-started/tutorial', label: 'Tutorial: prove without revealing' },
+          ],
+        },
+        {
+          label: 'Build and integrate',
+          items: [
+            { slug: 'e2e/overview' },
+            { slug: 'e2e/generate-artifacts' },
+            { slug: 'e2e/rust' },
+            { slug: 'e2e/js-typescript' },
+            { slug: 'e2e/swift' },
+            { slug: 'e2e/kotlin' },
+            { slug: 'integrations/overview' },
+            { slug: 'reference/starter-template', label: 'Starter templates' },
+          ],
+        },
+        {
+          label: 'Concepts',
+          items: [
+            { slug: 'concepts/proving-flow' },
+            { slug: 'concepts/designing-circuits', label: 'Designing circuits for ProveKit' },
+            { slug: 'concepts/artifact-lifecycle' },
+            { slug: 'concepts/security-model' },
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { slug: 'cli/overview', label: 'CLI reference' },
+            { slug: 'reference/performance' },
+            { slug: 'reference/comparison', label: 'How ProveKit compares' },
+            { slug: 'reference/examples', label: 'Examples catalog' },
+            { slug: 'reference/error-codes', label: 'FFI error codes' },
+            { slug: 'reference/faq', label: 'FAQ' },
+            { slug: 'reference/glossary' },
+          ],
+        },
+        {
+          label: 'Operations',
+          items: [
+            { slug: 'reference/production-checklist' },
+            { slug: 'reference/project-status', label: 'Project status' },
+            { slug: 'reference/changelog' },
+            { slug: 'troubleshooting/common-errors', label: 'Troubleshooting' },
+          ],
+        },
+      ],
+    }),
+  ],
+});

docs/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "provekit-docs",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "check": "astro sync && tsc --noEmit",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.39.1",
+    "astro": "^6.3.1"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
+}