Daemoniorum-LLC · paraphilic-ecchymosis · Feb 3, 2026 · Jan 20, 2026 · Jan 20, 2026 · Jan 26, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -17,14 +17,17 @@ members = [
     "moloch-anchor-bitcoin",
     "moloch-anchor-ethereum",
     "moloch-bench",
+    "examples",
 ]
 
 [workspace.package]
 version = "0.1.0"
 edition = "2021"
 authors = ["Daemoniorum LLC"]
 license = "MIT"
-repository = "https://github.com/Daemoniorum-LLC/workspace"
+repository = "https://github.com/Daemoniorum-LLC/moloch"
+keywords = ["audit", "blockchain", "cryptography", "merkle", "zk-proofs"]
+categories = ["cryptography", "data-structures"]
 
 [workspace.dependencies]
 # Core
@@ -39,8 +42,8 @@ bincode = "1.3"
 rkyv = { version = "0.8" }
 
 # Crypto - using Arcanum primitives with SIMD-accelerated native backend
-arcanum-hash = { path = "../arcanum/crates/arcanum-hash", default-features = false, features = ["std", "backend-native", "blake3"] }
-arcanum-signatures = { path = "../arcanum/crates/arcanum-signatures", default-features = false, features = ["ed25519", "batch"] }
+arcanum-hash = { version = "0.1", default-features = false, features = ["std", "backend-native", "blake3"] }
+arcanum-signatures = { version = "0.1", default-features = false, features = ["ed25519", "batch"] }
 rayon = "1.10"
 rand = "0.8"
 hex = "0.4"
@@ -61,6 +64,7 @@ memmap2 = "0.9"
 
 # Time
 chrono = { version = "0.4", features = ["serde"] }
+chrono-tz = "0.10"
 
 # Logging
 tracing = "0.1"

diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # Moloch
 
-Cryptographic audit chain with post-quantum encryption, zero-knowledge proofs, and cross-chain anchoring.
+Cryptographic audit chain with post-quantum encryption, zero-knowledge proofs, cross-chain anchoring, and autonomous agent accountability.
+
+**~48,700 lines of Rust** across 16 crates and 113 source files. **361 tests** (348 unit + 13 integration).
 
 See [BENCHMARK_REPORT.md](BENCHMARK_REPORT.md) for performance data.
 
@@ -12,12 +14,35 @@ See [BENCHMARK_REPORT.md](BENCHMARK_REPORT.md) for performance data.
 - **Selective Field Encryption** - HoloCrypt encrypts sensitive fields while keeping structure visible
 - **Threshold Encryption** - k-of-n decryption schemes
 - **Cross-Chain Anchoring** - Anchor roots to Bitcoin (OP_RETURN) and Ethereum (calldata)
