diff --git a/DOCS_NAVIGATION.md b/DOCS_NAVIGATION.md new file mode 100644 index 0000000..a2cde72 --- /dev/null +++ b/DOCS_NAVIGATION.md @@ -0,0 +1,239 @@ +# Documentation Navigation Guide + +**Last Updated:** 2025-11-21 + +This guide helps you navigate GenesisGraph documentation using **incremental reveal** principles - start simple, add depth progressively. + +## 🎯 Quick Start: Choose Your Learning Path + +### Path 1: "I Want to Try It" (10 minutes) +**For:** Developers who learn by doing + +1. [Quickstart](docs/getting-started/quickstart.md) (5 min) - Guitar hanger example +2. [Examples](docs/getting-started/examples.md) (5 min) - Hands-on code +3. Try: `genesisgraph validate examples/basic-pipeline.gg.yaml` + +### Path 2: "I Need to Understand It" (20 minutes) +**For:** Engineers evaluating adoption + +1. [README](README.md) (5 min) - What is GenesisGraph? +2. [Disclosure Levels](docs/user-guide/disclosure-levels.md) (10 min) - A/B/C model explained +3. [User Guide Overview](docs/user-guide/overview.md) (5 min) - Feature landscape + +### Path 3: "I'm Building With It" (45 minutes) +**For:** Developers integrating GenesisGraph + +1. [Architecture](docs/developer-guide/architecture.md) (15 min) - System design +2. [Use Cases](docs/use-cases.md) (15 min) - Integration patterns +3. [SDK Quick Reference](docs/reference/sdk-quick-reference.md) (15 min) - API lookup + +### Path 4: "I'm Making Decisions" (30 minutes) +**For:** Executives, product managers, researchers + +1. [FAQ](docs/faq.md) (10 min) - Common objections answered +2. [Vision](docs/strategic/vision.md) (15 min) - Why this matters +3. [Roadmap](docs/strategic/roadmap.md) (5 min) - Maturity & timeline + +--- + +## πŸ“š Documentation Structure β€” Four Layers + +GenesisGraph documentation follows **incremental reveal**: each layer builds on the previous. + +### Layer 1: Essential Basics (5-10 minutes) +**Goal:** Understand what GenesisGraph is and why it matters + +| Document | Purpose | Time | +|----------|---------|------| +| [Installation](docs/getting-started/installation.md) | Set up SDKs | 2 min | +| [Quickstart](docs/getting-started/quickstart.md) | Simplest tutorial | 5 min | +| [Examples](docs/getting-started/examples.md) | Hands-on code | 5 min | +| **[Disclosure Levels](docs/user-guide/disclosure-levels.md)** | **Core innovation: A/B/C model** | **10 min** | + +**Key Concept:** Three-level selective disclosure (A=full, B=verified, C=zero-knowledge) + +--- + +### Layer 2: User Guidance (15-45 minutes) +**Goal:** Learn how to use GenesisGraph features effectively + +| Document | Purpose | Time | +|----------|---------|------| +| [User Guide Overview](docs/user-guide/overview.md) | Feature landscape | 15 min | +| [DID & Identity](docs/user-guide/did-web-guide.md) | Enterprise identity (did:web) | 15 min | +| [Selective Disclosure](docs/user-guide/selective-disclosure.md) | SD-JWT, BBS+, cryptography | 20 min | +| [Transparency Logs](docs/user-guide/transparency-log.md) | RFC 6962 audit trails | 15 min | +| [Profile Validators](docs/user-guide/profile-validators.md) | Industry compliance | 15 min | +| [Use Cases](docs/use-cases.md) | Real-world integrations | 15 min | +| [FAQ](docs/faq.md) | Common questions | 10 min | + +**Key Skills:** Choose disclosure level, set up identity, implement features + +--- + +### Layer 3: Technical Depth (30-90 minutes) +**Goal:** Understand architecture and integrate with your systems + +| Document | Purpose | Time | +|----------|---------|------| +| [Architecture](docs/developer-guide/architecture.md) | System design | 30 min | +| [Contributing](docs/developer-guide/contributing.md) | Contribution guidelines | 15 min | +| [Security](docs/developer-guide/security.md) | Security model | 20 min | +| [Troubleshooting](docs/developer-guide/troubleshooting.md) | Common issues | 15 min | +| [SDK Development Guide](docs/reference/sdk-development-guide.md) | Extend SDKs | 45 min | +| [SDK Quick Reference](docs/reference/sdk-quick-reference.md) | API lookup | 15 min | +| [Implementation Status](docs/reference/implementation-summary.md) | Feature coverage | 10 min | +| [Main Specification](docs/specifications/main-spec.md) | Formal standard | 60 min | +| [ZKP Templates](docs/specifications/zkp-templates.md) | Zero-knowledge proofs | 30 min | + +**Key Skills:** Integrate GenesisGraph, extend functionality, understand formal spec + +--- + +### Layer 4: Strategic Context (20-60 minutes) +**Goal:** Understand vision, roadmap, and planning for adoption + +| Document | Purpose | Time | +|----------|---------|------| +| [Vision](docs/strategic/vision.md) | Why it matters, 5-year plan | 20 min | +| [Roadmap](docs/strategic/roadmap.md) | v0.3.0 β†’ v1.0 development | 25 min | +| [Critical Gaps](docs/strategic/critical-gaps.md) | Strategic gaps analysis | 30 min | + +**Key Insights:** Adoption strategy, maturity level, investment planning + +--- + +## 🧭 Navigation by Role + +### Developers +``` +1. [Quickstart](docs/getting-started/quickstart.md) +2. [Examples](docs/getting-started/examples.md) +3. [Architecture](docs/developer-guide/architecture.md) +4. [SDK Reference](docs/reference/sdk-quick-reference.md) +``` + +### Decision-Makers +``` +1. [FAQ](docs/faq.md) +2. [Use Cases](docs/use-cases.md) +3. [Vision](docs/strategic/vision.md) +4. [Roadmap](docs/strategic/roadmap.md) +``` + +### AI/ML Engineers +``` +1. [Disclosure Levels](docs/user-guide/disclosure-levels.md) +2. [Use Cases: AI Pipelines](docs/use-cases.md#ai-pipelines) +3. [Profile Validators](docs/user-guide/profile-validators.md) +4. [Selective Disclosure](docs/user-guide/selective-disclosure.md) +``` + +### Researchers +``` +1. [Main Specification](docs/specifications/main-spec.md) +2. [Selective Disclosure](docs/user-guide/selective-disclosure.md) +3. [ZKP Templates](docs/specifications/zkp-templates.md) +4. [Architecture](docs/developer-guide/architecture.md) +``` + +--- + +## πŸ“– Progressive Reading Tools + +### Progressive Reveal CLI +Consume documentation at your own pace: + +```bash +# Install +cd tools/progressive-reveal-cli && pip install -e . + +# Explore at different depth levels +reveal docs/getting-started/quickstart.md --level 1 # Structure only +reveal docs/user-guide/overview.md --level 2 # With previews +reveal docs/faq.md --level 3 --grep "blockchain" # Full search +``` + +**Full guide:** [Document Explorer Guide](DOCUMENT_EXPLORER_GUIDE.md) + +--- + +## πŸ—ΊοΈ Documentation Map + +``` +README.md (Entry point) +β”œβ”€β”€ Layer 1: Getting Started +β”‚ β”œβ”€β”€ Installation +β”‚ β”œβ”€β”€ Quickstart +β”‚ β”œβ”€β”€ Examples +β”‚ └── ⭐ Disclosure Levels (Core concept) +β”‚ +β”œβ”€β”€ Layer 2: User Guidance +β”‚ β”œβ”€β”€ User Guide Overview +β”‚ β”œβ”€β”€ Feature Guides +β”‚ β”‚ β”œβ”€β”€ DID & Identity +β”‚ β”‚ β”œβ”€β”€ Selective Disclosure +β”‚ β”‚ β”œβ”€β”€ Transparency Logs +β”‚ β”‚ └── Profile Validators +β”‚ β”œβ”€β”€ Use Cases & Integration +β”‚ └── FAQ +β”‚ +β”œβ”€β”€ Layer 3: Technical Depth +β”‚ β”œβ”€β”€ Developer Guide +β”‚ β”‚ β”œβ”€β”€ Architecture +β”‚ β”‚ β”œβ”€β”€ Contributing +β”‚ β”‚ β”œβ”€β”€ Security +β”‚ β”‚ └── Troubleshooting +β”‚ β”œβ”€β”€ Reference +β”‚ β”‚ β”œβ”€β”€ SDK Development +β”‚ β”‚ β”œβ”€β”€ SDK Quick Reference +β”‚ β”‚ └── Implementation Status +β”‚ └── Specifications +β”‚ β”œβ”€β”€ Main Spec (formal) +β”‚ └── ZKP Templates +β”‚ +└── Layer 4: Strategic Context + β”œβ”€β”€ Vision (why it matters) + β”œβ”€β”€ Roadmap (v0.3 β†’ v1.0) + └── Critical Gaps (planning) +``` + +--- + +## πŸ” Finding What You Need + +### "I want to understand the core innovation" +β†’ [Disclosure Levels (A/B/C)](docs/user-guide/disclosure-levels.md) + +### "I need to see real examples" +β†’ [Use Cases](docs/use-cases.md) +β†’ [Examples](docs/getting-started/examples.md) + +### "I have questions" +β†’ [FAQ](docs/faq.md) +β†’ [Troubleshooting](docs/developer-guide/troubleshooting.md) + +### "I'm integrating GenesisGraph" +β†’ [Architecture](docs/developer-guide/architecture.md) +β†’ [SDK Quick Reference](docs/reference/sdk-quick-reference.md) + +### "I need the formal specification" +β†’ [Main Specification](docs/specifications/main-spec.md) + +### "I'm evaluating for adoption" +β†’ [Vision](docs/strategic/vision.md) +β†’ [Roadmap](docs/strategic/roadmap.md) +β†’ [FAQ](docs/faq.md) + +--- + +## πŸ“¦ Related Files + +- **[README.md](README.md)** - Main entry point with progressive learning paths +- **[mkdocs.yml](mkdocs.yml)** - MkDocs site configuration (matches this structure) +- **[DOCUMENT_EXPLORER_GUIDE.md](DOCUMENT_EXPLORER_GUIDE.md)** - Progressive reveal CLI guide +- **[CHANGELOG.md](CHANGELOG.md)** - Version history + +--- + +**Need help?** Start with the [README](README.md) or jump to your role-specific path above! diff --git a/DOCUMENT_EXPLORER_GUIDE.md b/DOCUMENT_EXPLORER_GUIDE.md index 387cae6..067227e 100644 --- a/DOCUMENT_EXPLORER_GUIDE.md +++ b/DOCUMENT_EXPLORER_GUIDE.md @@ -37,37 +37,37 @@ reveal README.md --level 3 --page-size 50 **2. Get Started in 5 Minutes** ```bash # See structure -reveal QUICKSTART.md --level 1 +reveal docs/getting-started/quickstart.md --level 1 # Preview steps -reveal QUICKSTART.md --level 2 +reveal docs/getting-started/quickstart.md --level 2 # Follow along -reveal QUICKSTART.md --level 3 +reveal docs/getting-started/quickstart.md --level 3 ``` **3. Explore Real Use Cases** ```bash # See available use cases -reveal USE_CASES.md --level 1 +reveal docs/use-cases.md --level 1 # Find your industry -reveal USE_CASES.md --level 2 --grep "manufacturing|AI|science" +reveal docs/use-cases.md --level 2 --grep "manufacturing|AI|science" # Deep dive -reveal USE_CASES.md --level 3 --grep "manufacturing" --context 5 +reveal docs/use-cases.md --level 3 --grep "manufacturing" --context 5 ``` **4. Common Questions** ```bash # See all FAQ topics -reveal FAQ.md --level 1 +reveal docs/faq.md --level 1 # Find specific questions -reveal FAQ.md --level 2 --grep "blockchain|PROV-O|performance" +reveal docs/faq.md --level 2 --grep "blockchain|PROV-O|performance" # Read answers -reveal FAQ.md --level 3 --grep "Why not blockchain" --context 10 +reveal docs/faq.md --level 3 --grep "Why not blockchain" --context 10 ``` --- @@ -89,10 +89,10 @@ reveal docs/developer-guide/architecture.md --level 3 **6. SDK Documentation** ```bash # SDK guide structure -reveal SDK-DEVELOPMENT-GUIDE.md --level 1 +reveal docs/reference/sdk-development-guide.md --level 1 # Quick reference -reveal SDK-QUICK-REFERENCE.md --level 2 +reveal docs/reference/sdk-quick-reference.md --level 2 # Python examples reveal sdks/python/README.md --level 2 @@ -103,26 +103,29 @@ reveal sdks/javascript/README.md --level 2 **7. Feature Guides** ```bash +# Disclosure levels (CORE CONCEPT) +reveal docs/user-guide/disclosure-levels.md --level 2 + # Enterprise identity (did:web) -reveal docs/DID_WEB_GUIDE.md --level 2 +reveal docs/user-guide/did-web-guide.md --level 2 # Privacy patterns -reveal docs/SELECTIVE_DISCLOSURE.md --level 2 +reveal docs/user-guide/selective-disclosure.md --level 2 # Transparency logs -reveal docs/TRANSPARENCY_LOG.md --level 2 +reveal docs/user-guide/transparency-log.md --level 2 # Zero-knowledge proofs -reveal docs/ZKP_TEMPLATES.md --level 2 +reveal docs/specifications/zkp-templates.md --level 2 # Industry compliance -reveal docs/PROFILE_VALIDATORS.md --level 2 +reveal docs/user-guide/profile-validators.md --level 2 ``` **8. Security** ```bash # Security considerations -reveal SECURITY.md --level 1 +reveal docs/developer-guide/security.md --level 1 # Audit findings reveal SECURITY_AUDIT_FINDINGS.md --level 1 --grep "CRITICAL|HIGH" @@ -138,37 +141,37 @@ reveal SECURITY_AUDIT_FINDINGS.md --level 3 **9. Project Vision** ```bash # Strategic context -reveal STRATEGIC_CONTEXT.md --level 1 +reveal docs/strategic/vision.md --level 1 # Vision and roadmap -reveal STRATEGIC_CONTEXT.md --level 2 +reveal docs/strategic/vision.md --level 2 # 5-year plan -reveal STRATEGIC_CONTEXT.md --level 3 --grep "adoption|market" +reveal docs/strategic/vision.md --level 3 --grep "adoption|market" ``` **10. Current Status & Roadmap** ```bash # What's implemented -reveal ROADMAP.md --level 1 +reveal docs/strategic/roadmap.md --level 1 # Current gaps -reveal ROADMAP.md --level 2 --grep "v1.0|milestone" +reveal docs/strategic/roadmap.md --level 2 --grep "v1.0|milestone" # Full roadmap -reveal ROADMAP.md --level 3 +reveal docs/strategic/roadmap.md --level 3 ``` **11. Critical Analysis** ```bash # All gaps overview -reveal CRITICAL_GAPS_ANALYSIS.md --level 1 +reveal docs/strategic/critical-gaps.md --level 1 # Critical gaps only -reveal CRITICAL_GAPS_ANALYSIS.md --level 2 --grep "CRITICAL" +reveal docs/strategic/critical-gaps.md --level 2 --grep "CRITICAL" # Difficulty analysis -reveal CRITICAL_GAPS_ANALYSIS.md --level 3 --grep "Exceptionally Hard" --context 10 +reveal docs/strategic/critical-gaps.md --level 3 --grep "Exceptionally Hard" --context 10 ``` --- @@ -178,22 +181,22 @@ reveal CRITICAL_GAPS_ANALYSIS.md --level 3 --grep "Exceptionally Hard" --context **12. Main Specification** ```bash # Spec metadata (886 lines!) -reveal spec/MAIN_SPEC.md +reveal docs/specifications/main-spec.md # Spec structure -reveal spec/MAIN_SPEC.md --level 1 +reveal docs/specifications/main-spec.md --level 1 # Specific sections -reveal spec/MAIN_SPEC.md --level 2 --grep "attestation|verification|disclosure" +reveal docs/specifications/main-spec.md --level 2 --grep "attestation|verification|disclosure" # Deep dive -reveal spec/MAIN_SPEC.md --level 3 --grep "cryptographic" --context 5 +reveal docs/specifications/main-spec.md --level 3 --grep "cryptographic" --context 5 ``` **13. Implementation Details** ```bash # Implementation summary -reveal IMPLEMENTATION_SUMMARY.md --level 2 +reveal docs/reference/implementation-summary.md --level 2 # Change history reveal CHANGELOG.md --level 2 @@ -217,8 +220,8 @@ done ```bash # Compare SDK documentation -reveal SDK-DEVELOPMENT-GUIDE.md --level 1 > /tmp/sdk-dev.txt -reveal SDK-QUICK-REFERENCE.md --level 1 > /tmp/sdk-ref.txt +reveal docs/reference/sdk-development-guide.md --level 1 > /tmp/sdk-dev.txt +reveal docs/reference/sdk-quick-reference.md --level 1 > /tmp/sdk-ref.txt diff /tmp/sdk-dev.txt /tmp/sdk-ref.txt ``` @@ -229,7 +232,7 @@ diff /tmp/sdk-dev.txt /tmp/sdk-ref.txt reveal README.md --level 3 --grep "```yaml" --context 10 # Search for Python code -reveal SDK-DEVELOPMENT-GUIDE.md --level 3 --grep "def |class " --context 3 +reveal docs/reference/sdk-development-guide.md --level 3 --grep "def |class " --context 3 ``` ### Explore by File Size @@ -251,78 +254,92 @@ done | sort -t: -k2 -n ### Workflow 1: "I Need to Integrate GenesisGraph" 1. `reveal README.md --level 2` - Understand the basics -2. `reveal QUICKSTART.md --level 3` - Follow tutorial -3. `reveal USE_CASES.md --level 3 --grep "your-industry"` - See relevant examples -4. `reveal SDK-QUICK-REFERENCE.md --level 2` - API overview +2. `reveal docs/getting-started/quickstart.md --level 3` - Follow tutorial +3. `reveal docs/use-cases.md --level 3 --grep "your-industry"` - See relevant examples +4. `reveal docs/reference/sdk-quick-reference.md --level 2` - API overview 5. `reveal docs/developer-guide/troubleshooting.md --level 2` - Common issues ### Workflow 2: "I'm Evaluating GenesisGraph" 1. `reveal README.md --level 1` - High-level structure -2. `reveal FAQ.md --level 3 --grep "why not|vs|comparison"` - Compare alternatives -3. `reveal STRATEGIC_CONTEXT.md --level 2` - Vision and maturity -4. `reveal ROADMAP.md --level 2` - Implementation status +2. `reveal docs/faq.md --level 3 --grep "why not|vs|comparison"` - Compare alternatives +3. `reveal docs/strategic/vision.md --level 2` - Vision and maturity +4. `reveal docs/strategic/roadmap.md --level 2` - Implementation status 5. `reveal SECURITY_AUDIT_FINDINGS.md --level 1` - Risk assessment ### Workflow 3: "I Want to Contribute" -1. `reveal CONTRIBUTING.md --level 3` - Guidelines -2. `reveal ROADMAP.md --level 2 --grep "TODO|future|planned"` - Open work -3. `reveal CRITICAL_GAPS_ANALYSIS.md --level 2` - High-impact areas +1. `reveal docs/developer-guide/contributing.md --level 3` - Guidelines +2. `reveal docs/strategic/roadmap.md --level 2 --grep "TODO|future|planned"` - Open work +3. `reveal docs/strategic/critical-gaps.md --level 2` - High-impact areas 4. `reveal docs/developer-guide/architecture.md --level 2` - System design -5. `reveal SDK-DEVELOPMENT-GUIDE.md --level 3` - Implementation patterns +5. `reveal docs/reference/sdk-development-guide.md --level 3` - Implementation patterns ### Workflow 4: "I'm Writing a Paper" -1. `reveal spec/MAIN_SPEC.md --level 1` - Specification structure +1. `reveal docs/specifications/main-spec.md --level 1` - Specification structure 2. `reveal README.md --level 3 --grep "citation|reference"` - How to cite -3. `reveal STRATEGIC_CONTEXT.md --level 3` - Problem space analysis -4. `reveal USE_CASES.md --level 3` - Application domains -5. `reveal CRITICAL_GAPS_ANALYSIS.md --level 3` - Future research directions +3. `reveal docs/strategic/vision.md --level 3` - Problem space analysis +4. `reveal docs/use-cases.md --level 3` - Application domains +5. `reveal docs/strategic/critical-gaps.md --level 3` - Future research directions --- -## Document Inventory - -### Root-Level Documents (16 files) - -| Priority | Document | Purpose | Lines | Audience | -|----------|----------|---------|-------|----------| -| ⭐⭐⭐ | README.md | Main entry point | 704 | Everyone | -| ⭐⭐⭐ | QUICKSTART.md | 5-minute tutorial | 258 | New users | -| ⭐⭐⭐ | FAQ.md | Common questions | 551 | Evaluators | -| ⭐⭐ | USE_CASES.md | Integration patterns | 467 | Developers | -| ⭐⭐ | ROADMAP.md | Project status | 699 | Contributors | -| ⭐⭐ | SECURITY.md | Security model | 440 | Enterprise | -| ⭐ | STRATEGIC_CONTEXT.md | Vision & strategy | 372 | Decision-makers | -| ⭐ | CRITICAL_GAPS_ANALYSIS.md | Deep analysis | 1574 | Architects | -| ⭐ | IMPROVEMENT_PLAN.md | Tactical roadmap | 1131 | Core team | -| β€’ | CONTRIBUTING.md | Contributor guide | 200 | Contributors | -| β€’ | CHANGELOG.md | Release history | 352 | All users | -| β€’ | SECURITY_AUDIT_FINDINGS.md | Audit results | 583 | Security team | -| β€’ | SDK-DEVELOPMENT-GUIDE.md | SDK architecture | 1045 | SDK devs | -| β€’ | SDK-QUICK-REFERENCE.md | API reference | 350 | SDK users | -| β€’ | IMPLEMENTATION_SUMMARY.md | Status summary | 320 | Trackers | -| β€’ | claude.md | Claude config | 122 | Claude users | - -### Feature Documentation (/docs - 8 files) - -| Document | Purpose | Lines | -|----------|---------|-------| -| DID_WEB_GUIDE.md | Enterprise identity | 382 | -| SELECTIVE_DISCLOSURE.md | Privacy patterns | 413 | -| TRANSPARENCY_LOG.md | Audit trails | 351 | -| PROFILE_VALIDATORS.md | Industry compliance | 321 | -| ZKP_TEMPLATES.md | Zero-knowledge proofs | 411 | -| developer-guide/architecture.md | System design | 666 | -| developer-guide/troubleshooting.md | Common issues | 267 | -| getting-started/installation.md | Installation | 78 | - -### Specification (/spec - 1 file) - -| Document | Purpose | Lines | -|----------|---------|-------| -| MAIN_SPEC.md | Complete formal spec | 886 | +## Document Inventory β€” Organized by Layer + +### Layer 1: Getting Started + +| Priority | Document | Purpose | Audience | +|----------|----------|---------|----------| +| ⭐⭐⭐ | docs/getting-started/installation.md | Installation | New users | +| ⭐⭐⭐ | docs/getting-started/quickstart.md | 5-minute tutorial | New users | +| ⭐⭐⭐ | docs/getting-started/examples.md | Hands-on examples | Developers | +| ⭐⭐⭐ | docs/user-guide/disclosure-levels.md | **Core A/B/C model** | **Everyone** | + +### Layer 2: User Guidance + +| Priority | Document | Purpose | Audience | +|----------|----------|---------|----------| +| ⭐⭐⭐ | docs/user-guide/overview.md | Feature landscape | Implementers | +| ⭐⭐ | docs/user-guide/did-web-guide.md | Enterprise identity | Enterprise users | +| ⭐⭐ | docs/user-guide/selective-disclosure.md | Cryptographic privacy | Advanced users | +| ⭐⭐ | docs/user-guide/transparency-log.md | Audit trails | Compliance teams | +| ⭐⭐ | docs/user-guide/profile-validators.md | Industry compliance | Regulated industries | +| ⭐⭐⭐ | docs/use-cases.md | Real-world integrations | Developers | +| ⭐⭐⭐ | docs/faq.md | Common questions | Evaluators | + +### Layer 3: Technical Depth + +| Priority | Document | Purpose | Audience | +|----------|----------|---------|----------| +| ⭐⭐ | docs/developer-guide/architecture.md | System design | Developers | +| β€’ | docs/developer-guide/contributing.md | Contributor guide | Contributors | +| ⭐⭐ | docs/developer-guide/security.md | Security model | Enterprise | +| β€’ | docs/developer-guide/troubleshooting.md | Common issues | Support | +| ⭐⭐ | docs/reference/sdk-development-guide.md | SDK architecture | SDK developers | +| ⭐⭐ | docs/reference/sdk-quick-reference.md | API reference | SDK users | +| β€’ | docs/reference/implementation-summary.md | Status summary | Trackers | +| ⭐⭐⭐ | docs/specifications/main-spec.md | Formal specification | Implementers | +| ⭐ | docs/specifications/zkp-templates.md | Zero-knowledge proofs | Researchers | + +### Layer 4: Strategic Context + +| Priority | Document | Purpose | Audience | +|----------|----------|---------|----------| +| ⭐ | docs/strategic/vision.md | Vision & strategy | Decision-makers | +| ⭐⭐ | docs/strategic/roadmap.md | Development plan | Contributors | +| ⭐ | docs/strategic/critical-gaps.md | Strategic analysis | Architects | + +### Root-Level Files + +| Document | Purpose | Audience | +|----------|---------|----------| +| README.md | **Main entry point** | **Everyone** | +| CHANGELOG.md | Release history | All users | +| SECURITY_AUDIT_FINDINGS.md | Audit results | Security team | +| IMPROVEMENT_PLAN.md | Historical tactical plan | Core team | +| claude.md | Claude Code config | Claude users | +| DOCS_NAVIGATION.md | Documentation map | All users | --- @@ -341,13 +358,13 @@ When working with Claude Code, use progressive reveal to: # Task: "Update security documentation" # Step 1: Understand current security docs -reveal SECURITY.md --level 1 +reveal docs/developer-guide/security.md --level 1 # Step 2: Find relevant sections -reveal SECURITY.md --level 2 --grep "threat|attack" +reveal docs/developer-guide/security.md --level 2 --grep "threat|attack" # Step 3: Read specific sections -reveal SECURITY.md --level 3 --grep "threat model" --context 20 +reveal docs/developer-guide/security.md --level 3 --grep "threat model" --context 20 # Step 4: Check related docs reveal SECURITY_AUDIT_FINDINGS.md --level 2 --grep "CRITICAL" diff --git a/README.md b/README.md index 7922fe7..83f52f4 100644 --- a/README.md +++ b/README.md @@ -25,42 +25,85 @@ GenesisGraph is an **open standard for proving how things were made**. It provid --- -## πŸš€ Quick Start +## πŸš€ Quick Start β€” Choose Your Path -**New to GenesisGraph?** Start here: +**New to GenesisGraph?** Follow this progressive learning path: -1. **[QUICKSTART.md](QUICKSTART.md)** - 5-minute tutorial with simplest possible examples -2. **[USE_CASES.md](USE_CASES.md)** - Real-world integrations (AI, science, media) -3. **[FAQ.md](FAQ.md)** - Common questions: "Why not PROV-O?", "Do I need blockchain?", etc. -4. **[spec/MAIN_SPEC.md](spec/MAIN_SPEC.md)** - Complete specification (24,317 lines) +### Layer 1: Essential Basics (5-10 minutes) +Start here to understand what GenesisGraph is and why it matters: -**For developers and contributors:** +1. **[5-Minute Quickstart](docs/getting-started/quickstart.md)** - Simplest possible example (CAD file export) +2. **[Disclosure Levels (A/B/C)](docs/user-guide/disclosure-levels.md)** - **Core innovation**: Choose what to reveal -5. **[ROADMAP.md](ROADMAP.md)** - πŸ“ **PRIMARY ROADMAP** - Unified development plan from v0.3.0 β†’ v1.0 -6. **[STRATEGIC_CONTEXT.md](STRATEGIC_CONTEXT.md)** - Why this matters, adoption strategy, 5-year vision -7. **[CRITICAL_GAPS_ANALYSIS.md](CRITICAL_GAPS_ANALYSIS.md)** - Strategic analysis of 10 gaps for v1.0 (detailed context for roadmap) -8. **[IMPROVEMENT_PLAN.md](IMPROVEMENT_PLAN.md)** - Tactical implementation details (historical reference) +### Layer 2: User Guidance (15-30 minutes) +Learn how to use GenesisGraph features effectively: -**Enterprise users:** See **[docs/DID_WEB_GUIDE.md](docs/DID_WEB_GUIDE.md)** for did:web support - use your organization's domain for identity management. +3. **[User Guide Overview](docs/user-guide/overview.md)** - Progressive feature introduction +4. **[Examples & Use Cases](docs/use-cases.md)** - Real-world integrations (AI, manufacturing, research) +5. **[FAQ](docs/faq.md)** - Common questions: "Why not PROV-O?", "Do I need blockchain?" -**Want to integrate?** See `USE_CASES.md` Β§Integration Patterns for wrapper/native/post-hoc approaches. +### Layer 3: Technical Depth (30-60 minutes) +Understand the architecture and integrate with your systems: -**Explore documentation incrementally:** Use our Progressive Reveal CLI to understand docs at your own pace: +6. **[Architecture](docs/developer-guide/architecture.md)** - System design and components +7. **[Main Specification](docs/specifications/main-spec.md)** - Complete formal standard +8. **[SDK References](docs/reference/sdk-quick-reference.md)** - API quick lookup + +### Layer 4: Strategic Context (20-45 minutes) +Explore vision, roadmap, and planning for decision-makers: + +9. **[Vision & Why It Matters](docs/strategic/vision.md)** - 5-year adoption strategy +10. **[Roadmap](docs/strategic/roadmap.md)** - πŸ“ **PRIMARY ROADMAP** - v0.3.0 β†’ v1.0 +11. **[Critical Gaps Analysis](docs/strategic/critical-gaps.md)** - Strategic gaps for v1.0 + +--- + +### 🎯 Quick Navigation by Role + + + + + + + + + + +
πŸ‘¨β€πŸ’» Developers
+β†’ Quickstart
+β†’ Examples
+β†’ Architecture +		🏒 Decision-Makers
+β†’ FAQ
+β†’ Use Cases
+β†’ Vision +
πŸ€– AI/ML Engineers
+β†’ Disclosure Levels
+β†’ AI Examples
+β†’ AI Validators +		πŸ”¬ Researchers
+β†’ Specification
+β†’ Cryptography
+β†’ ZKP Templates +
+ +--- + +### πŸ“– Explore Documentation Incrementally + +Use our Progressive Reveal CLI to consume docs at your own pace: ```bash # Install the tool cd tools/progressive-reveal-cli && pip install -e . -# Quick exploration -./scripts/explore_docs.sh --level 0 --category essential - -# Or explore specific docs -reveal README.md --level 1 # See structure -reveal QUICKSTART.md --level 2 # Preview content -reveal FAQ.md --level 3 --grep "blockchain" # Search topics +# Explore by depth level +reveal docs/getting-started/quickstart.md --level 1 # See structure +reveal docs/user-guide/overview.md --level 2 # Preview content +reveal docs/faq.md --level 3 --grep "blockchain" # Search topics ``` -**See [DOCUMENT_EXPLORER_GUIDE.md](DOCUMENT_EXPLORER_GUIDE.md) for complete documentation exploration guide.** +**Full guide:** [Document Explorer Guide](DOCUMENT_EXPLORER_GUIDE.md) --- @@ -144,23 +187,47 @@ This package contains the complete v0.3 implementation with: ``` genesisgraph/ -β”œβ”€β”€ spec/ -β”‚ └── MAIN_SPEC.md # Updated specification with Β§9.2 selective disclosure +β”œβ”€β”€ docs/ # Organized documentation (see mkdocs.yml) +β”‚ β”œβ”€β”€ getting-started/ # Layer 1: Essential basics +β”‚ β”‚ β”œβ”€β”€ installation.md +β”‚ β”‚ β”œβ”€β”€ quickstart.md +β”‚ β”‚ └── examples.md +β”‚ β”œβ”€β”€ user-guide/ # Layer 2: Feature guides +β”‚ β”‚ β”œβ”€β”€ overview.md +β”‚ β”‚ β”œβ”€β”€ disclosure-levels.md # A/B/C model explained +β”‚ β”‚ β”œβ”€β”€ did-web-guide.md # Enterprise identity +β”‚ β”‚ β”œβ”€β”€ selective-disclosure.md # SD-JWT, BBS+ cryptography +β”‚ β”‚ β”œβ”€β”€ transparency-log.md # RFC 6962 audit trails +β”‚ β”‚ └── profile-validators.md # Industry compliance +β”‚ β”œβ”€β”€ developer-guide/ # Layer 3: Architecture & integration +β”‚ β”‚ β”œβ”€β”€ architecture.md +β”‚ β”‚ β”œβ”€β”€ contributing.md +β”‚ β”‚ β”œβ”€β”€ security.md +β”‚ β”‚ └── troubleshooting.md +β”‚ β”œβ”€β”€ reference/ # API & SDK reference +β”‚ β”‚ β”œβ”€β”€ sdk-development-guide.md +β”‚ β”‚ β”œβ”€β”€ sdk-quick-reference.md +β”‚ β”‚ └── implementation-summary.md +β”‚ β”œβ”€β”€ specifications/ # Formal definitions +β”‚ β”‚ β”œβ”€β”€ main-spec.md # Complete specification +β”‚ β”‚ └── zkp-templates.md # Zero-knowledge proofs +β”‚ β”œβ”€β”€ strategic/ # Layer 4: Vision & planning +β”‚ β”‚ β”œβ”€β”€ vision.md +β”‚ β”‚ β”œβ”€β”€ roadmap.md +β”‚ β”‚ └── critical-gaps.md +β”‚ β”œβ”€β”€ use-cases.md # Real-world examples +β”‚ └── faq.md # Common questions β”œβ”€β”€ schema/ -β”‚ └── genesisgraph-core-v0.1.yaml # Core schema with selective disclosure support -β”œβ”€β”€ docs/ -β”‚ └── DID_WEB_GUIDE.md # Complete guide for did:web usage +β”‚ └── genesisgraph-core-v0.1.yaml # Core schema with selective disclosure β”œβ”€β”€ examples/ β”‚ β”œβ”€β”€ level-a-full-disclosure.gg.yaml # Level A: Full transparency -β”‚ β”œβ”€β”€ level-b-partial-envelope.gg.yaml # Level B: Policy claims only -β”‚ β”œβ”€β”€ level-c-sealed-subgraph.gg.yaml # Level C: Sealed subgraph with commitments -β”‚ β”œβ”€β”€ workflow-with-did-web.gg.yaml # Enterprise workflow using did:web -β”‚ β”œβ”€β”€ did-web-example.json # Sample DID document -β”‚ └── did-web-organization.json # Organization DID document with multiple keys +β”‚ β”œβ”€β”€ level-b-partial-envelope.gg.yaml # Level B: Verified privacy +β”‚ β”œβ”€β”€ level-c-sealed-subgraph.gg.yaml # Level C: Zero-knowledge +β”‚ └── workflow-with-did-web.gg.yaml # Enterprise workflow β”œβ”€β”€ scripts/ β”‚ β”œβ”€β”€ verify_sealed_subgraph.py # Merkle inclusion proof verifier β”‚ └── verify_transparency_anchoring.py # Transparency log anchor verifier -└── genesisgraph/ +└── genesisgraph/ # Python SDK implementation β”œβ”€β”€ did_resolver.py # DID resolution (did:key, did:web, did:ion, did:ethr) └── validator.py # Signature verification with DID support ``` @@ -203,7 +270,7 @@ validator = GenesisGraphValidator(verify_profile=True, profile_id='gg-cam-v1') result = validator.validate_file('manufacturing.gg.yaml') ``` -See **[docs/PROFILE_VALIDATORS.md](docs/PROFILE_VALIDATORS.md)** for complete documentation. +See **[Profile Validators Guide](docs/user-guide/profile-validators.md)** for complete documentation. --- @@ -243,7 +310,7 @@ sd_jwt = issuer.create_sd_jwt( ) ``` -See **[docs/SELECTIVE_DISCLOSURE.md](docs/SELECTIVE_DISCLOSURE.md)** for complete documentation and examples. +See **[Selective Disclosure Guide](docs/user-guide/selective-disclosure.md)** for complete documentation and examples. **Note:** Requires optional `credentials` dependencies: `pip install genesisgraph[credentials]` @@ -306,7 +373,7 @@ The updated specification (Β§9.2) defines three practical patterns for privacy-p **Example:** All levels can use transparency anchoring (see Level B and C examples) -**Documentation:** See [docs/TRANSPARENCY_LOG.md](docs/TRANSPARENCY_LOG.md) for detailed usage and API reference. +**Documentation:** See [Transparency Log Guide](docs/user-guide/transparency-log.md) for detailed usage and API reference. ## Disclosure Levels @@ -627,7 +694,7 @@ GenesisGraph provides: | **Researcher** | "Figure reproducibility depends on goodwill" | "Attached `.gg.yaml` with exact software versions, parameters" | | **Auditor** | "Manual verification, slow, error-prone" | "Machine-verifiable proof, instant validation" | -**See:** `USE_CASES.md` for complete examples with code. +**See:** [Use Cases & Integration](docs/use-cases.md) for complete examples with code. --- @@ -643,46 +710,55 @@ response = client.chat_completion(messages=[...]) client.export_provenance("workflow.gg.yaml") ``` -**Details:** `USE_CASES.md` Β§AI Pipeline Provenance +**Details:** [Use Cases](docs/use-cases.md) Β§AI Pipeline Provenance --- -## πŸ“š Documentation Guide - -| Document | Purpose | Audience | Time | -|----------|---------|----------|------| -| **QUICKSTART.md** | Simplest tutorial | Developers new to GenesisGraph | 5 min | -| **USE_CASES.md** | Real integrations | Teams evaluating adoption | 15 min | -| **FAQ.md** | Common objections | Decision-makers, skeptics | 10 min | -| **MAIN_SPEC.md** | Complete standard | Implementers, auditors | 45 min | -| **STRATEGIC_CONTEXT.md** | Big picture | Executives, investors | 20 min | -| **CRITICAL_GAPS_ANALYSIS.md** | v1.0 roadmap & strategic gaps | Standards architects, contributors | 30 min | +## πŸ“š Documentation Guide β€” Organized by Incremental Reveal + +| Layer | Document | Purpose | Audience | Time | +|-------|----------|---------|----------|------| +| **1** | [Quickstart](docs/getting-started/quickstart.md) | Simplest tutorial | New developers | 5 min | +| **1** | [Disclosure Levels](docs/user-guide/disclosure-levels.md) | Core A/B/C model | All users | 10 min | +| **2** | [User Guide](docs/user-guide/overview.md) | Feature overview | Implementers | 15 min | +| **2** | [Use Cases](docs/use-cases.md) | Real integrations | Teams evaluating adoption | 15 min | +| **2** | [FAQ](docs/faq.md) | Common questions | Decision-makers | 10 min | +| **3** | [Architecture](docs/developer-guide/architecture.md) | System design | Developers | 30 min | +| **3** | [Main Spec](docs/specifications/main-spec.md) | Complete standard | Implementers, auditors | 45 min | +| **4** | [Vision](docs/strategic/vision.md) | Why it matters | Executives, investors | 20 min | +| **4** | [Roadmap](docs/strategic/roadmap.md) | Development plan | Contributors | 25 min | +| **4** | [Critical Gaps](docs/strategic/critical-gaps.md) | Strategic analysis | Standards architects | 30 min | --- -## πŸ› οΈ Next Steps +## πŸ› οΈ Next Steps β€” Progressive Learning Paths ### For Developers +Follow Layer 1 β†’ 2 β†’ 3 for systematic learning: -1. Read `QUICKSTART.md` (5 minutes) -2. Try simplest example (guitar hanger CAD export) -3. Explore `examples/` directory -4. Run verification scripts -5. Integrate with your tool (see `USE_CASES.md` Β§Integration Patterns) +1. **Start:** [Quickstart](docs/getting-started/quickstart.md) (5 min) - Guitar hanger CAD export example +2. **Understand:** [Disclosure Levels](docs/user-guide/disclosure-levels.md) (10 min) - A/B/C model +3. **Explore:** [Examples](docs/getting-started/examples.md) - Hands-on code samples +4. **Integrate:** [Architecture](docs/developer-guide/architecture.md) - System integration patterns +5. **Reference:** [SDK Quick Reference](docs/reference/sdk-quick-reference.md) - API lookup ### For Decision-Makers +Evaluate business value quickly: -1. Read `FAQ.md` (10 minutes) - addresses "Why not PROV-O?", "Do I need blockchain?" -2. Review `USE_CASES.md` - see real-world integration examples -3. Read `STRATEGIC_CONTEXT.md` (20 minutes) - understand adoption strategy, 5-year vision -4. Evaluate business value for your domain (AI, manufacturing, research, etc.) +1. **Overview:** Read the top of this README (2 min) - Understand the innovation +2. **Questions:** [FAQ](docs/faq.md) (10 min) - "Why not PROV-O?", "Do I need blockchain?" +3. **Examples:** [Use Cases](docs/use-cases.md) (15 min) - Real-world integrations +4. **Strategy:** [Vision](docs/strategic/vision.md) (20 min) - Adoption strategy, 5-year plan +5. **Planning:** [Roadmap](docs/strategic/roadmap.md) (25 min) - Current state & v1.0 timeline ### For Researchers +Deep technical exploration: -1. Read `spec/MAIN_SPEC.md` Β§9.2 - selective disclosure patterns (normative) -2. Review examples: Level A (full), Level B (partial), Level C (sealed) -3. Try verification scripts: `scripts/verify_sealed_subgraph.py` -4. Explore schema: `schema/genesisgraph-core-v0.1.yaml` +1. **Concept:** [Disclosure Levels](docs/user-guide/disclosure-levels.md) - Three-level model +2. **Cryptography:** [Selective Disclosure](docs/user-guide/selective-disclosure.md) - SD-JWT, BBS+, ZKP +3. **Specification:** [Main Spec](docs/specifications/main-spec.md) - Β§9.2 selective disclosure (normative) +4. **Examples:** Review `examples/level-{a,b,c}-*.gg.yaml` files +5. **Verification:** Try `scripts/verify_sealed_subgraph.py` and `verify_transparency_anchoring.py` --- diff --git a/CONTRIBUTING.md b/docs/developer-guide/contributing.md similarity index 100% rename from CONTRIBUTING.md rename to docs/developer-guide/contributing.md diff --git a/SECURITY.md b/docs/developer-guide/security.md similarity index 100% rename from SECURITY.md rename to docs/developer-guide/security.md diff --git a/FAQ.md b/docs/faq.md similarity index 100% rename from FAQ.md rename to docs/faq.md diff --git a/docs/getting-started/examples.md b/docs/getting-started/examples.md new file mode 100644 index 0000000..f809c96 --- /dev/null +++ b/docs/getting-started/examples.md @@ -0,0 +1,137 @@ +# Examples + +This page provides hands-on examples to help you understand GenesisGraph through practical use cases. + +## Quick Examples + +### Example 1: Basic Provenance Graph + +The simplest example is tracking a file transformation: + +```yaml +# example-basic.gg.yaml +nodes: + - id: cad-file + type: Input + label: "guitar-hanger.blend" + + - id: export-process + type: Process + label: "Blender STL Export" + agent: "Blender 3.6.5" + + - id: stl-file + type: Output + label: "guitar-hanger.stl" + hash: + algorithm: sha256 + value: "a3f5c892..." + +edges: + - from: cad-file + to: export-process + - from: export-process + to: stl-file +``` + +**What this shows:** Basic provenance tracking - input β†’ process β†’ output + +### Example 2: Disclosure Levels (A/B/C) + +GenesisGraph's key feature is **selective disclosure**: + +```yaml +# Disclosure Level A: Full transparency +disclosure: A +nodes: + - id: training-data + type: Input + label: "customer-images.zip" + location: "s3://mybucket/data.zip" + hash: + algorithm: sha256 + value: "d4e5f6..." +``` + +```yaml +# Disclosure Level B: Verified, private details +disclosure: B +nodes: + - id: training-data + type: Input + label: "customer-images.zip" + hash: + algorithm: sha256 + value: "d4e5f6..." + # location omitted for privacy +``` + +```yaml +# Disclosure Level C: Proof without revealing anything +disclosure: C +nodes: + - id: training-data + type: Input + proofs: + - type: "hash-commitment" + value: "proof:zkp:c7a8b9..." + # All details hidden, only cryptographic proof shown +``` + +**What this shows:** How to control what information is shared + +## Example Repository + +Full examples with runnable code: + +```bash +# Explore the examples directory +cd examples/ +ls -la +``` + +Available examples: +- `basic-pipeline.gg.yaml` - Simple three-step process +- `disclosure-levels.gg.yaml` - A/B/C examples side-by-side +- `ai-training.gg.yaml` - ML pipeline with model provenance +- `manufacturing.gg.yaml` - CAD to production workflow + +## Interactive Examples + +### Try It Yourself + +1. **Validate an example:** + ```bash + genesisgraph validate examples/basic-pipeline.gg.yaml + ``` + +2. **Check different disclosure levels:** + ```bash + genesisgraph validate examples/disclosure-levels.gg.yaml + ``` + +3. **Visualize a graph:** + ```bash + genesisgraph visualize examples/ai-training.gg.yaml --output graph.png + ``` + +## Real-World Example Scenarios + +For complete real-world integration examples, see: +- [Use Cases](../use-cases.md) - Detailed scenarios with code +- [AI Pipeline Example](../use-cases.md#ai-pipelines) - FDA-compliant ML tracking +- [Manufacturing Example](../use-cases.md#manufacturing) - ISO 9001 CAD workflow + +## Next Steps + +
+ +- **Master the concepts** β†’ [User Guide Overview](../user-guide/overview.md) +- **Understand disclosure levels** β†’ [Disclosure Levels (A/B/C)](../user-guide/disclosure-levels.md) +- **See real integrations** β†’ [Use Cases & FAQ](../use-cases.md) + +
+ +--- + +**Need Help?** Check the [FAQ](../faq.md) or [Troubleshooting Guide](../developer-guide/troubleshooting.md) diff --git a/QUICKSTART.md b/docs/getting-started/quickstart.md similarity index 100% rename from QUICKSTART.md rename to docs/getting-started/quickstart.md diff --git a/docs/index.md b/docs/index.md index 005025d..162503c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,41 +20,48 @@ GenesisGraph provides verifiable provenance for: βœ… **Industry Profiles** - AI/ML (FDA 21 CFR), Manufacturing (ISO 9001) βœ… **Progressive Trust** - Start simple, add cryptography as needed -## Quick Links +## Quick Links β€” Organized by Incremental Reveal
-- :material-clock-fast:{ .lg .middle } __5-Minute Quickstart__ +- :material-clock-fast:{ .lg .middle } __Layer 1: Getting Started__ --- - Get started with a simple example and validate your first document + 5-minute tutorial and understand the A/B/C disclosure model - [:octicons-arrow-right-24: Quickstart Guide](getting-started/quickstart.md) + [:octicons-arrow-right-24: Quickstart](getting-started/quickstart.md) + [:octicons-arrow-right-24: Disclosure Levels](user-guide/disclosure-levels.md) -- :fontawesome-brands-python:{ .lg .middle } __API Reference__ +- :material-book-open-variant:{ .lg .middle } __Layer 2: User Guide__ --- - Complete Python SDK documentation with examples + Learn features, see examples, and find answers - [:octicons-arrow-right-24: API Docs](api-reference/validator.md) + [:octicons-arrow-right-24: User Guide](user-guide/overview.md) + [:octicons-arrow-right-24: Use Cases](use-cases.md) + [:octicons-arrow-right-24: FAQ](faq.md) -- :material-book-open-variant:{ .lg .middle } __User Guide__ +- :material-code-braces:{ .lg .middle } __Layer 3: Technical Depth__ --- - Learn about validation, disclosure levels, and cryptographic features + Architecture, specifications, and SDK reference - [:octicons-arrow-right-24: User Guide](user-guide/overview.md) + [:octicons-arrow-right-24: Architecture](developer-guide/architecture.md) + [:octicons-arrow-right-24: Main Spec](specifications/main-spec.md) + [:octicons-arrow-right-24: SDK Reference](reference/sdk-quick-reference.md) -- :material-code-braces:{ .lg .middle } __Developer Guide__ +- :material-strategy:{ .lg .middle } __Layer 4: Strategic Context__ --- - Architecture, testing, and contribution guidelines + Vision, roadmap, and planning for decision-makers - [:octicons-arrow-right-24: Developer Guide](developer-guide/architecture.md) + [:octicons-arrow-right-24: Vision](strategic/vision.md) + [:octicons-arrow-right-24: Roadmap](strategic/roadmap.md) + [:octicons-arrow-right-24: Critical Gaps](strategic/critical-gaps.md)
@@ -123,7 +130,7 @@ gg validate workflow.gg.yaml # βœ“ Validation PASSED ``` -## Use Cases +## Use Cases by Industry
@@ -133,7 +140,7 @@ gg validate workflow.gg.yaml Prove how AI models generated outputs, with selective disclosure of prompts - [:octicons-arrow-right-24: AI Use Cases](use-cases/ai-pipelines.md) + [:octicons-arrow-right-24: See AI Examples](use-cases.md#ai-pipelines) - :material-cube-outline:{ .lg .middle } __Manufacturing__ @@ -141,7 +148,7 @@ gg validate workflow.gg.yaml ISO 9001 compliance with sealed CAM toolpaths - [:octicons-arrow-right-24: Manufacturing](use-cases/manufacturing.md) + [:octicons-arrow-right-24: See Manufacturing](use-cases.md#manufacturing) - :material-flask:{ .lg .middle } __Scientific Research__ @@ -149,10 +156,12 @@ gg validate workflow.gg.yaml Reproducible research with full parameter disclosure - [:octicons-arrow-right-24: Science](use-cases/scientific-research.md) + [:octicons-arrow-right-24: See Research](use-cases.md#scientific-research)
+**See the complete [Use Cases & Integration Guide](use-cases.md) for code examples and integration patterns.** + ## Community & Support - **GitHub**: [github.com/scottsen/genesisgraph](https://github.com/scottsen/genesisgraph) diff --git a/IMPLEMENTATION_SUMMARY.md b/docs/reference/implementation-summary.md similarity index 100% rename from IMPLEMENTATION_SUMMARY.md rename to docs/reference/implementation-summary.md diff --git a/SDK-DEVELOPMENT-GUIDE.md b/docs/reference/sdk-development-guide.md similarity index 100% rename from SDK-DEVELOPMENT-GUIDE.md rename to docs/reference/sdk-development-guide.md diff --git a/SDK-QUICK-REFERENCE.md b/docs/reference/sdk-quick-reference.md similarity index 100% rename from SDK-QUICK-REFERENCE.md rename to docs/reference/sdk-quick-reference.md diff --git a/spec/MAIN_SPEC.md b/docs/specifications/main-spec.md similarity index 100% rename from spec/MAIN_SPEC.md rename to docs/specifications/main-spec.md diff --git a/docs/ZKP_TEMPLATES.md b/docs/specifications/zkp-templates.md similarity index 100% rename from docs/ZKP_TEMPLATES.md rename to docs/specifications/zkp-templates.md diff --git a/CRITICAL_GAPS_ANALYSIS.md b/docs/strategic/critical-gaps.md similarity index 100% rename from CRITICAL_GAPS_ANALYSIS.md rename to docs/strategic/critical-gaps.md diff --git a/ROADMAP.md b/docs/strategic/roadmap.md similarity index 100% rename from ROADMAP.md rename to docs/strategic/roadmap.md diff --git a/STRATEGIC_CONTEXT.md b/docs/strategic/vision.md similarity index 100% rename from STRATEGIC_CONTEXT.md rename to docs/strategic/vision.md diff --git a/USE_CASES.md b/docs/use-cases.md similarity index 100% rename from USE_CASES.md rename to docs/use-cases.md diff --git a/docs/DID_WEB_GUIDE.md b/docs/user-guide/did-web-guide.md similarity index 100% rename from docs/DID_WEB_GUIDE.md rename to docs/user-guide/did-web-guide.md diff --git a/docs/user-guide/disclosure-levels.md b/docs/user-guide/disclosure-levels.md new file mode 100644 index 0000000..3a4fce4 --- /dev/null +++ b/docs/user-guide/disclosure-levels.md @@ -0,0 +1,371 @@ +# Disclosure Levels (A/B/C) + +The three-level disclosure model is **GenesisGraph's core innovation**. It solves the privacy-vs-trust dilemma by letting you choose how much to reveal while maintaining verifiability. + +## The Problem GenesisGraph Solves + +Traditional provenance systems force a binary choice: + +| **Full Transparency** | **No Transparency** | +|----------------------|---------------------| +| βœ… Maximum trust | βœ… Maximum privacy | +| ❌ No privacy | ❌ No trust | +| Used: Open source, public data | Used: Proprietary systems | + +**This doesn't work for:** Enterprise collaboration, regulated industries, competitive R&D, sensitive data processing + +## GenesisGraph's Three-Level Model + +GenesisGraph provides a spectrum: + +```mermaid +graph LR + A[Level A
Full Transparency] --> B[Level B
Verified Privacy] + B --> C[Level C
Zero-Knowledge] + + style A fill:#90EE90 + style B fill:#FFD700 + style C fill:#87CEEB +``` + +You choose the level **per node** in your provenance graph - mix and match as needed! + +--- + +## Level A: Full Transparency + +**Philosophy:** "Trust through complete openness" + +### What You Share +βœ… All details: file locations, parameters, agent versions, timestamps +βœ… Public hashes for verification +βœ… Full metadata + +### When to Use +- **Open science** - Reproducible research requiring full disclosure +- **Public datasets** - Government data, open source projects +- **Supply chain** - Consumer-facing product provenance +- **Audits** - Regulatory compliance requiring full records + +### Example + +```yaml +disclosure: A +nodes: + - id: training-dataset + type: Input + label: "ImageNet-2024" + location: "https://image-net.org/data/imagenet2024.tar.gz" + hash: + algorithm: sha256 + value: "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5" + metadata: + size: "150GB" + format: "tar.gz" + license: "CC BY-SA 4.0" + + - id: training-process + type: Process + label: "Model Training" + agent: + id: "did:key:z6MkhaXg..." + name: "PyTorch Training Pipeline" + version: "2.1.0" + parameters: + epochs: 100 + batch_size: 32 + learning_rate: 0.001 + optimizer: "Adam" + environment: + hardware: "NVIDIA A100 80GB" + os: "Ubuntu 22.04" + cuda: "12.1" + timestamps: + started: "2024-01-15T10:00:00Z" + completed: "2024-01-18T22:30:00Z" +``` + +**Result:** Complete transparency - anyone can reproduce or verify every detail + +--- + +## Level B: Verified Privacy + +**Philosophy:** "Trust through verifiable integrity without revealing details" + +### What You Share +βœ… Cryptographic hashes (proves integrity) +βœ… Minimal metadata (type, general category) +βœ… Verification method +❌ Actual locations, parameters, or sensitive details + +### When to Use +- **Enterprise collaboration** - Working with partners while protecting IP +- **Regulated industries** - Healthcare (HIPAA), finance (PCI-DSS) +- **Competitive R&D** - Proving due diligence without revealing techniques +- **Sensitive data** - Government, defense, private customer data + +### Example + +```yaml +disclosure: B +nodes: + - id: training-dataset + type: Input + label: "Proprietary Medical Images" + hash: + algorithm: sha256 + value: "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5" + # Location NOT disclosed - privacy preserved + # Can still verify integrity via hash + + - id: training-process + type: Process + label: "Model Training" + agent: + id: "did:web:example.com:ai-lab" + # Verified identity, but no version details + hash: + algorithm: sha256 + value: "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2" + # Parameters NOT disclosed - competitive advantage protected + # Hash proves process integrity + + timestamps: + started: "2024-01-15T10:00:00Z" + completed: "2024-01-18T22:30:00Z" + # Timing shown, but not configuration details +``` + +**Result:** Verifiable integrity + privacy. Auditors can confirm "this exact process ran" without learning details + +--- + +## Level C: Zero-Knowledge Proofs + +**Philosophy:** "Trust through cryptographic proof without revealing anything" + +### What You Share +βœ… Cryptographic proofs (proves properties) +βœ… Proof type and verification method +❌ No hashes, no metadata, no details whatsoever + +### When to Use +- **Maximum privacy** - Competitive algorithms, state secrets +- **Compliance proofs** - "I followed regulations" without revealing what you did +- **Predicate proofs** - "My data meets criteria X" without showing the data +- **Unlinkable verification** - Prove compliance without linking to identity + +### Example + +```yaml +disclosure: C +nodes: + - id: training-dataset + type: Input + proofs: + - type: "predicate-proof" + claim: "dataset size >= 100GB" + proof: "zkp:snark:0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b" + verifier: "did:web:example.com:zkp-verifier" + + - type: "compliance-proof" + claim: "HIPAA-compliant data handling" + proof: "zkp:bulletproof:0x9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e" + standard: "HIPAA-2023" + + - id: training-process + type: Process + proofs: + - type: "parameter-range-proof" + claim: "learning_rate in [0.0001, 0.01]" + proof: "zkp:rangeproof:0x2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c" + + - type: "execution-proof" + claim: "process ran on certified hardware" + proof: "zkp:sigma:0x4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f" + attestation: "SGX-2024" +``` + +**Result:** Cryptographic proof of properties (compliance, ranges, attestations) without revealing **any** underlying data + +--- + +## Comparing the Three Levels + +| **Aspect** | **Level A** | **Level B** | **Level C** | +|-----------|------------|------------|------------| +| **Privacy** | None (public) | High (hashed) | Maximum (ZKP) | +| **Trust** | Full transparency | Hash verification | Cryptographic proof | +| **Reproducibility** | Complete | Partial (with key) | Proof-based only | +| **Verification Cost** | Low (hash check) | Low (hash check) | Higher (ZKP verify) | +| **Use Case** | Open science | Enterprise | Competitive R&D | +| **Example** | Public dataset URL | Hash of private data | Proof of compliance | + +## Mixing Levels in One Graph + +**Key Feature:** You can use different levels for different nodes! + +```yaml +nodes: + # Public input - full transparency + - id: public-dataset + disclosure: A + location: "https://github.com/example/data.zip" + hash: "sha256:abc123..." + + # Proprietary algorithm - verified privacy + - id: processing-step + disclosure: B + hash: "sha256:def456..." + # Algorithm details hidden + + # Sensitive output - zero-knowledge proof + - id: final-model + disclosure: C + proofs: + - type: "accuracy-proof" + claim: "accuracy >= 95%" + proof: "zkp:proof_data..." +``` + +**Why this works:** Different stakeholders need different levels of trust: +- **Public** (Level A): Consumers trust transparent sources +- **Partners** (Level B): Verify integrity without revealing IP +- **Regulators** (Level C): Prove compliance without exposing trade secrets + +## How to Choose the Right Level + +### Decision Flow + +```mermaid +graph TD + A[Start] --> B{Is data public?} + B -->|Yes| C[Use Level A] + B -->|No| D{Do partners need
to verify integrity?} + D -->|Yes| E{Can you share
a hash?} + E -->|Yes| F[Use Level B] + E -->|No| G[Use Level C] + D -->|No| H{Need to prove
compliance?} + H -->|Yes| G + H -->|No| I[Consider no disclosure
or private storage] + + style C fill:#90EE90 + style F fill:#FFD700 + style G fill:#87CEEB +``` + +### Quick Reference + +| **Question** | **Answer** | **Use Level** | +|-------------|-----------|---------------| +| "Can competitors see this?" | No | B or C | +| "Must prove to regulators?" | Yes | C (if sensitive) or A (if public) | +| "Open source project?" | Yes | A | +| "Collaborating with partners?" | Yes | B | +| "Consumer-facing product?" | Yes | A | +| "Proprietary algorithm?" | Yes | B or C | +| "Healthcare/financial data?" | Yes | B or C | +| "Research reproducibility?" | Yes | A | + +## Implementation Examples + +### Example 1: Pharmaceutical R&D + +```yaml +# Clinical trial provenance - mixed levels +nodes: + # Trial design - public for transparency + - id: trial-protocol + disclosure: A + location: "https://clinicaltrials.gov/study/NCT123456" + + # Patient data - verified but private + - id: patient-data + disclosure: B + hash: "sha256:abc123..." + # HIPAA-protected + + # Drug formulation - zero-knowledge proof + - id: drug-synthesis + disclosure: C + proofs: + - type: "fda-compliance-proof" + claim: "21 CFR Part 11 compliant" + proof: "zkp:proof..." +``` + +### Example 2: AI Model Supply Chain + +```yaml +nodes: + # Training code - open source + - id: training-code + disclosure: A + location: "https://github.com/example/model-training" + + # Training data - proprietary + - id: training-data + disclosure: B + hash: "sha256:def456..." + + # Model weights - competitive + - id: model-output + disclosure: C + proofs: + - type: "performance-proof" + claim: "accuracy >= 98%" + proof: "zkp:proof..." +``` + +## Best Practices + +### 1. Start with the Minimum Necessary Disclosure +- Use Level C by default +- Increase to B if partners need hash verification +- Use A only for public/open data + +### 2. Document Your Disclosure Choices +```yaml +metadata: + disclosure_rationale: "Level B used to protect IP while enabling partner verification" +``` + +### 3. Consider Your Audience +- **Regulators:** May require Level A for audits +- **Partners:** Usually satisfied with Level B +- **Competitors:** Definitely use Level C +- **Public:** Level A builds consumer trust + +### 4. Use Transparency Logs for Level B/C +Even with privacy, you can prove "when" something happened: +```yaml +disclosure: B +transparency_log: + log_id: "https://rekor.sigstore.dev" + entry_id: "abc123..." + # Proves graph existed at timestamp, without revealing content +``` + +## Advanced: Selective Disclosure + +For even more control, use **Selective Disclosure** cryptography: +- Reveal only specific fields to specific parties +- Same graph, different views for different audiences + +β†’ See [Selective Disclosure Guide](selective-disclosure.md) + +## Next Steps + +
+ +- **Set up identity** β†’ [DID & Identity Guide](did-web-guide.md) +- **Implement Level B/C** β†’ [Selective Disclosure](selective-disclosure.md) +- **Add audit trails** β†’ [Transparency Logs](transparency-log.md) +- **Industry compliance** β†’ [Profile Validators](profile-validators.md) + +
+ +--- + +**Questions?** Check the [FAQ](../faq.md) or see [Use Cases](../use-cases.md) for real-world examples diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md new file mode 100644 index 0000000..92ea7e2 --- /dev/null +++ b/docs/user-guide/overview.md @@ -0,0 +1,168 @@ +# User Guide Overview + +Welcome to the GenesisGraph User Guide! This guide will help you understand how to use GenesisGraph effectively. + +## What You'll Learn + +This user guide is organized progressively, from core concepts to advanced features: + +```mermaid +graph LR + A[Overview] --> B[Disclosure Levels] + B --> C[Identity & DID] + C --> D[Advanced Features] + D --> E[Selective Disclosure] + D --> F[Transparency Logs] + D --> G[Profile Validators] +``` + +## Core Concept: Selective Disclosure + +**The Problem:** Traditional provenance systems force you to choose: +- **Full transparency** (publish everything, lose privacy) +- **No transparency** (keep everything private, lose trust) + +**GenesisGraph's Solution:** Three-level selective disclosure model + +### Disclosure Level A: Full Transparency +βœ… Use when: Public data, open science, supply chain verification + +```yaml +disclosure: A +nodes: + - id: input-1 + type: Input + label: "training-data.zip" + location: "https://example.com/data.zip" # Full details + hash: "sha256:abc123..." +``` + +**Shows:** Everything - files, locations, parameters, agent details + +### Disclosure Level B: Verified Privacy +βœ… Use when: Enterprise collaboration, regulated industries, competitive IP + +```yaml +disclosure: B +nodes: + - id: input-1 + type: Input + label: "training-data.zip" + hash: "sha256:abc123..." # Provable integrity + # location omitted - private but verifiable +``` + +**Shows:** Enough to verify integrity, hides sensitive details + +### Disclosure Level C: Zero-Knowledge Proofs +βœ… Use when: Maximum privacy, compliance proofs, competitive advantage + +```yaml +disclosure: C +nodes: + - id: input-1 + type: Input + proofs: + - type: "hash-commitment" + proof: "zkp:proof_data..." # Cryptographic proof only +``` + +**Shows:** Only cryptographic proofs, reveals nothing about the data itself + +## How Disclosure Works in Practice + +| **What You Want to Prove** | **Disclosure Level** | **What You Share** | +|----------------------------|----------------------|---------------------| +| "I used this exact file" | A | File location + hash | +| "I used a verified file" | B | Hash only | +| "I used a compliant file" | C | Zero-knowledge proof | +| "This process ran on certified hardware" | A | Hardware ID + cert | +| "This process ran on secure hardware" | B | Cert hash | +| "This process met security standards" | C | ZKP of compliance | + +## User Guide Structure + +This guide follows an incremental reveal approach: + +### 1. **Start Here: Disclosure Levels (A/B/C)** +Learn the three-level model in depth +β†’ [Disclosure Levels Guide](disclosure-levels.md) + +### 2. **Identity & DIDs** +Understand how GenesisGraph uses decentralized identifiers for trust +β†’ [DID & Identity Guide](did-web-guide.md) + +### 3. **Advanced Features** + +Once you understand the basics, explore advanced capabilities: + +- **[Selective Disclosure](selective-disclosure.md)** - SD-JWT and BBS+ cryptographic techniques +- **[Transparency Logs](transparency-log.md)** - Certificate Transparency for tamper-proof audit trails +- **[Profile Validators](profile-validators.md)** - Industry-specific compliance (FDA, ISO, etc.) + +## Common Use Cases + +**Quick Navigation by Role:** + +
+ +- **πŸ€– AI/ML Engineers** + + Track model training, validate datasets, prove compliance + β†’ [AI Pipeline Examples](../use-cases.md#ai-pipelines) + +- **🏭 Manufacturing** + + CAD provenance, ISO 9001 compliance, supply chain verification + β†’ [Manufacturing Examples](../use-cases.md#manufacturing) + +- **πŸ”¬ Researchers** + + Reproducible science, data lineage, peer review + β†’ [Scientific Research Examples](../use-cases.md#scientific-research) + +- **🏒 Enterprises** + + Cross-organization collaboration with privacy + β†’ [Enterprise Identity Guide](did-web-guide.md) + +
+ +## How to Use This Guide + +### For Beginners +1. Read this overview +2. Understand [Disclosure Levels](disclosure-levels.md) +3. Try the [Examples](../getting-started/examples.md) + +### For Implementers +1. Review [Disclosure Levels](disclosure-levels.md) +2. Set up [DID & Identity](did-web-guide.md) +3. Choose features: [Selective Disclosure](selective-disclosure.md), [Transparency Logs](transparency-log.md), or [Profile Validators](profile-validators.md) +4. See [Architecture](../developer-guide/architecture.md) for integration + +### For Decision Makers +1. Read this overview +2. Check [Use Cases & FAQ](../use-cases.md) +3. Review [Vision & Strategy](../strategic/vision.md) + +## Next Steps + +
+ +- **Master disclosure levels** β†’ [Disclosure Levels (A/B/C)](disclosure-levels.md) +- **Set up identity** β†’ [DID & Identity Guide](did-web-guide.md) +- **See real examples** β†’ [Use Cases](../use-cases.md) +- **Deep dive** β†’ [Main Specification](../specifications/main-spec.md) + +
+ +## Need Help? + +- **Common questions:** [FAQ](../faq.md) +- **Technical issues:** [Troubleshooting](../developer-guide/troubleshooting.md) +- **Integration help:** [Architecture Guide](../developer-guide/architecture.md) + +--- + +**Ready to start?** β†’ [Learn about Disclosure Levels](disclosure-levels.md) diff --git a/docs/PROFILE_VALIDATORS.md b/docs/user-guide/profile-validators.md similarity index 100% rename from docs/PROFILE_VALIDATORS.md rename to docs/user-guide/profile-validators.md diff --git a/docs/SELECTIVE_DISCLOSURE.md b/docs/user-guide/selective-disclosure.md similarity index 100% rename from docs/SELECTIVE_DISCLOSURE.md rename to docs/user-guide/selective-disclosure.md diff --git a/docs/TRANSPARENCY_LOG.md b/docs/user-guide/transparency-log.md similarity index 100% rename from docs/TRANSPARENCY_LOG.md rename to docs/user-guide/transparency-log.md diff --git a/mkdocs.yml b/mkdocs.yml index 823774a..313eebf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -108,58 +108,58 @@ plugins: enable_creation_date: true type: timeago -# Navigation structure +# Navigation structure - Organized by Incremental Reveal Principles +# Layer 1: Essential basics (what, why, how to start) +# Layer 2: User guidance (features and how to use them) +# Layer 3: Technical depth (architecture, specifications, reference) +# Layer 4: Strategic context (vision, roadmap, planning) + nav: - Home: index.md - + + # Layer 1: Getting Started - Simplest entry point - Getting Started: - Installation: getting-started/installation.md - - Quickstart: getting-started/quickstart.md + - Quickstart (5 min): getting-started/quickstart.md - Examples: getting-started/examples.md - + + # Layer 2: User Guide - Progressive feature depth - User Guide: - Overview: user-guide/overview.md - - Validation: user-guide/validation.md - - CLI Usage: user-guide/cli.md - - Disclosure Levels: user-guide/disclosure-levels.md + - Disclosure Levels (A/B/C): user-guide/disclosure-levels.md - DID & Identity: user-guide/did-web-guide.md - - Transparency Logs: user-guide/transparency-log.md - Selective Disclosure: user-guide/selective-disclosure.md + - Transparency Logs: user-guide/transparency-log.md - Profile Validators: user-guide/profile-validators.md - - - API Reference: - - Validator: api-reference/validator.md - - CLI: api-reference/cli.md - - DID Resolver: api-reference/did-resolver.md - - Transparency Log: api-reference/transparency-log.md - - Errors: api-reference/errors.md - - SDK (Python): api-reference/python-sdk.md - - SDK (JavaScript): api-reference/javascript-sdk.md - + + # Use Cases - Real-world applications + - Use Cases & Integration: + - Overview: use-cases.md + - FAQ: faq.md + + # Layer 3: Technical Depth - Architecture and Implementation - Developer Guide: - Architecture: developer-guide/architecture.md - Contributing: developer-guide/contributing.md - - Testing: developer-guide/testing.md - Security: developer-guide/security.md - Troubleshooting: developer-guide/troubleshooting.md - + + # Reference - Quick lookup for developers + - Reference: + - SDK Development Guide: reference/sdk-development-guide.md + - SDK Quick Reference: reference/sdk-quick-reference.md + - Implementation Status: reference/implementation-summary.md + + # Specifications - Formal definitions - Specifications: - - Main Spec: specifications/main-spec.md - - Selective Disclosure: specifications/selective-disclosure.md + - Main Specification: specifications/main-spec.md - ZKP Templates: specifications/zkp-templates.md - - - Use Cases: - - Overview: use-cases/overview.md - - AI Pipelines: use-cases/ai-pipelines.md - - Manufacturing: use-cases/manufacturing.md - - Scientific Research: use-cases/scientific-research.md - + + # Layer 4: Strategic Context - Vision and planning - Strategic Context: - - Vision: strategic/vision.md - - Critical Gaps: strategic/critical-gaps.md + - Vision & Why It Matters: strategic/vision.md - Roadmap: strategic/roadmap.md - - - FAQ: faq.md + - Critical Gaps Analysis: strategic/critical-gaps.md # Extra settings extra: