View source on GitHub →

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-06-01 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:

Visual explainers and assets

Control plane for ICN's visual explainer system — the doctrine, asset register, briefs, and review gate that govern every diagram, infographic, generated image, and source asset:

Claude Design — seed review and handoff

Governance scaffold for taking Claude Design seed artifacts into the canonical repo without confusing generated output with repo truth. Default: a seed is a proposal, not a design system:

📚 Core Documentation

Essential reading for all ICN users and contributors.

Document Description
README.md Documentation overview and structure
ARCHITECTURE.md Comprehensive system architecture (160KB+)
DESIGN_PRINCIPLES.md Canonical three-tier index of operational, firewall, and frozen-core invariants
design/ICN_DESIGN_SYSTEM.md UI/UX/visual/accessibility design system entry point (kernel-bound via §"Kernel architecture binding")
design/CLAUDE_DESIGN_SETUP.md How to use Claude Design with ICN — paste flow, local /design:* skills, job-card templates, failure modes
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:

  • KERNEL_CONTRACTS.md - Kernel contract specifications
  • effect-dispatch-contract.md - Accepted-proposal effect dispatch contract (governance decision → mandate → effect plan → dispatch → application + evidence)
  • institutional-domain.md - InstitutionalDomain and DomainPolicy primitive (the governed operating jurisdiction)
  • ccl-policy-registry.md - CCL policy registry, versioning, adoption contract, and governance-effect hook contract
  • governed-service-binding.md - GovernedServiceBinding, WorkloadManifest, and RuntimeProvider (the integrating envelope for hosted services, tools, compute jobs, and CCL evaluators)
  • storage-durability-policies.md - StorageSpec, BackupPolicy, ReplicationPolicy, RecoveryPolicy, ArchivePolicy, IntegrityPolicy, restore-test receipts, locality + privacy inheritance, restore authority
  • artifact-registry-and-scoped-vault.md - ArtifactRegistry v0 (content-addressed artifact metadata) and ScopedVault (privacy-enforced container), the boundary between them, the artifact-class taxonomy, and six integration points (documents, compute outputs, evidence packets, private evidence, mobile cache, replication)
  • compute-placement-policy.md - Compute placement policy contract (seven placement classes, decision inputs and outputs, fallback behavior, boundary rules, dashboard and member-shell rendering) sitting between ADR-0030 (workload manifest) and ADR-0031 (commons admission and settlement); fixes scope vocabulary (LocalDomain not Coop), execution vs capacity vocabulary (execution budget vs fuel vs capacity vs allocation), and settlement vs payment vocabulary
  • network-anti-entropy-proof-loops.md - Network anti-entropy proof-loop contract (eight-phase institutional evidence loop, thirteen forward-direction proof-artifact identifiers, eighteen divergence classes, ten boundary rules, steward / member surface vocabularies, three fixture-first proof-loop slices) beneath compute placement, storage durability, artifact registry, receipt clearing, and federation settlement finality; anchors against existing icn-gossip + icn-core anti-entropy primitives without redefining them
  • member-shell-v0.md - Member shell v0 — the primary participation surface (mobile-first, offline-tolerant, accessibility-first, plain-language-first). Defines five boundary lines, ten design principles, ten-surface information architecture, the ActionCard rendering contract over ADR-0027, the ten-step signing flow with reversibility / privacy / sync warnings, three-tier receipt rendering, offline / draft-intent behavior, ScopedVault opaque-reference affordances, the twelve-category accessibility gate, a closed v0 member-facing status vocabulary, an eighteen-row failure / safety table, and three fixture-first dogfood slices; no new endpoints, no platform decision, no native-app implementation
  • steward-cockpit-v0.md - Steward cockpit v0 — the operator-facing civic-infrastructure surface for node and domain stewards (the operator/steward complement of the member shell). Consumes verbatim the 9-field anti-entropy cockpit surface from #1829 and the 14-field operator/steward dashboard from #1826. Defines six boundary lines (vs member shell, vs node operator civic-role surface, vs public website, vs institution-package skin, vs backend/runtime, vs surveillance/admin-control panel), ten v0 design principles led by stewardship-not-domination, twelve cockpit surfaces, fourteen operator action-card scenarios, per-surface rendering contracts, a closed v0 operator-facing status vocabulary plus a verbatim member-impact summary mapping into the member-shell sync vocabulary, a twenty-row failure / safety table, and three fixture-first dogfood slices; no new endpoints, no frontend technology decision, no surveillance console, no private-data preview, no production-dashboard claim
  • icn-civic-shell-v0.md - ICN Civic Shell v0 — composition contract that ties the public website (truth boundary per ADR-0032 / ADR-0033), the member shell (#1830), the steward cockpit (#1831), the no-CLI organizer / member workflow (#1724 / #1726), the forge / auth-bridge / service-hosting / sovereign-forge models, and current operational reality into a single top-level public-plus-logged-in institutional shell. The first draft used the rejected ICN Headquarters metaphor; the v0 name is ICN Civic Shell. The Civic Shell composes existing ICN surfaces; it does not supersede the Member Shell, the Steward Cockpit, the public website, the service-hosting model, or the auth-bridge model. Defines public exterior (maturity-banded status / development updates / public roadmap / service-health posture / public forge window), logged-in interior (identity / active domain / active role / authority scope plus dashboards composed from existing surfaces), domain-and-route doctrine (intercooperative.network canonical public identity/truth vs icn.zone short operational/access/discovery — no icn.zone routes claimed live today; ICN-PRIVATE / ICN-EDGE segmentation framed as current/planned operational context, not ICN product doctrine), a ten-room model, notifications and action-card boundaries (preserves ADR-0027), status / proof labels anchored to #1796, and follow-up issue suggestions (not opened by this PR). No app implementation, no new endpoint, no auth implementation, no Keycloak / Forgejo / Matrix deployment, no n8n workflow build, no DNS / K3s / VLAN / network mutation, no public admin surfaces, no private data in repo, no Phase 2 completion claim, no formal NYCN pilot claim, no live-federation claim, no production-readiness claim, no replacement of existing member-shell or steward-cockpit specs. network-ops was not read locally; operator-provided context only.

📖 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:

Contract notes (contracts/)

  • schema-id-audit.md - Audit-only record of every JSON schema $id under docs/contracts/, with per-schema keep / migrate / investigate recommendations and migration safety rules
  • preview-review.md - Read-only / read-model contract for the human review boundary between source material and any subsequent action (urn:icn:contract:preview-review:v1); not a mutation API
  • pending-publish-summary.md - Read-only row-level read-model for pending-publish summaries (urn:icn:contract:pending-publish-summary:v1); composed body for preview_kind: pending_publish_summary, does not replace preview-review; not a mutation API

Other References

Project Index (reference/project-index/)

Show-ready orientation layer — routes outside readers, contributors, and agents to the right canonical doc, source tree, or external URL. Defers to STATE.md and PHASE_PROGRESS.md for current truth.

📚 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 Outreach (pilots/)

Organizer-facing pilot materials. Honest scope-of-now framing; not pitch decks. Defer to STATE.md and PHASE_PROGRESS.md for current truth.

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/)

Public introduction materials (June 2026, claims bounded by the evidence map):

  • ICN_FOR_COOPERATIVE_MOVEMENT.md - Plain-English ICN introduction for cooperative developers, federation organizers, TA providers, and member-owners; honest tool comparisons, explicit non-claims
  • ICN_FOR_EVERYONE.md - General-public introduction starting from "what is a cooperative"; receipts as evidence records, not crypto; explicit non-claims
  • ICN_HANDBILL.md - One-page handbill with honest "where it actually stands" framing
  • ICN_HARD_QUESTIONS.md - Hard questions answered directly (bad-answer/honest-answer format): production use, fixture vs live vs design-only, capture, surveillance, private data, regulation, bus factor
  • ICN_INTRODUCTION_EVIDENCE_MAP.md - Maps every introduction claim to verifiable merged artifacts and states what each does NOT prove

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