View source on GitHub →

Status: operational Canonical: yes Last Reviewed: 2026-04-15

Where things live (control plane)

What Where
Canonical entry docs STATE.md (living snapshot), ARCHITECTURE.md (system truth), DOCUMENTATION_CONTROL_SYSTEM.md (doc/process policy), and this INDEX.md (navigation).
Machine registry `registry.toml` — [control], [[doc_path_defaults]], [docs."path"] rows.
Human registry summary DOCUMENT_REGISTRY.md — regenerate via doc_control_check.py --write-document-registry.
Validator `scripts/doc_control_check.py`
Historical material `archive/` (by year); session-style content often still under development/ until archived.
Supplemental state/ tree state/README.md — not a substitute for root STATE.md.

Control-plane canonical (single definition): Only the paths listed in [control].canonical_doc_paths in `registry.toml` are “canonical” for CI header checks. Other docs may use canonical = "yes" in a registry row for emphasis, but that does not add them to the control-plane set unless canonical_doc_paths is updated.

INDEX vs generated index: This `INDEX.md` is the authoritative hand-maintained navigation. `INDEX.generated.md` is derived (registry/corpus snapshot for drift detection in CI); if the generator disagrees with this file, reconcile here intentionally.

Canon vs history: Prefer YAML on important docs: Status: (normative / descriptive / operational / historical / draft) and Canonical: yes|no. Do not treat undated snapshots or archive/ neighbors as current truth without checking STATE.md and dates.

One-line check: python3 docs/scripts/doc_control_check.py --repo . --registry docs/registry.toml (optional --strict before merge).

ICN Documentation Index

Welcome to the ICN (Intercooperative Network) documentation! This index provides clear navigation to all documentation.

Last Updated: 2026-04-15
Version: 2.1 (canon-sync pass)

📋 Quick Navigation

Start here by role

Design language (canonical)

The ICN public website is the first implementation surface of the universal civic design language. These docs are the source of truth for every public-facing design decision:

📚 Core Documentation

Essential reading for all ICN users and contributors.

Document Description
README.md Documentation overview and structure
ARCHITECTURE.md Comprehensive system architecture (160KB+)
GETTING_STARTED.md Quick start guide for developers
PHASE_HISTORY.md Development phase completion history
PHASE_PROGRESS.md Active phase tracking and cross-cutting metrics
STATE.md Current project state snapshot
TODO.md Active work items and priorities
glossary.md ICN terminology and definitions

🏗️ Architecture & Design

In-depth architectural documentation and design specifications.

Architecture Documentation (architecture/)

Comprehensive architectural reviews and design decisions:

Design Documents (design/)

Feature designs, proposals, and evolution plans:

Core Systems:

Economics (design/economics/):

Governance (design/governance/):

SDIS (design/sdis/):

Specifications (spec/)

Formal protocol and contract specifications:

📖 Reference Documentation

Technical reference materials, APIs, and configuration.

API Reference (reference/api/)

REST API, WebSocket, and SDK documentation:

Institutional Reference (reference/)

Configuration Reference (reference/config/)

Configuration files and environment settings:

Other References

📚 User & Developer Guides

Practical guides for using and building with ICN.

Institutional Guides (guides/)

User Guides (guides/user/)

End-user documentation:

Developer Guides (guides/developer/)

Technical guides for contributors:

Operations Guides (guides/operations/)

Deployment and operations documentation:

Quick References

🛠️ Development Documentation

Internal development resources, testing, and CI/CD.

Development Process (development/)

  • README.md - Development documentation index

Sprints (development/sprints/):

  • README.md - Sprint planning and tracking
  • Sprint completion records

Testing (development/testing/):

  • README.md - Testing documentation index
  • Integration and E2E testing guides
  • Mobile app testing procedures

CI/CD & Automation (ci/)

Continuous integration and delivery:

Performance (performance/)

  • README.md - Performance documentation index
  • Benchmarks and optimization guides

🔒 Security & Compliance

Security documentation, threat models, and audit reports.

Security Documentation (security/)

Production Security:

Threat Models & Audits:

SDIS Security:

Specialized Topics:

SDIS Documentation (sdis/)

Sovereign Digital Identity System:

🎯 Specialized Topics

Onboarding (onboarding/)

Contributor onboarding materials:

Deployment & Operations

Deployment Guides (deployment/):

  • Deployment configuration and guides

Operations (operations/):

  • README.md - Operations documentation
  • Monitoring, runbooks, and operational procedures

Ops runbooks (canonical: guides/operations/runbooks/):

Mobile & Observability

Mobile (mobile/):

  • Mobile app documentation

Observability (observability/):

  • Metrics, logging, and tracing

Pilot Programs (internal/pilots/)

Real-world pilot deployment documentation:

🔬 Internal Documentation

Internal planning, status tracking, and project management.

Internal Overview (internal/)

Status Tracking (internal/status/)

Active project status and gap analyses:

Planning Documents (planning/)

Current project planning and analysis:

Strategy Documents (strategy/)

Strategic direction and gap analysis (March 2026):

Current Status Reports (status/)

Live status reports and deployment verification:

Architecture Decision Records (adr/)

Formal architectural decisions:

Templates (templates/)

Documentation and code templates for consistency.

Reference Additions

Vision Documents (vision/)

High-level vision and strategic direction.

Session Handoffs & Dev Docs (dev/)

Session handoffs, development workflow docs, and worktree guidance:

  • WORKTREES.md - Git worktree guide for parallel agent work
  • language-guide.md - ICN language and terminology guide
  • Session handoffs: handoff-YYYY-MM-DD.md files (latest is the current execution state)

AI & Automation (ai/)

📦 Archives

Historical documentation, completed phases, and superseded materials.

Archive Structure (archive/2025/)

Organized by year, containing completed work and historical records:

Key Archived Documents:

  • Phase completion reports (PHASE_18_COMPLETE.md, etc.)
  • Historical deployment guides (KUBERNETES_DEPLOYMENT.md, PRODUCTION_DEPLOYMENT_GUIDE.md)
  • System status snapshots (PROJECT_STATUS_2025-12-06.md, SYSTEM_GAPS_2025-12-06.md)
  • Completed analyses (FOUNDATIONAL_REVIEW_2025-12-16.md, CODE_REVIEW_COMPLETE.md)
  • Security audit resolutions (security-audit-resolution-2025-12-18.md, security-hardening-2025-12-18.md)
  • Integration reports (GOVERNANCE-LEDGER-INTEGRATION-COMPLETE.md, GOVERNANCE-LEDGER-BUGS-FOUND.md)
  • Evolution documents (COMMONS_EVOLUTION_SUMMARY.md, ICN_COMPLETE_ARCHITECTURE_SYNTHESIS.md)
  • HSM/TPM documentation (hsm-tpm-roadmap.md, tpm-setup.md, tpm-implementation-plan.md)
  • Bug reports and sprint plans
  • Plus 20+ additional historical documents

Migration Notes: Documents are moved to archives when superseded, completed, or no longer actively referenced. See REORGANIZATION_2026.md for migration details.

🗂️ Documentation by Role

For New Contributors

  1. GETTING_STARTED.md - Quick start
  2. onboarding/README.md - Onboarding program
  3. guides/developer/README.md - Developer guides
  4. ARCHITECTURE.md - Architecture overview

For Core Developers

  1. ARCHITECTURE.md - Full architecture
  2. architecture/ARCHITECTURE_MAP.md - Visual guide
  3. design/ - Design documents
  4. development/testing/README.md - Testing guides

For Operations Engineers

  1. guides/operations/README.md - Operations guides
  2. security/FINAL_SECURITY_STATUS.md - Security status
  3. deployment/ - Deployment configs
  4. operations/README.md - Operational procedures

For Security Engineers

  1. security/FINAL_SECURITY_STATUS.md - Security overview
  2. security/threat-model.md - Threat analysis
  3. security/SECURITY_TESTING_GUIDE.md - Testing
  4. security/production-hardening.md - Hardening

For Product/Community

  1. guides/user/WHY_ICN_HANDOUT.md - Value proposition
  2. design/economics/ECONOMIC_VISION.md - Economic vision
  3. design/MINIMAL-VIABLE-COOP.md - MVC specification
  4. internal/pilots/pilot-playbook.md - Pilot guide

📊 Documentation Statistics

  • Total Markdown Files: 200+
  • Core Documentation: 7 files
  • Architecture Docs: 25+ files
  • Design Documents: 35+ files
  • Reference Materials: 15+ files
  • Guides: 20+ files
  • Security Documents: 20+ files
  • Internal/Status: 15+ files
  • Archived Documents: 30+ files
  • Total Documentation Size: ~2MB+ of structured knowledge

🔍 Search Tips

Find by Topic

  • Use your IDE's search (Ctrl/Cmd+Shift+F) across docs/ directory
  • Check specific subdirectories for focused results
  • Search glossary.md for terminology

Find by Date

  • Recent work: Check status/ directory
  • Historical: Browse archive/2025/
  • Development timeline: See PHASE_HISTORY.md

Find by Component

  • Identity: Search identity in architecture/ and design/
  • Trust: Check trust in architecture/ and security/
  • Ledger: Search ledger or economic in design/economics/
  • Governance: Browse design/governance/
  • Federation: Search federation in architecture/
  • SDIS: Check sdis/ directory

📞 Getting Help

  • Documentation Issues: File an issue on GitHub
  • Architecture Questions: Check architecture/ or ask in dev channels
  • Operations Support: See guides/operations/troubleshooting.md
  • Contributing: Read CONTRIBUTING.md in project root
  • Security Issues: Follow responsible disclosure process

🔄 Documentation Maintenance

Keeping This Index Current

This index should be updated when:

  • New major documents are added
  • Directory structure changes
  • Documents are archived
  • Significant reorganizations occur

Last Major Updates

  • 2026-02-10: Phase 2C reorganization (this version)
  • 2026-01-17: Previous organization
  • See REORGANIZATION_2026.md for detailed change history

Navigation: Top | Core Docs | Architecture | Reference | Guides | Archives

← Back to Docs