Read the system, and know what you are reading.
ICN's documentation is written in the open and kept in the repository. That includes material which is no longer true — old plans, completed phases, superseded decisions. Rather than delete it, we sort it, so a page can never quietly present itself as current when it is not.
If you don't know what to search for
Each path is a short reading sequence assembled from existing pages. They are the fastest way into a corpus this size.
-
Understand the project
What ICN is, what problem it addresses, and how one decision travels through the system.
-
Build or contribute
Get the workspace running and find a contribution path that matches the repository as it exists.
-
Understand governance
How proposals, decisions, mandates, and the kernel/app boundary actually work.
-
Understand economics and resource governance
The vocabulary discipline — obligation, allocation, settlement — and how external bridges are framed.
-
Understand federation
How distinct cooperatives coordinate without merger — treaties, attestations, cross-institution clearing.
-
Understand design and accessibility
The cross-surface design system, content discipline, and the accessibility floor for member-facing surfaces.
-
Check current project state
Dated, per-subsystem maturity with the evidence behind each claim. Read this before assuming any subsystem is more finished than it is.
-
Run infrastructure
Deployment routing and cluster topology for anyone standing a node up themselves.
Browse everything current
Search covers the 597 current documents below — Learn, Current reference, and Decisions. Historical material is searchable separately so it cannot be mistaken for current guidance.
/
Learn
Start here
Guides
- Agent Context Spine (v0)
- Agent MCP tooling (icn-ops)
- Backup and Recovery Guide
- Backup and Restore: Operator Recovery Procedure
- Claude Code plugin: icn-agent-pack
- Cooperative Setup Guide
- Cursor and Claude MCP Setup
- Data Recovery Procedure
- Developer Guides
- Documentation Style Guide
- Emergency Node Restart
- Frequently Asked Questions (FAQ)
- ICN Agent Context Spine Plan
- ICN Daemon Mode with Governance Receipts
- ICN Development Environment
- ICN Institution Setup Guide
- ICN Invite System - Quick Reference
- ICN Operations Guide
- ICN Operations Runbooks
- ICN Pilot Cluster Operator Runbook
- ICN Replication Operations Guide
- ICN Troubleshooting Runbooks
- Internationalization (i18n) Migration Guide
- NAT Traversal Operations Guide
- NAT Traversal Pilot Test Guide
- Network Policy Design — ICN K3s Cluster
- Onboarding Runbook
- Operations Guides
- Phase 0 Operational Monitoring
- Pilot Smoke Runbook
- Pilot Vertical Slice Smoke
- Secrets Rotation Procedure
- Security Incident Response
- Summit Decision Registry Demo
- Treasury Entity-Auth Enforce-Mode Runbook
- Troubleshooting Guide
- User Guides
- Version Upgrade Procedure
- Why ICN?
Onboarding
- 01: Environment Setup & Repository Navigation
- 02: Rust Through ICN's Lens
- 03: Errors and Tracing — Distributed Visibility
- 04: Actors and Concurrency
- 05: The Meaning Firewall — ICN's Central Design Principle
- 06: Persistence and Ledger — Time-Communication + Invariants
- 07: Identity and Cryptography — Practical Crypto for ICN
- 08: Network and Gossip — Eventual Consistency Without Consensus
- 09: Governance and Contracts — Democratic Rule Changes
- 10: Federation and Operations — Production Deployment
- 11: Maintainer Skills — Reshaping Architecture Safely
- Accelerated Track (4 weeks)
- Assessments
- Capstone: Local Two-Node ICN + Ledger Flow
- Capstone: Maintainer Demonstration
- Curriculum Gap Analysis and Iteration Plan
- Curriculum Update Process
- Foundations Track (8 weeks)
- Gate 1: Becoming a Reader
- Gate 2: Becoming a Fixer
- Gate 3: Becoming a Builder
- ICN Common Patterns Reference
- ICN Contributor Ladder
- ICN Developer Onboarding Curriculum
- ICN Systems Textbook
- Lab 01: Workspace Setup
- Lab 02: Error Receipts and Tracing
- Lab 03: Mini Actor Runtime
- Lab 04: Firewall Oracle — THE KEYSTONE LAB
- Lab 05: Mini Ledger with Double-Entry and Quarantine
- Lab 06: Signed Envelopes with Replay Protection
- Lab 07: Gossip Sync with Vector Clocks
- Lab 08: Governance Flow — Proposal to Constraint Update
- Module 0: Setup and Tooling
- Module 1: Rust Fundamentals
- Module 10: Contributor Workflow
- Module 11: Federation and Inter-Cooperative Agreements
- Module 12: Observability and Metrics
- Module 13: Security and Privacy Layers
- Module 14: Governance and CCL Deep Dive
- Module 2: ICN Architecture Overview
- Module 3: Runtime and Actor Model
- Module 4: Identity and Trust
- Module 5: Network and Gossip
- Module 6: Ledger and Contracts
- Module 7: Gateway API and SDK
- Module 8: Web UI Integration
- Module 9: Operations and Deployment
- Module Template
- Onboarding Resources
- Reading Map
- Syllabus
- Workshop 0: Local Build and Repo Orientation
- Workshop 1: Rust Fundamentals in Practice
- Workshop 10: Contributor Workflow Practice
- Workshop 11: Federation Hands-On
- Workshop 12: Observability and Metrics
- Workshop 13: Security and Privacy Layers
- Workshop 14: Governance and CCL Deep Dive
- Workshop 2: Architecture Mapping Exercise
- Workshop 3: Runtime and Actor Lifecycle
- Workshop 4: Identity and Trust Hands-On
- Workshop 5: Network and Gossip Deep Dive
- Workshop 6: Ledger and Contract Flow
- Workshop 7: Gateway Auth and SDK Usage
- Workshop 8: Web UI Exploration
- Workshop 9: Local Deployment and Observability
Current reference
Core
Architecture
- Abuse-case hardening strategy
- Architecture Documentation
- Architecture due diligence
- Architecture Update - December 17, 2025
- Auth Bridge and DID Login
- Canonical Encoding Specification
- Cells & Scopes Architecture
- Complete Architecture Audit - December 17, 2025
- Comprehensive Architecture Review
- Cooperative Domain Infrastructure
- Cooperative Tool Commons
- Debian Appliance Model
- Domain Routing and DNS Bindings
- Federation Actions Specification
- Federation Interoperability Contract
- GEN-A — context-scoped Subject genesis (SubjectContextGenesisV1)
- Governance State Machine Specification
- Human Identity in ICN — a first-principles architecture
- ICN Agent Runtime
- ICN Architectural Gaps & Weaknesses - Analysis & Remediation Plan
- ICN Architecture Completion Status
- ICN Architecture Comprehensive Audit - 2025-12-17
- ICN Architecture Documentation Index
- ICN Architecture Quick Reference Card
- ICN Architecture Review - Complete Coverage Checklist
- ICN Architecture Review & Post-Quantum Integration - Session Summary
- ICN Architecture Wiring Audit
- ICN Client Architecture: Passport, Keyring, Position, Receipt
- ICN Complete Architecture Map
- ICN Complete Architecture Review - Executive Summary
- ICN Integrated System Model
- ICN Operating Model
- ICN Visual Architecture Reference
- Identity Semantics — the N2 semantic contract
- Implementation Gap Analysis
- Inbound Handshake Cancellation (#2521) — Causal Record
- Institution Package Boundary
- Institutional Feedback and Support Primitives
- Kernel/App Separation Architecture
- Meaning Firewall Phase 2 Audit
- Member Standing and Accessible Participation
- Model Workloads and Deliberation
- Mutation controls for the #2517 migration tests
- N2-A — migration gate: collision scan, dispositions and partner invariants (#2627)
- N2-A0 — stored-key inventory before Did canonicalization (#2623)
- Network identity: the local node is never a remote peer
- Network Session Identity Binding
- Private Data Disclosure Boundary, Scoped Vaults, and Access Receipts
- Protocol Selection for Member Services
- Protocol state migration invariants
- Replay state and restart invariants
- Restart/rejoin investigation (#2504) — causal record
- Scope-Bounded Trust: Structural Centralization Prevention
- Service Hosting Model
- The Authority Spine
- The Commons
- The Principal Model
CI
Contracts
Demo
- Assembled Rehearsal Node — organizer → member loop (appliance)
- From This Rehearsal to the Horizon: What ICN Does Today, and What It Is For
- Governance Proposal/Vote Fixture Handoff
- ICN Architecture Overview
- ICN Demo Script
- ICN Demo: Start Here
- ICN FAQ & Talking Points
- ICN Governance Demo — Walkthrough
- ICN July Demo — Hands-On Guide
- ICN July Demo — Operator Checklist
- ICN July Demo Candidate 0.1 — Hand-off Packet
- ICN July Demo Candidate 0.1 — Operator & Reviewer Handoff Script
- ICN Quick Start
- ICN Rehearsal Node v0.1 Runbook
- ICN System Demo Readiness Map
- July Demo Candidate 0.1 — accessibility + rendered-browser walkthrough evidence
- July Demo Candidate 0.1 — human accessibility validation packet
- July Demo Candidate 0.1 — organizer-steward process-evidence surface walkthrough
- Two-node appliance proof v0.2 plan
Deployment
- 🚀 ICN Quick Start - Full Stack
- Deploy ICN Test Network
- Full Stack Deployment Guide
- ICN Deployment - Complete Guide
- ICN Deployment Active
- ICN Deployment Guide
- ICN Deployment Ready - December 12, 2025
- ICN Deployment Status - December 12, 2025
- ICN Invite System - Deployment Guide
- ICN Invite System - K3s Deployment Guide
- ICN Quick Deploy Reference Card
- icn.zone Domain Routing Plan
Design
- Access, Made-Available, and Disclosure Receipt Decision Rung — R1–R10 (what comes after export-prepared)
- ActivationCrossedReceipt — Design/Audit Contract
- ActivationCrossedReceipt decision rung — B1/B2/B3 (decision → activation reference, gate basis, timestamp)
- Agent Handoff: Deterministic Compute Sprint
- apps/membership coop_core — Map-Parity Contract (#2082 gap 12b)
- Authenticated governance replication (#2469)
- Candidate Icon Family · Review Package
- Capability-Based Feature Gating
- Claude Design — ICN Context
- Claude Design — ICN Setup and Workflow
- Claude Design Handoff Template
- Claude Design Review Protocol
- Claude Design Seed — Repository Workflow
- Claude Design Seed — Review Notes
- Claude Design Seed Changelog
- Commons Credit Enforcement V1 — Implementation Note
- Compute Classes: Legitimacy Compute vs Utility Compute
- Compute Substrate Design
- Compute Substrate Vertical Slice - Implementation Status
- Contribution Credits: Infrastructure Incentives Design
- CreateTreasury — Treasury entity_id Trust Semantics
- DecisionRecordedReceipt — Design/Audit Contract
- DecisionRecordedReceipt Q4 decision — recorded fact vs proposal/vote lineage
- DeliberationEntry kind taxonomy — Q3 decision
- DeliberationEntryRecordedReceipt — Design/Audit Contract
- Design Documentation
- Dual-Foundation Minimal-Seams Slice
- Economic Design Documentation
- Economic Model Validation
- Economic Modeling for Mutual Credit Systems
- Entity Dissolution Workflow
- Entity Dissolution: Before and After
- Entity-Aware Authorization Control Map
- Evidence Export and Delivery Boundary — Design/Audit Contract
- Evidence export/delivery boundary decision rung — EX1–EX8 (fact name, availability vs delivery, recipient scope, acceptance placement, v1 field set, vault/access interaction, challenge shape, smallest dogfood)
- EvidencePacketProducedReceipt — Design/Audit Contract
- EvidencePacketProducedReceipt decision rung — EP1/EP2/EP3/EP4/EP5 (predecessor linkage, packet-hash coverage, redaction boundary, meaning of "produced", human/AT status)
- Execution Bridge Specification
- Federation / Operator Surface — Concept
- Governance Broad-Fallback Observability and Retirement Evidence
- Governance Design Documentation
- Governance Model Validation
- Governance Primitives
- Governance Primitives
- Governance Write Authority Decomposition
- Governance:Write Decomposition — Design
- GovernanceDecisionReceipt Authority + Grant-Minting — Design
- Governed coop_id → EntityId Resolver — Design Seam
- ICN Accessibility Baseline
- ICN Commons Design System
- ICN Content Style Guide
- ICN Deterministic Compute Sprint
- ICN Deterministic Core (ICN-DC) Specification
- ICN Economic Architecture
- ICN Economic Safety Mechanisms
- ICN Economic Vision
- ICN Economics Subsystem — Truth Contract
- ICN Platform Layer Design
- ICN Project Governance
- ICN Prompt Library
- ICN Repo Reality Map
- ICN Scheduler Evolution Plan
- ICN Visual Asset Register
- ICN Visual Assets — Planning Layer
- ICN Visual Explainer Bible — v0
- ICN Visual Review Checklist
- ICN Visual System
- Institution-in-a-Box
- Institutional Structure + Event Model — Design Spec
- IPv6 Dual-Stack Transport and Endpoint Sets Design
- Made-Available, Federation Sync, Access, and Repair Boundary Map
- MandateGate — Act-Time Resolver Design
- Membership durable timestamp semantics — Design/Audit Contract
- Minimal Viable Coop (MVC) Track
- Multi-Device Identity Design (Phase 11)
- MutationAppliedReceipt — Design/Audit Contract
- MutationAppliedReceipt decision rung — A1/A2/A3/A4 (plan → application reference, result representation, timestamp, applied-witness boundary)
- MutationPlanRecordedReceipt — Design/Audit Contract
- MutationPlanRecordedReceipt decision rung — M1/M2/M3 (plan → activation reference, plan-body representation, timestamp)
- NAT Traversal Design
- Organizer / member accessibility gate
- Organizer rehearsal review → confirm workflow wireframe (interactive)
- Organizer review preview wireframe
- Organizer-steward evidence surface runtime dogfood — Design Contract
- Passport / Keyring / Position / Receipt — Identity & Custody Vocabulary Boundary
- Post-Quantum Cryptography in ICN
- ProcessSession Receipt Anchor — Design/Audit Contract
- Public site information architecture
- Razeto's Four Intercooperative Bodies: ICN Integration Design
- Regulatory-Safe Verifiable State Architecture
- RFC: ICN Commons Evolution
- Scope Scheduling: Capacity Slices and Preemption
- SDIS Design Documentation
- Social Recovery Design
- Social Recovery Guide
- Trust-Graph Integration for Witness Validation
- VE-001 — How ICN Works / Closure Loop
- VE-002 — Where You Are Acting / Scope Model
- VE-003 — Decision to Receipt / Provenance Trail
- VE-004 — Member Shell Concept
- VE-005 — Kernel / App Separation
- Wallet DID Migration Boundary — wallet_did / icn_wallet_did
- What Must Not Ship
Design Language
Dev
Maintenance
Manual
- Foundational Manual Baseline Lock
- Foundational Manual: Deterministic Boundary Types
- Foundational Manual: Economic State Resolution
- Foundational Manual: Executable Baseline-Lock Loop
- Foundational Manual: Identity Recovery and Capability Leases
- Foundational Manual: State Projection and Compaction
- Foundational Manual: Trustless Client Boundary
- ICN User Manual
Migration Guides
Mobile
Operations
Ops
Performance
Planning
Plans
- Agent Teams Launch Prompt: ICN Point A → Point B
- Authz Capability Graph (Phase B0) Implementation Plan
- Authz Capability Graph Design (Phase B)
- B3: Allocation Receipt Chain — Implementation Plan
- B3: Allocation Receipt Chain Design
- C3 NAT Traversal Design
- C3 NAT Traversal Implementation Plan
- Commons Credit Accounting Implementation Plan
- ICN Demo System Design
- ICN Federation Demo System — Implementation Plan
- ICN Formal Research Agenda: Architectural Hurdles and Track Briefs
- ICN Point A → Point B: Civilizational Consensus Stack
- Planning scratch (relocated)
- Sprint 11: Federated Governance Wiring — Implementation Plan
- Sprint 14 Closeout + Sprint 15 Scope
- Sprint 21: Meaning Firewall Policy Extraction Implementation Plan
- UI Polish: Conference-Ready Demo — Implementation Plan
Reference
- API Reference Documentation
- CCL Charter Templates
- CCL Map
- CI / Ops / Deploy Map
- Claim-Boundary Map
- Configuration Reference Documentation
- Current Truth Map
- Docs Control Map
- Entity Topology Patterns
- Full Repository Record Protocol
- Governance Playbook
- ICN API Versioning Guide
- ICN Configuration Management Guide
- ICN Gateway API (developer reference)
- ICN Invariants Catalog
- ICN Project Index
- ICN Repo Atlas
- ICN Repository Map
- ICN Upstream Lock Format (icn-upstream-lock/v1)
- Identity and Cryptography Map
- Identity Backend Configuration
- Institution Package Bootstrap Contract
- Network and Gossip Map
- Organizer Rehearsal Operability Map
- Pilot UI Current State Map
- Project Coverage Matrix
- Proof-Level Taxonomy and Capability Matrix
- Public state projection
- Remote coordination note (superseded sequencing)
- Runtime Surface Map
- Rust Workspace Map
- Service Hosting Map
- Show-Readiness Map
- Source Tree Map
- Source-of-Truth Map
- Stale and Archived Map
- Tool Commons Map
- Topic Subscriptions API
- Trust Threshold Configuration
- Website Truth Map
SDIS
- SDIS & Steward System - Completion Roadmap
- SDIS & Steward System - Deployment Status
- SDIS & Steward System Implementation Status
- SDIS + Steward System Status
- SDIS API Guide
- SDIS Complete Build - Detailed Plan
- SDIS Complete Integration - Implementation Session
- SDIS Gateway API Implementation - Session Complete
- SDIS Implementation Complete
- SDIS Implementation Plan for ICN
- SDIS Quick Start Guide
- SDIS User Guide
- SDIS: Secure Distributed Identity System
Security
- CodeQL alert triage — 2026-06-29
- CodeQL gossip nonce triage — 2026-06-29
- CodeQL triage closeout — 2026-06-29
- Comprehensive Security Improvements - December 18, 2025
- Educational Guide: Security Code Review & Fixes
- Final Security Status - December 18, 2025
- Gateway Content Security Policy
- ICN Security Roadmap
- ICN Threat Model
- Phase 10C Security Analysis & Production Hardening
- Production Hardening - Security & Stability
- SDIS Code Audit Checklist
- SDIS Cryptographic Review
- SDIS Threat Model
- Secret Management Best Practices
- Security Analysis - Remaining Issues
- Security Audit Report - cargo-audit
- Security Audit Results - December 2024
- Security Documentation
- Security Fixes - December 18, 2025
- Security Follow-up Tasks
- Security Testing Guide
- TOFU (Trust-On-First-Use) Security Model
Spec
- Artifact Registry and Scoped Vault — boundary, v0 design
- CCL Policy Registry and Hook Contract
- Community Proof Spine 0.1
- Compute Placement Policy
- Effect Dispatch Contract
- Federation Settlement Finality Spec
- Governed Bridge External References
- Governed Bridge Receipt Vocabulary
- Governed Bridge Service Binding
- Governed Bridge Steward Review Surface
- Governed Bridge ToolManifest Modes
- Governed Service Binding, Workload Manifest, and Runtime Provider
- ICN Civic Shell v0
- ICN Kernel Contracts Specification
- Institutional Powers and Legitimacy Invariants
- InstitutionalDomain and DomainPolicy
- Local issuance audit record (icnctl --local-mint)
- Member Shell i18n seam v0
- Member Shell v0
- Network Anti-Entropy Proof Loops
- Private-overlay DID activation flow (generic ICN spec)
- Receipt-chain verification contract (ADR-0026 re-verifiability, made enforceable)
- Steward Cockpit v0
- Storage Durability Policies — Backup, Replication, Recovery, Archive, Integrity
State
Status
Strategy
- ADR-001: What ICN Is
- Grant Application Artifacts
- ICN Budget Skeleton
- ICN Compliance Architecture
- ICN Constitutional Roadmap
- ICN Grant Narrative Core
- ICN Hard Questions and Evidence-Bound Answers
- ICN in Practice: Six Scenarios
- ICN Institutional Ecosystem Arc
- ICN Institutional Operability Roadmap
- ICN Introduction Evidence Map
- ICN Milestones
- ICN Operability Audit — 2026-03-25
- ICN Organizational Technical Alpha — Control Plan
- ICN Pilot Readiness Assessment
- ICN Roadmap — Live
- ICN Roadmap & Strategy: From Solo Developer to Cooperative Infrastructure
- ICN Second-Pass Strategy Brief (2026-07-17)
- ICN System-by-System Gap Analysis: Vision vs. Reality
- ICN Technical Whitepaper: Architecture of a P2P Constraint Engine for Democratic Organizations
- ICN, in Plain English
- ICN: Digital Infrastructure for the Democratic Economy
- ICN: Digital Public Infrastructure for the Cooperative Economy
- ICN: Infrastructure for the Cooperative Movement
- Infrastructure the cooperative movement owns
- Licensing strategy matrix (autonomy review)
- Sovereign Forge Strategy
- Sprint 24 Close — Commons-Compute Spine
- Sprint Plan: Close the Demo Gap
- The Evolution of ICN: From First Thought to Coordination OS
- What ICN Is
Templates
Testing
- CoopWallet Mobile App - Testing Instructions
- Integration Test Status
- LAN Rehearsal Node deployment (appliance LAN profile)
- Quick Mobile App Testing Guide
- Rehearsal reset and recovery — LAN Rehearsal Node
- Security Fixes Testing Summary
- Workstation browser test guide — LAN Rehearsal Node
- Workstation browser test matrix — LAN Rehearsal Node
Decisions — ADRs and RFCs
ADR
- Accessibility Baseline for Member Interfaces
- Action Card Contract
- ADR Candidate Registry as Architectural Memory
- ADR Lifecycle and Canonical Decision Index
- ADR-0001: Orchestration Plane Architecture (icn-ops)
- ADR-0002: MCP Server Registration via ~/.mcp.json
- ADR-0003: IPv6 Dual-Stack Transport with Endpoint Sets
- ADR-0004: ICN Base Layer Models Obligations and Attestations, Not Payment Rails
- ADR-0005: Commons Credit Settlement Architecture
- ADR-0006: Compliance Chain — Verifiable State Architecture
- ADR-0007: Commons Resource Policy — CCL Formula Extraction
- ADR-0008: Receipt Chain Vertical Slice and Audit Verify
- ADR-0009: Happy Eyeballs — IPv4/IPv6 Connection Racing Within Endpoint Categories
- ADR-0010: App topology and canonical app roots
- ADR-0015: Service Discovery Auth Semantics — Auth-gated with Enumeration-Safe 404
- ADR-0016: Admin Merge Exception Policy for GitHub Runner Pool Saturation
- Authority Grant Minting and Mandate Persistence Seam
- Canonical Truth Ownership — Gateway vs Supervisor
- CCL Determinism, Fuel, and Capability Safety
- CCL Institutional Process Language
- CCL Schema Bridge and Constraint Compilation
- Commons Compute Admission and Settlement Policy
- Compute Workload Manifest and Authority Boundary
- Conflict Resolution Object Model
- Constitutional Object Model — AuthorityClass, AuthorityGrant, TypedScope, Mandate
- Controlled treasury entity-id backfill apply contract
- Entity-aware request authorization (require_entity_access) — primitive + treasury observe
- Federation Clearing Adoption Contract — Step 3 Architecture Design
- Federation State Origin Model — Gateway vs Governance vs Compute
- ICN deployment profiles and public/private infrastructure boundary
- Institution Package Manifest Schema
- Institutional Bootstrap Activation and Standing Read Model
- Institutional Domain and Domain Policy runtime root
- Institutional Effect Record Canonical Schema
- Monorepo Consolidation with Explicit Internal Boundaries
- Public Maturity Claims and Evidence Links
- Receipt and Provenance Proof Envelope
- Short Decision Title
- Website Truth Boundary
Rfcs
- docs/rfcs/
- Entity-Aware Request Authorization (EntityId + membership/hierarchy/delegation, migrate off flat coop_id guards)
- Generic Relationship Surface (RelationshipRecord primitive)
- Obligation / Allocation / Settlement Primitives and External Settlement Bridges
- Public Surface and Learning Repo Architecture
- RFC Process
- Short RFC Title
- Tool Install Infrastructure (ToolManifest, ToolBinding, ToolInstall lifecycle)