+- **Agent Accountability** - Cryptographically-enforced autonomous agent governance (see below)
+
+## Agent Accountability
+
+Moloch includes a comprehensive agent accountability framework for governing autonomous AI agent actions through cryptographic guarantees rather than trust assumptions.
+
+**12 modules, ~10,750 lines, 242 tests (229 unit + 13 integration)**
+
+| Module | Purpose |
+|--------|---------|
+| **Causality** | Lamport clocks and causal context chains linking every agent action to its cause |
+| **Principal** | Cryptographic agent identity bound to Ed25519 key pairs |
+| **Attestation** | Signed, timestamped claims with expiry and revocation support |
+| **Capability** | Scoped, delegatable, time-bounded permission tokens signed by grantors |
+| **Human-in-the-Loop** | Structured approval workflows with configurable policies (unanimous, threshold, any) |
+| **Reasoning** | Immutable reasoning traces capturing agent decision-making with constraint references |
+| **Outcome** | Post-execution outcome recording with severity-tiered evidence requirements |
+| **Emergency** | Circuit breaker and kill switch controls for immediate agent shutdown |
+| **Coordination** | Multi-agent commit protocols with Byzantine fault detection |
+
+Each module enforces its invariants cryptographically: capabilities are signed tokens that expire, attestations carry verifiable signatures, and outcomes require evidence proportional to impact severity.
+
+The implementation follows the [Agent Accountability Specification](docs/specs/AGENT_ACCOUNTABILITY.md) and was built under a strict [TDD roadmap](docs/specs/AGENT_ACCOUNTABILITY_TDD.md). A [remediation roadmap](docs/developer/AGENT_ACCOUNTABILITY_REMEDIATION.md) documents known gaps and planned hardening work.
 
 ## Architecture
 
 ```
 moloch/
-├── moloch-core           # Core types: Event, Block, signatures
+├── moloch-core           # Core types: Event, Block, signatures, agent accountability
 ├── moloch-mmr            # Merkle Mountain Range accumulator
 ├── moloch-chain          # Block chain management
 ├── moloch-storage        # RocksDB + mmap storage layer
@@ -192,6 +217,39 @@ The `moloch-api` crate provides:
 - JWT and API key authentication
 - Rate limiting and audit logging
 
+## Documentation
+
+```
+docs/
+├── MASTER_SPECIFICATION.md           # Full system specification
+├── INDEX.md                          # Documentation index
+├── specs/                            # Formal specifications
+│   ├── AGENT_ACCOUNTABILITY.md       # Agent accountability spec
+│   └── AGENT_ACCOUNTABILITY_TDD.md   # TDD implementation roadmap
+├── developer/                        # Developer documentation
+│   ├── quickstart.md                 # Getting started guide
+│   ├── architecture.md               # System design
+│   ├── api.md                        # REST/WebSocket API reference
+│   ├── security.md                   # Security considerations
+│   ├── configuration.md              # Configuration reference
+│   ├── deployment.md                 # Deployment guide
+│   ├── operations.md                 # Operations guide
+│   ├── OSS_RELEASE_ROADMAP.md        # Release roadmap
+│   ├── SPEC_GAPS.md                  # Specification gap analysis
+│   └── AGENT_ACCOUNTABILITY_REMEDIATION.md  # Remediation roadmap
+├── diagrams/                         # Architecture diagrams
+│   ├── anchoring-sequence.md
+│   ├── consensus-sequence.md
+│   ├── data-flow.md
+│   └── sync-sequence.md
+├── llm/                              # Agent-optimized docs (Sigil format)
+│   ├── quickstart.sigil
+│   ├── architecture.sigil
+│   ├── api.sigil
+│   └── security.sigil
+└── archive/                          # Historical documents
+```
+
 ## License
 
 MIT License - see [LICENSE](LICENSE)
@@ -202,7 +260,7 @@ See [SECURITY.md](SECURITY.md) for vulnerability reporting.
 
 ## Contributing
 
-See contributing guidelines before submitting PRs.
+See [CONTRIBUTING.md](CONTRIBUTING.md) before submitting PRs.
 
 ## Related Projects
 

diff --git a/docs/INDEX.md b/docs/INDEX.md
@@ -0,0 +1,127 @@
+# Moloch Documentation Index
+
+Complete index of all documentation for the Moloch cryptographic audit chain.
+
+## Documentation Map
+
+```
+moloch/
+├── README.md                    # Project overview
+├── CONTRIBUTING.md              # Contribution guidelines
+├── SECURITY.md                  # Security policy & vulnerability reporting
+├── CHANGELOG.md                 # Version history
+├── BENCHMARK_REPORT.md          # Performance benchmarks
+│
+└── docs/
+    ├── INDEX.md                 # This file
+    ├── MASTER_SPECIFICATION.md  # Complete system specification
+    │
+    ├── developer/               # Developer documentation
+    │   ├── quickstart.md        # Getting started guide
+    │   ├── architecture.md      # System architecture & diagrams
+    │   ├── api.md               # REST/WebSocket API reference
+    │   ├── security.md          # Security model & threat analysis
+    │   ├── SPEC_GAPS.md         # Specification gap analysis
+    │   ├── OSS_RELEASE_ROADMAP.md # Release planning
+    │   ├── deployment.md        # Deployment guide
+    │   ├── operations.md        # Operations & monitoring
+    │   └── configuration.md     # Configuration reference
+    │
+    ├── diagrams/                # Architecture diagrams
+    │   ├── data-flow.md         # Data flow diagrams
+    │   ├── consensus-sequence.md # Consensus protocol sequence
+    │   ├── sync-sequence.md     # Sync protocol sequence
+    │   └── anchoring-sequence.md # Anchoring protocol sequence
+    │
+    ├── llm/                     # Agent-optimized documentation
+    │   ├── quickstart.sigil
+    │   ├── architecture.sigil
+    │   ├── api.sigil
+    │   └── security.sigil
+    │
+    └── archive/                 # Historical documents
+        ├── ROADMAP.md
+        └── AGENT_QUICKSTART_v1.md
+```
+
+## Document Categories
+
+### Core Documentation
+
+| Document | Path | Description | Status |
+|----------|------|-------------|--------|
+| Master Specification | `docs/MASTER_SPECIFICATION.md` | Complete system specification | Complete |
+| README | `README.md` | Project overview and quick start | Complete |
+| Architecture | `docs/developer/architecture.md` | System design with diagrams | Complete |
+| API Reference | `docs/developer/api.md` | REST/WebSocket API | Complete |
+| Security | `docs/developer/security.md` | Security model | Complete |
+| Quickstart | `docs/developer/quickstart.md` | Getting started guide | Complete |
+
+### Operational Documentation
+
+| Document | Path | Description | Status |
+|----------|------|-------------|--------|
+| Deployment Guide | `docs/developer/deployment.md` | Production deployment | New |
+| Operations Guide | `docs/developer/operations.md` | Running and monitoring | New |
+| Configuration Reference | `docs/developer/configuration.md` | All config options | New |
+
+### Architecture Diagrams
+
+| Document | Path | Description | Status |
+|----------|------|-------------|--------|
+| Data Flow | `docs/diagrams/data-flow.md` | Event lifecycle diagrams | New |
+| Consensus Sequence | `docs/diagrams/consensus-sequence.md` | Block production protocol | New |
+| Sync Sequence | `docs/diagrams/sync-sequence.md` | Node synchronization | New |
+| Anchoring Sequence | `docs/diagrams/anchoring-sequence.md` | External anchoring flow | New |
+
+### Planning & Process
+
+| Document | Path | Description | Status |
+|----------|------|-------------|--------|
+| Spec Gaps | `docs/developer/SPEC_GAPS.md` | Dead code gap analysis | Complete |
+| Release Roadmap | `docs/developer/OSS_RELEASE_ROADMAP.md` | OSS release planning | Complete |
+| Benchmarks | `BENCHMARK_REPORT.md` | Performance data | Complete |
+
+## Quick Links by Role
+
+### For New Developers
+1. [README](../README.md) - Project overview
+2. [Quickstart](developer/quickstart.md) - Build and run
+3. [Architecture](developer/architecture.md) - System design
+
+### For API Consumers
+1. [API Reference](developer/api.md) - REST/WebSocket endpoints
+2. [Quickstart](developer/quickstart.md) - SDK examples
+
+### For Operators
+1. [Deployment Guide](developer/deployment.md) - Production setup
+2. [Operations Guide](developer/operations.md) - Monitoring & maintenance
+3. [Configuration Reference](developer/configuration.md) - Config options
+
+### For Contributors
+1. [CONTRIBUTING](../CONTRIBUTING.md) - Contribution guidelines
+2. [Master Specification](MASTER_SPECIFICATION.md) - Complete spec
+3. [Spec Gaps](developer/SPEC_GAPS.md) - Areas needing work
+
+### For Security Auditors
+1. [Security](developer/security.md) - Threat model
+2. [SECURITY](../SECURITY.md) - Vulnerability reporting
+3. [Master Specification](MASTER_SPECIFICATION.md) - Cryptographic specs
+
+## Document Standards
+
+### Markdown Conventions
+- GitHub-flavored Markdown
+- ASCII diagrams for inline visualization
+- Code blocks with language annotations
+- Tables for structured data
+
+### Diagram Standards
+- Mermaid syntax for sequence diagrams (when GitHub renders)
+- ASCII art for maximum compatibility
+- Include text descriptions for accessibility
+
+### Update Policy
+- Specs updated before implementation (SDD methodology)
+- Tests written after spec approval (Agent-TDD)
+- Diagrams updated with architecture changes