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
  • receipt-chain-verification.md - Normative contract for a mechanical, offline re-verifier of ICN receipt chains (ADR-0026 re-verifiability made enforceable): content-hash recompute, fail-closed Pass/Fail/Unresolved/NotApplicable folding, generic chain-link + collision checks. Implemented as icn-governance::verify and consumed by a rewritten icnctl audit verify; proves integrity/authenticity only. A concrete supersedes-linked domain-policy-adoption receipt class is a deferred consumer (needs a crash-atomic cross-store transition)
  • 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)
  • local-issuance-audit-record.md - Trusted-local icnctl --local-mint issuance audit record (#2399): a secret-free append-only JSONL operator log for the rehearsal/appliance boundary, explicitly labeled as operational provenance and not cryptographic evidence; defines exact BLAKE3 fingerprints for scope-set and public issuer identity, fail-closed write semantics, actual minting command paths, and deferred daemon-side ingestion. Design decision only; no runtime writer, daemon evidence binding, production trusted-issuance path, governance approval, bearer credential, revocation infrastructure, or #2080 implementation
  • 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)
  • governed-bridge-receipts.md - Governed bridge receipt vocabulary (draft spec / requirements vocabulary, #2365) — names the expected/future receipt family a governed bridge import would emit (BridgeDryRunReceipt, BridgeReviewDecisionReceipt, BridgeImportReceipt + minimum evidence, VaultObjectWriteReceipt, ArtifactRegistrationReceipt, ExternalReferenceObservationReceipt, discard/policy-block classes, and a provisional follow-up underlying-object receipt), with the evidence boundaries: ArtifactReceipt is transfer proof only (not registry registration), and action cards are derived read views (no card-write receipt). Derived from the NYCN airlock requirements note; vocabulary/boundary planning only, implements nothing
  • governed-bridge-toolmanifest-modes.md - Governed bridge ToolManifest modes (draft spec / capability declaration model, #2366) — models how a future bridge tool (a ToolRuntimeMode: bridge adapter per RFC-0017) declares safety modes: source_shape_read vs gated real_row_read, dry_run_preview, no_default_write, steward_review_handoff, custody_write, external_reference_observe, refusal_policy_enforcement, export_delete_recovery; ties each mode to the receipt evidence contract in governed-bridge-receipts.md and defers per-run source/scope/target pinning to GovernedServiceBinding (#2367). Illustrative non-normative manifest sketch; no ToolManifest change, implements nothing
  • governed-bridge-service-binding.md - Governed bridge service binding (draft spec / binding model, #2367) — models how a future governed bridge refines GovernedServiceBinding (#1815) to pin per-(record, field) custody for one import run: allowed_source_systems, field_custody_map (source-authority → privacy class → custody target), allowed_scoped_vault_targets / allowed_artifact_registry_namespaces / allowed_governed_object_targets, receipt_sink, required_receipts, export_delete_recovery_refs, and 13 promotion gates. Inherits the binding's never-widens custody-class rule; per-run permission layer that narrows the #2371 manifest modes to concrete sources/scopes/targets. Illustrative non-normative field-custody-map sketch (opaque source refs, example field paths only); no binding change, implements nothing
  • governed-bridge-external-references.md - Governed bridge external references (draft spec / external reference model, #2368) — the observe-only external-custodian model a governed bridge uses to record that an external system holds authority over a fact (invoice status, registration/ticket/check-in status, external file/consent id) without importing the document, processing settlement, or claiming to be its source of truth. Defines the reference record (opaque/hash-bound external_record_ref, external_status, observed_at, source_hash, mapping_version, authority_basis, …), the ExternalReferenceObservationReceipt minimum evidence, binding policy + promotion-gate hooks, source-authority/freshness, privacy rendering, and export/delete/recovery distinguishing ICN-reference lifecycle from external-source lifecycle. Observe-only; no settlement/payment/connector; implements nothing
  • governed-bridge-steward-review.md - Governed bridge steward review surface (draft spec / steward review surface, #2369) — the minimum steward-facing review surface a governed bridge must present before turning a dry-run proposal into real custody writes; the "Steward review surface (#2369)" that BridgeReviewDecisionReceipt and the binding's steward_review_surface field point at, modeled as a Steward Cockpit affordance. Defines minimum review inputs (dry-run plan hash, opaque source-record refs, field classes, proposed targets/receipts, policy blocks, gate fields, external observations, export/delete path), required decisions (approve/reject/hold/block/discard/request-re-observation/request-reclassification/request-member-consent-review) each tied to a receipt, role-display-vs-verifiable-authority-proof, per-(record, field) reviewed-set binding (never bare field names, no silent gaps), care/accessibility need-to-know boundaries, publication/consent policy-block boundaries, derived-action-card visibility, and the separate future member consent review. Review-surface planning only; implements nothing
  • governed bridge conformance fixtures (review-coverage-v0) - First machine-checkable conformance slice for the six governed-bridge specs — a fake fixture (binding + dry-run + steward-review + expected-receipts) plus tools/validate-governed-bridge-conformance.py, proving the minimum chain binding → dry-run → steward review → expected receipts: per-(record, field) coverage (no bare field names, no silent gaps, no duplicates), reviewer authority proof required, dry-run writes nothing, ArtifactReceipt ≠ ArtifactRegistrationReceipt, action cards not write targets, external references observe-only. Fixture/tooling only; no real data, no connector, no runtime import
  • governed-bridge-nycn-handoff-map.md - Governed bridge NYCN handoff map (draft spec / handoff map, #2377) — maps NYCN's fake airlock rehearsals (intake §3–§12; relationship/recognition/obligation §14, translating the package-local pipeline into generic relationship.* custody with package nouns confined to source columns) onto the ICN governed-bridge conformance contract, backing the fake fixtures nycn-intake-handoff-v0 and nycn-relationship-handoff-v0: record/field identity using per-fixture generic field_paths (attendee.* for intake, relationship.* for the relationship map) with opaque source-record refs, privacy-class pass-through, custody-target translation (NYCN future_icn_target → ICN 7-kind enum), gate-field handling, the reviewer-authority and plan-hash gaps (NYCN role-only / no plan hash vs ICN reviewer_authority_ref / reviewed_plan_hash), compound-decision decomposition into per-(record, field) atomic verbs, receipt translation, and the action-card write conflict (routed through governed_object + FollowUpObjectCreationReceipt; cards are derived read views). Both sides fake; observe-only external references; opens no issues, implements nothing
  • governed bridge conformance fixtures (nycn-intake-handoff-v0) - Second fake conformance fixture — expresses NYCN's fake intake-import airlock rehearsal in the ICN governed-bridge contract (binding → dry-run → steward review → expected receipts), passing tools/validate-governed-bridge-conformance.py unchanged. Three fake intake records → nine actions over five naturally-occurring custody kinds (artifact_registry / scoped_vault / governed_object / external_reference / discard); exercises approve/discard/block verbs and the automatic-vs-human block distinction; no-consent follow-up is an automatic block on the follow-up governed_object. Handoff fidelity, not taxonomy coverage; no invented fields; no policy_gate/policy_block kind (left to review-coverage-v0 + the relationship slice). Fixture/tooling only; no real data, no connector, no runtime import
  • governed bridge conformance fixtures (nycn-relationship-handoff-v0) - Third fake conformance fixture — expresses NYCN's fake relationship-pipeline airlock rehearsal (package-local source vocabulary stays in the NYCN repo) in the ICN governed-bridge contract through generic relationship.* field paths, passing the validator unchanged. Three fake records → twenty-three actions over six naturally-occurring custody kinds (artifact_registry / policy_block / governed_object / scoped_vault / external_reference / discard); first fixture to use the generic GovernedObjectCreationReceipt (commitment record, object_class as institution-declared opaque data) alongside FollowUpObjectCreationReceipt (follow-up record); exercises approve/hold/block(automatic)/discard, denied-permission publication blocks, held-vs-observed external references, and the declined-record closure path (never a commitment; record-state custody limit documented). ICN core learns no package nouns. Fixture/tooling only; no real data, no connector, no runtime import
  • 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
  • member-shell-i18n-v0.md - Member shell v0 i18n seam — the language-modularity contract for the reference client (icn#2042): locale-keyed message catalog, t() fallback order, locale resolution (?lang= → navigator.language → en), lang/dir + RTL, a pseudo-locale coverage test, and the translation-pending rule. Dependency-free; adding a language is a catalog entry, not a code change. Non-goals: real translations, server-side locale negotiation
  • 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.
  • community-proof-spine-0.1.md - Community Proof Spine 0.1 (icn#2084) — the smallest honest, fixture/dev proof that the RFC-0018 entity-authority spine (require_entity_access, #2079 / ADR-0035) can carry a community-shaped civic action end to end (belonging → standing → authority → action → ADR-0026-style blake3 receipt → recompute-verify → plain-language explanation). Models the community as an icn-entity Community entity; does NOT reconcile the icn-community crate. Runtime proof in icn-gateway (steward allowed, plain member denied, receipt tamper detected) + a ?mode=demo&set=community member-shell fixture mirror. Boundary: no new endpoint, no new persisted receipt type, no new EntityAction variant, no enforcement change, no kernel change; Meaning Firewall preserved; fixture/dev 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.

These links include historical reports, current scanning notes, and point-in-time triage records. They do not by themselves establish current production readiness, vulnerability remediation status, deployment approval, or security hardening completion.

Security Documentation (security/)

Historical security assessments and references:

Threat Models & Audits:

SDIS Security:

Specialized Topics:

SDIS Documentation (sdis/)

Sovereign Digital Identity System:

🎯 Specialized Topics

Onboarding (onboarding/)

Contributor onboarding materials:

Deployment & Operations

Appliance proof plans (demo/):

  • TWO_NODE_APPLIANCE_PROOF_V0.2_PLAN.md - Bounded, gated execution plan for a two-node appliance proof (two independently initialized VMs from one reviewed image, distinct identities, DID-bound peer relationship, receipt bundle verified offline, restart/reboot continuity, backup and independent restoration). Plan only — not an executed proof; Gate 4 is BLOCKED pending an offline receipt-bundle exporter/verifier contract, and federation is explicitly not exercised

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 (dated snapshots, March–July 2026):

Current Status Reports (status/)

Live status reports and deployment verification:

Architecture Decision Records (adr/)

Formal architectural decisions:

  • ADR-0010-app-topology.md - App topology decision
  • ADR-0086-deployment-profiles.md - Deployment profiles and the public/private infrastructure boundary: Debian appliance as the canonical sovereign-node artifact, Docker Compose as the disposable development network, Kubernetes/K3s as optional hosted operator infrastructure, native Linux as an advanced installation form. status: proposed, implementation_status: partially implemented — merging the record does not adopt the decision, and only the appliance profile has a retained build-and-boot witness
  • Additional ADRs as numbered documents

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