From 89befd54f2b288a5fce5d3d00d9a9c49f5b50f42 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Nov 2025 13:41:34 +0000 Subject: [PATCH 1/2] docs: Reorganize documentation using incremental reveal principles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comprehensive documentation restructuring to improve discoverability, organization, and progressive learning using incremental reveal methodology. ## Changes ### File Reorganization (17 files moved) - Moved strategic docs to docs/strategic/ (vision, roadmap, critical-gaps) - Moved SDK guides to docs/reference/ (sdk-development-guide, sdk-quick-reference, implementation-summary) - Moved specifications to docs/specifications/ (main-spec, zkp-templates) - Moved user guides to docs/user-guide/ (did-web-guide, selective-disclosure, transparency-log, profile-validators) - Moved developer guides to docs/developer-guide/ (contributing, security) - Moved core docs to docs/ (faq, use-cases, quickstart) ### New Bridge Documents (4 created) - docs/getting-started/examples.md - Hands-on examples with progressive depth - docs/user-guide/overview.md - User guide entry point with feature landscape - docs/user-guide/disclosure-levels.md - Deep dive into A/B/C model (core innovation) - DOCS_NAVIGATION.md - Comprehensive navigation guide with learning paths ### Enhanced Entry Points - README.md: Restructured with 4-layer progressive learning paths - Layer 1: Essential basics (5-10 min) - Layer 2: User guidance (15-30 min) - Layer 3: Technical depth (30-60 min) - Layer 4: Strategic context (20-45 min) - README.md: Added role-based quick navigation (developers, decision-makers, AI engineers, researchers) - README.md: Updated all internal links to match new structure ### Navigation Improvements - docs/index.md: Restructured cards to show 4 layers clearly - docs/index.md: Fixed broken links to match reorganized structure - mkdocs.yml: Updated navigation with layer-based organization - mkdocs.yml: Added comments explaining incremental reveal structure ## Incremental Reveal Principles Applied 1. **Progressive Depth**: Documentation layered from simple → complex 2. **Clear Entry Points**: Multiple paths based on user role and goals 3. **Reduced Cognitive Load**: Each layer focuses on specific learning outcomes 4. **Signposting**: Clear "next steps" at each stage 5. **Role-Based Navigation**: Tailored paths for different audiences ## Benefits - Easier onboarding for new users (clear 5-min → 10-min → 15-min paths) - Better discoverability (organized by user journey, not document type) - Aligned with MkDocs structure (documentation site ready) - Reduced root directory clutter (16 files → organized structure) - Improved navigation (role-based and layer-based access) ## Files Changed - Renamed: 17 files moved to proper directories - Created: 4 new bridge/navigation documents - Modified: 3 files (README, docs/index, mkdocs.yml) - Total: 24 files affected ## Migration Guide All documentation remains accessible. Old paths redirect via git renames: - QUICKSTART.md → docs/getting-started/quickstart.md - FAQ.md → docs/faq.md - ROADMAP.md → docs/strategic/roadmap.md - (See DOCS_NAVIGATION.md for complete mapping) --- DOCS_NAVIGATION.md | 239 +++++++++++ README.md | 200 +++++++--- .../developer-guide/contributing.md | 0 .../developer-guide/security.md | 0 FAQ.md => docs/faq.md | 0 docs/getting-started/examples.md | 137 +++++++ .../getting-started/quickstart.md | 0 docs/index.md | 43 +- .../reference/implementation-summary.md | 0 .../reference/sdk-development-guide.md | 0 .../reference/sdk-quick-reference.md | 0 .../specifications/main-spec.md | 0 .../zkp-templates.md} | 0 .../strategic/critical-gaps.md | 0 ROADMAP.md => docs/strategic/roadmap.md | 0 .../strategic/vision.md | 0 USE_CASES.md => docs/use-cases.md | 0 .../did-web-guide.md} | 0 docs/user-guide/disclosure-levels.md | 371 ++++++++++++++++++ docs/user-guide/overview.md | 168 ++++++++ .../profile-validators.md} | 0 .../selective-disclosure.md} | 0 .../transparency-log.md} | 0 mkdocs.yml | 66 ++-- 24 files changed, 1112 insertions(+), 112 deletions(-) create mode 100644 DOCS_NAVIGATION.md rename CONTRIBUTING.md => docs/developer-guide/contributing.md (100%) rename SECURITY.md => docs/developer-guide/security.md (100%) rename FAQ.md => docs/faq.md (100%) create mode 100644 docs/getting-started/examples.md rename QUICKSTART.md => docs/getting-started/quickstart.md (100%) rename IMPLEMENTATION_SUMMARY.md => docs/reference/implementation-summary.md (100%) rename SDK-DEVELOPMENT-GUIDE.md => docs/reference/sdk-development-guide.md (100%) rename SDK-QUICK-REFERENCE.md => docs/reference/sdk-quick-reference.md (100%) rename spec/MAIN_SPEC.md => docs/specifications/main-spec.md (100%) rename docs/{ZKP_TEMPLATES.md => specifications/zkp-templates.md} (100%) rename CRITICAL_GAPS_ANALYSIS.md => docs/strategic/critical-gaps.md (100%) rename ROADMAP.md => docs/strategic/roadmap.md (100%) rename STRATEGIC_CONTEXT.md => docs/strategic/vision.md (100%) rename USE_CASES.md => docs/use-cases.md (100%) rename docs/{DID_WEB_GUIDE.md => user-guide/did-web-guide.md} (100%) create mode 100644 docs/user-guide/disclosure-levels.md create mode 100644 docs/user-guide/overview.md rename docs/{PROFILE_VALIDATORS.md => user-guide/profile-validators.md} (100%) rename docs/{SELECTIVE_DISCLOSURE.md => user-guide/selective-disclosure.md} (100%) rename docs/{TRANSPARENCY_LOG.md => user-guide/transparency-log.md} (100%) 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/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: From c14a99e07b4a9d4edb050b84d362abd8d4bf4896 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Nov 2025 13:45:40 +0000 Subject: [PATCH 2/2] docs: Update DOCUMENT_EXPLORER_GUIDE with new file paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated all documentation paths in DOCUMENT_EXPLORER_GUIDE.md to match the reorganized structure. Updated workflows, examples, and document inventory to reflect new layer-based organization. Changes: - Updated all file paths (QUICKSTART.md → docs/getting-started/quickstart.md, etc.) - Reorganized Document Inventory by 4 layers instead of by location - Added new docs (disclosure-levels.md, overview.md, examples.md) to inventory - Updated all workflow examples with correct paths - Aligned examples with incremental reveal principles --- DOCUMENT_EXPLORER_GUIDE.md | 201 ++++++++++++++++++++----------------- 1 file changed, 109 insertions(+), 92 deletions(-) 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"