Align repository with Kovina Repository Standard

CONTRIBUTING.md

@@ -1,57 +1,11 @@
-# Contributing
+# Contributing to OpenProof
 
-Thanks for helping improve OpenProof. The project is intentionally small, privacy-first, and zero-backend for the MVP.
+Please see [docs/Contributing.md](docs/Contributing.md) for the full contributing guide.
 
-## Development Setup
+## Quick Links
+- [Development Setup](docs/Development.md)
+- [Architecture](docs/Architecture.md)
+- [Deployment](docs/Deployment.md)
+- [Testing](docs/Testing.md)
 
-```bash
-npm install
-cp .env.example .env.local
-npm run dev
-```
-
-Before opening a pull request, run:
-
-```bash
-npm run lint
-npm run typecheck
-npm run build
-npm run test:contracts
-```
-
-## Product Boundaries
-
-Keep contributions aligned with the core model:
-
-- Hash files locally in the browser.
-- Register only hashes on Base Sepolia.
-- Avoid server-side file uploads.
-- Avoid mandatory databases, storage buckets, accounts, or IPFS.
-- Do not add tokens, NFTs, staking, DeFi, social feeds, or ownership/legal overclaims.
-- Do not commit private keys, wallet secrets, RPC secrets, or deployment credentials.
-
-## Pull Requests
-
-Good pull requests include:
-
-- A short description of the change.
-- The commands used to validate it.
-- Screenshots or recordings for UI changes.
-- Updated documentation for behavior, setup, or security changes.
-- Focused scope; unrelated refactors should be separate.
-
-Security-sensitive changes should also update [`SECURITY.md`](SECURITY.md) or [`docs/threat-model.md`](docs/threat-model.md) when relevant.
-
-## Commit Style
-
-Use clear, practical commit messages. Prefer:
-
-```text
-Improve receipt import validation
-Add proof explorer empty state
-Harden Base Sepolia network handling
-```
-
-## License
-
-By contributing, you agree that your contribution is licensed under AGPL-3.0-only.
+By contributing, you agree that your contributions will be licensed under AGPLv3.

docs/Architecture.md

@@ -0,0 +1,13 @@
+# Architecture
+
+The canonical architecture document is at [`docs/ARCHITECTURE.md`](ARCHITECTURE.md).
+
+For additional architectural context, see:
+
+- [Architectural Invariants](ARCHITECTURAL_INVARIANTS.md)
+- [Data Flow](DATA_FLOW.md)
+- [Trust Model](TRUST_MODEL.md)
+- [Trust Boundaries](TRUST_BOUNDARIES.md)
+- [Failure Modes](FAILURE_MODES.md)
+- [Design Restraints](DESIGN_RESTRAINTS.md)
+- [Systems Doctrine](SYSTEMS_DOCTRINE.md)

docs/Contributing.md

@@ -0,0 +1,52 @@
+# Contributing to OpenProof
+
+Thank you for your interest in OpenProof. The project is intentionally small, privacy-first, and zero-backend for the MVP.
+
+## Quick Start
+
+See [`docs/Development.md`](Development.md) for full setup instructions.
+
+## Before Submitting a Pull Request
+
+```bash
+npm run lint
+npm run typecheck
+npm run build
+npm run test:contracts
+```
+
+For UI changes, include screenshots. For security-sensitive changes, update the threat model or security policy.
+
+## Product Boundaries
+
+- Hash files locally in the browser.
+- Register only hashes on Base Sepolia.
+- Avoid server-side file uploads, databases, storage buckets, accounts, or IPFS.
+- Do not add tokens, NFTs, staking, DeFi, social feeds, or ownership/legal overclaims.
+- Do not commit private keys, wallet secrets, or deployment credentials.
+
+## Pull Request Guidelines
+
+- Short description of the change.
+- Commands used to validate it.
+- Screenshots for UI changes.
+- Updated documentation for behavior, setup, or security changes.
+- Focused scope; unrelated refactors in separate PRs.
+
+## Commit Style
+
+Use clear, practical commit messages:
+
+```text
+Improve receipt import validation
+Add proof explorer empty state
+Harden Base Sepolia network handling
+```
+
+## License
+
+By contributing, you agree that your contributions are licensed under AGPL-3.0-only.
+
+---
+
+*For the full contributing guide, see [`CONTRIBUTING.md`](../CONTRIBUTING.md) at the repository root.*

docs/Deployment.md

@@ -0,0 +1,27 @@
+# Deployment
+
+OpenProof deploys as a static Next.js app with no backend services required.
+
+## Deploy to Vercel
+
+1. Fork or clone this repository.
+2. Import it into [Vercel](https://vercel.com).
+3. Add the public environment variables:
+   - `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`
+   - `NEXT_PUBLIC_CHAIN_ID=84532`
+   - `NEXT_PUBLIC_OPENPROOF_CONTRACT_ADDRESS`
+4. Deploy with the default Next.js settings.
+
+No paid domain, database, storage bucket, file uploads, or IPFS pinning service is required for the MVP.
+
+## Contract Deployment
+
+```bash
+npm run compile
+npm run test:contracts
+npm run deploy:base-sepolia
+```
+
+Contract deployment requires `BASE_SEPOLIA_RPC_URL` and `DEPLOYER_PRIVATE_KEY` in `.env`.
+
+For additional deployment notes, see [`docs/deployment-notes.md`](deployment-notes.md).

docs/Development.md

@@ -0,0 +1,56 @@
+# Development
+
+## Prerequisites
+
+- Node.js 22 or newer
+- npm
+- A WalletConnect project ID from [Reown Cloud](https://cloud.reown.com/)
+- Base Sepolia test ETH for contract deployment or proof registration
+
+## Setup
+
+```bash
+git clone https://github.com/sparshsam/openproof.git
+cd openproof
+npm install
+cp .env.example .env.local
+npm run dev
+```
+
+Open `http://localhost:3000`.
+
+## Environment Variables
+
+Fill these values in `.env.local`:
+
+| Variable | Description |
+|---|---|
+| `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` | WalletConnect project ID (required) |
+| `NEXT_PUBLIC_CHAIN_ID` | Chain ID — set to `84532` for Base Sepolia |
+| `NEXT_PUBLIC_OPENPROOF_CONTRACT_ADDRESS` | Deployed registry contract address |
+| `BASE_SEPOLIA_RPC_URL` | RPC URL for Base Sepolia (`https://sepolia.base.org`) |
+| `DEPLOYER_PRIVATE_KEY` | Private key for contract deployment (never commit) |
+
+Never commit private keys. `.env` and `.env.local` are ignored by git.
+
+## Useful Commands
+
+```bash
+npm run dev          # Start development server
+npm run lint         # Run ESLint
+npm run typecheck    # Run TypeScript type checking
+npm run build        # Production build
+npm run compile      # Compile Solidity contracts
+npm run test:contracts  # Run Hardhat contract tests
+npm run deploy:base-sepolia  # Deploy registry contract
+```
+
+## Contract Commands
+
+```bash
+npm run compile                # Compile Solidity contracts
+npm run test:contracts         # Run contract tests
+npm run deploy:base-sepolia    # Deploy to Base Sepolia
+```
+
+Deployment requires `BASE_SEPOLIA_RPC_URL` and `DEPLOYER_PRIVATE_KEY` in `.env`.

docs/Testing.md

@@ -0,0 +1,41 @@
+# Testing
+
+Run these checks before submitting a pull request:
+
+## Lint
+
+```bash
+npm run lint
+```
+
+Runs ESLint across the codebase.
+
+## TypeScript Type Checking
+
+```bash
+npm run typecheck
+```
+
+Ensures all TypeScript types are correct.
+
+## Production Build
+
+```bash
+npm run build
+```
+
+Verifies the Next.js app builds without errors.
+
+## Contract Tests
+
+```bash
+npm run test:contracts
+```
+
+Runs Hardhat tests for the Solidity registry contract.
+
+## All Checks in One Command
+
+```bash
+npm run lint && npm run typecheck && npm run build && npm run test:contracts
+```