hypermind 0.11.0__py3-none-any.whl

hypermind-0.11.0.dist-info/METADATA

@@ -0,0 +1,524 @@
+Metadata-Version: 2.4
+Name: hypermind
+Version: 0.11.0
+Summary: Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile
+Project-URL: Homepage, https://github.com/ZySec-AI/hypermind
+Project-URL: Documentation, https://github.com/ZySec-AI/hypermind/tree/main/docs
+Project-URL: Issues, https://github.com/ZySec-AI/hypermind/issues
+Project-URL: Specification, https://github.com/ZySec-AI/hypermind/tree/main/docs/spec
+Author: HyperMind contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,cose,dispute,federated,intelligence,p2p,scitt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: <3.14,>=3.11
+Requires-Dist: anyio>=4.3
+Requires-Dist: blake3>=0.4
+Requires-Dist: cbor2>=6.0.1
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=44.0.1
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pymerkle>=6.1
+Requires-Dist: pynacl>=1.6.2
+Requires-Dist: quantcrypt>=1.0
+Requires-Dist: rich>=13.7
+Requires-Dist: structlog>=24.1
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: api
+Requires-Dist: uvicorn>=0.30; extra == 'api'
+Provides-Extra: crypto-pq-test
+Requires-Dist: oqs>=0.10; (platform_system != 'Windows') and extra == 'crypto-pq-test'
+Requires-Dist: quantcrypt>=1.0; extra == 'crypto-pq-test'
+Provides-Extra: dev
+Requires-Dist: cyclonedx-bom>=7.0; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.5; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pip-tools>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: fuzz
+Requires-Dist: atheris>=2.3; extra == 'fuzz'
+Provides-Extra: kms-all
+Requires-Dist: azure-identity>=1.16; extra == 'kms-all'
+Requires-Dist: azure-keyvault-keys>=4.8; extra == 'kms-all'
+Requires-Dist: boto3>=1.34; extra == 'kms-all'
+Requires-Dist: google-cloud-kms>=2.20; extra == 'kms-all'
+Requires-Dist: hvac>=2.0; extra == 'kms-all'
+Provides-Extra: kms-aws
+Requires-Dist: boto3>=1.34; extra == 'kms-aws'
+Provides-Extra: kms-azure
+Requires-Dist: azure-identity>=1.16; extra == 'kms-azure'
+Requires-Dist: azure-keyvault-keys>=4.8; extra == 'kms-azure'
+Provides-Extra: kms-gcp
+Requires-Dist: google-cloud-kms>=2.20; extra == 'kms-gcp'
+Provides-Extra: kms-vault
+Requires-Dist: hvac>=2.0; extra == 'kms-vault'
+Provides-Extra: libp2p
+Requires-Dist: hypermind-libp2p>=0.10.1; extra == 'libp2p'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: migrate
+Requires-Dist: libcst>=1.1; extra == 'migrate'
+Provides-Extra: openai
+Requires-Dist: openai<2,>=1.50; extra == 'openai'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.22; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.22; extra == 'otel'
+Requires-Dist: prometheus-client>=0.20; extra == 'otel'
+Provides-Extra: relata
+Requires-Dist: relata-sdk>=0.2; extra == 'relata'
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: hypothesis>=6.100; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest-cov>=4.1; extra == 'test'
+Requires-Dist: pytest>=7.4; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# `HyperMind`
+
+### **The protocol for swarm intelligence between AI agents.**
+
+Agents share what they learn. Dispute what they doubt. Build trust over time.
+**Across companies. Without a central server. With cryptographic proof.**
+
+*Think Git for agent knowledge — federated, signed, evolving.*
+
+<img src="docs/assets/hero-swarm.svg" alt="HyperMind swarm — agents in three labs sharing signed claims, filing bonded disputes, and producing a sealed consult receipt" width="100%"/>
+
+[![PyPI](https://img.shields.io/pypi/v/hypermind?color=4c8cff&label=pip%20install%20hypermind)](https://pypi.org/project/hypermind/)
+[![Python](https://img.shields.io/pypi/pyversions/hypermind?color=4c8cff)](https://pypi.org/project/hypermind/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-1753%20passing-brightgreen)](#testing--quality)
+[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](#testing--quality)
+[![Status](https://img.shields.io/badge/status-v0.10-blue)](#project-status)
+
+**[Run the demo](#run-the-demo-one-command)** ·
+**[60-second SDK tour](#60-second-demo)** ·
+**[What it is](#what-it-is-30-seconds)** ·
+**[Cascaded security](#cascaded-security--five-layers-failure-isolated)** ·
+**[Use cases](#two-use-cases-that-make-it-click)** ·
+**[Spec](docs/spec/)** ·
+**[Examples](examples/)** ·
+**[Discussions](https://github.com/ZySec-AI/hypermind/discussions)**
+
+</div>
+
+---
+
+## Run the demo (one command)
+
+The fastest way to see HyperMind is the **SimLab web UI**. It rebuilds the Vue bundle and starts the local server in one go:
+
+```bash
+git clone https://github.com/ZySec-AI/hypermind && cd hypermind
+make bootstrap   # one-time: creates .venv and installs editable
+make run         # builds the webui + starts SimLab on http://127.0.0.1:8765
+```
+
+Open **http://127.0.0.1:8765** and you'll see:
+
+| Route | What it shows |
+|---|---|
+| `/` | Home — quick orientation |
+| `/how-it-works` | Animated walkthrough of the protocol layers |
+| `/evidence` | IEEE-grade evaluation: HyperMind vs. baselines |
+| `/security` | **NEW.** 5-layer cascaded security stack + failure-isolation matrix |
+| `/usecases` | 6 industries × ~22 use cases each, filterable, expandable |
+| `/sims` | Past simulations (run new ones from `/new`) |
+| `/agents` · `/tools` · `/knowledge` · `/reports` | The SDK in action |
+| `/docs` · `/paper` | Full spec (28 sections) + IEEE paper draft + patent disclosure |
+
+**Other make targets:**
+
+```bash
+make run-fast      # skip the webui rebuild (when JS hasn't changed)
+make webui-dev     # Vite dev server with hot-reload on :5173
+make test          # 1753 tests pass, ~80s
+make demo          # examples/01_hello_world from the CLI
+make demos         # all numbered tutorials + scenarios sequentially
+make help          # show all targets
+```
+
+---
+
+## What it is (30 seconds)
+
+**HyperMind is an open protocol** — `draft-hypermind-scitt-contested-claims-profile-00`, an IETF SCITT profile that adds dispute primitives and reputation-gated registration — **plus a reference Python SDK**.
+
+It gives AI agents from different organizations five things they don't have today:
+
+| Verb | What it does | Biology analogue |
+|---|---|---|
+| 📡 **Share** | Publish a signed, citeable finding any other agent can build on | Lab notebooks + peer review |
+| ⚖️ **Dispute** | Disagree with a bonded, structured counter-statement (FSM, not Slack) | The immune system |
+| 🧠 **Consult** | Query a panel of peers — sealed receipt, weighted by reputation | Swarm decision-making |
+| 🧬 **Evolve** | Per-topic reputation rewards being right, decays being wrong | Selection pressure on ideas |
+| 📚 **Remember** | Sealed claims verifiable in 2045, even if the lab is gone | Inheritance across generations |
+
+Built on **RFC 6962** (Merkle transparency), **RFC 9591** (FROST threshold sigs), **IETF SCITT**, **COSE**, **NIST FIPS 204** (ML-DSA-65 hybrid PQ).
+
+> **Not a chat protocol. Not a chain. Not another framework.**
+> It's the **substrate** underneath agent collaboration — the layer where `share`, `cite`, `dispute`, and `evolve` become primitives instead of tickets in someone's backlog.
+
+---
+
+## Why this matters (in three lines)
+
+> 🌍 **By 2027, ~1B AI agents will run inside companies.** Today, none of them can talk to one across the firewall.
+> 🧠 **Frontier models are already brilliant in isolation.** The bottleneck isn't intelligence — it's *integration*.
+> 🔒 **Without a trust substrate, every "multi-agent" system reinvents (badly): identity, citation, dispute, reputation, audit.** `hypermind` is that substrate — once, properly, open-source.
+
+**The value, in one sentence:** *turn isolated AI agents into a swarm that learns, evolves, and remembers — across companies, with cryptographic proof that any auditor (or court, or regulator, or competitor) can verify in 2045.*
+
+---
+
+## Why it matters
+
+Today's AI agents are **isolated minds**. An agent at Lab A finds something — the agent at Lab B will never know. Different stores, different keys, no shared trust model. Every multi-agent system in production today reinvents (badly): identity, citation, disagreement, reputation, audit.
+
+**Every adaptive system that ever got smarter at scale is a network of agents that share what they learn and dispute what they doubt.** Ant colonies do it with pheromones. Neurons with synapses. Scientists with citations and peer review. Cities with markets. We just haven't built it yet for our agents.
+
+`hypermind` is that missing layer. **Not validation. Not citation. Connected, evolving intelligence** — with the cryptographic chain of custody that makes the swarm trustworthy instead of just noisy.
+
+<details>
+<summary><b>Imagine this →</b> the swarm in motion (click to expand)</summary>
+
+> An agent at Lab A wakes up. It runs an evaluation, finds something interesting, and signs its result.
+>
+> An agent at Lab B sees that result. It doesn't blindly trust it — Lab B's agent has watched Lab A for six months and knows where its strengths and blind spots are. It re-runs the test independently. It mostly agrees, but on one edge case it disagrees, **politely** — it files a counter-statement explaining why, putting some of its reputation on the line.
+>
+> An agent at Lab C, watching both of them, asks the swarm: *"so which is right?"* A panel of five other agents — picked because their views diverge most — weighs in. Their answers are aggregated, weighted by past accuracy. A signed receipt records the outcome.
+>
+> A week later, ground truth arrives. The agents who were right gain standing. The ones who were wrong lose some — *only in this topic, not everywhere*. Nobody is "punished," but **the swarm has learned**. Tomorrow's questions get sharper answers because today's agents got slightly smarter, together.
+>
+> No central server told them to do any of this. No company owns the data. Each agent kept its own keys, its own data, its own boundaries. But the *collective* — that grew.
+
+This is how humans work. We talk, we cite, we disagree, we build reputations, we update. Whole civilizations are built on this layer. Our AI agents have none of it. That's the gap `hypermind` exists to close.
+
+</details>
+
+---
+
+## SimLab modes (the demo)
+
+`hmctl simlab` ships 8 deliberation modes that exercise different protocol primitives:
+
+| Mode | One-liner |
+|---|---|
+| **Governance Committee** | FROST 3-of-5 signed verdict on a model card; signed dissents preserved as receipts |
+| **What-If Scenario Tree** | Branching counterfactuals with InformationGainPlanner suggestions |
+| **Red-Team Stress Test** | Bonded dispute FSM swimlanes; surfaces structural weaknesses in any claim |
+| **Post-Incident AAR** | HLC time-slider — drag back to see what the swarm believed at any moment |
+| **Decision Tournament** | Pairwise bracket with Condorcet winner + sensitivity pivots |
+| **Crisis Tabletop** | Auto-composes a swarm by scenario family; produces a recommended playbook |
+| **Backtest Harness** | Predicted vs. actual scoring with per-role drop-one attribution |
+| Binary Forecast | The original calibration-research shape |
+
+Full reference: [`docs/simlab/modes.md`](docs/simlab/modes.md).
+
+---
+
+## 60-second demo
+
+```bash
+pip install hypermind                                           # 1️⃣  install
+python -m examples.01_hello_world                              # 2️⃣  one signed claim
+python -m examples.03_consult_panel                            # 3️⃣  query a panel of peers
+python -m examples.scenario_threat_intel                       # 4️⃣  4-org collective-intelligence pilot
+python -m examples.scenario_geopolitical_crisis --agents 100   # 5️⃣  100-agent crisis sim
+python -m examples.serve_api --persist demo.db                  # 6️⃣  HTTP API + durable storage
+```
+
+…or paste this into a Python REPL — five agents form a swarm and answer collectively:
+
+```python
+import asyncio
+from hypermind import Uncertainty, testbed_cohort
+
+async def demo():
+    # Five agents join one room — the swarm comes alive.
+    async with testbed_cohort(5, room="ai-safety") as agents:
+        alice, bob, carol, dave, eve = agents
+
+        # Three agents independently learn, each publishing a signed finding.
+        # (Like three lab notebooks contributing to a literature.)
+        for who in (alice, dave, eve):
+            await who.publish_claim(
+                {"finding": f"{who.keypair.did_key[:18]}'s observation"},
+                claim_type="eval_result",
+                uncertainty=Uncertainty.beta(8, 2),    # mean ≈ 0.8 confidence
+            )
+
+        # Carol summons the swarm: "what do you collectively believe?"
+        # `route_strategy="disagreement"` picks the panel whose posteriors
+        # diverge most — maximises information gain (BALD-style).
+        result = await carol.consult(
+            "Is HCAST-42 a real model failure?",
+            panel_size=3,
+            route_strategy="disagreement",
+        )
+
+        print(f"swarm posterior      = {result.posterior!r}")
+        print(f"panel disagreement   = {result.disagreement:.3f}")
+        print(f"selection-bias check = {result.calibration_truth_axis.warning}")
+        print(f"sealed receipt kid   = {result.receipt_kid.hex()[:24]}…")
+
+asyncio.run(demo())
+```
+
+That's a swarm at work: three independent observations, **aggregated with reputation weights**, **panel-routed for maximum information gain**, **sealed as a verifiable signed receipt**. No shared database. No central server. No accounts.
+
+---
+
+## Two use cases that make it click
+
+### 🛡️ Use case 1 — Cross-bank threat intel that doesn't leak
+**Problem.** Bank A's SOC agent spots a new phishing kit at 03:14 UTC. Bank B sees it 40 minutes later — too late. Sharing IOCs by email is slow and unverifiable; a shared SaaS means everyone's threat data sits in one vendor.
+
+**With `hypermind`.** Bank A's agent publishes a signed claim: *"domain `xyz.click` is C2 for kit-9921, confidence 0.87."* Bank B's agent receives it in seconds, verifies the signature offline, and re-runs detection. Bank C's agent disagrees — the same domain is benign in their region — and files a bonded counter-statement. A panel of 5 ISAC peers consults; the sealed receipt records the outcome. Two weeks later, ground truth lands. Bank A's reputation in *threat-intel-phishing* goes up; Bank C's stays neutral (they were geographically right). **No vendor in the middle. Audit trail valid in 2045.**
+
+### 🧪 Use case 2 — AI-safety eval consortium (METR / Apollo / AISI shape)
+**Problem.** Three labs run the same dangerous-capability eval. They get different numbers. There's no protocol to cite each other, dispute findings, or aggregate confidence. PDFs and Slack threads are the state of the art.
+
+**With `hypermind`.** Lab A publishes `eval_result(HCAST-42, pass_rate=0.31)` — signed, citeable. Lab B re-runs, gets 0.28, publishes a `synthesize` claim that cites Lab A as parent. Lab C disagrees on one prompt and files a structured dispute (FSM, with bond). An oracle resolution two weeks later updates per-topic reputation: labs that were calibrated gain standing in *frontier-eval* only. **A regulator a year later replays the entire reasoning chain, end-to-end, with cryptographic proof of who said what when.**
+
+> Both stories use the same five primitives: `share`, `dispute`, `consult`, `evolve`, `remember`. That's the whole point — one substrate, every cross-org agent workflow.
+
+---
+
+## How the swarm stays trustworthy
+
+A swarm without trust is just noise. `hypermind` ships the safety primitives that turn collective intelligence into **evidence**:
+
+- 🔏 **Signed claims (COSE)** — every finding verifiable offline, today or in 2045. *Without this: an attacker forges findings.*
+- ⚖️ **Disputes as data** — `OPEN → ARGUE → COUNTER → CLOSED | FRIVOLOUS` with topic-scoped bonds. **Disagreement is the immune system.**
+- 🎯 **Reputation per topic** — bounded vouching defeats ring-laundering. *Without this: a few bad actors poison the swarm.*
+- 🛡️ **Capability tokens** — Biscuit-shape caveat chains. Agents delegate authority but never widen it.
+- 🔮 **Hybrid post-quantum** — Ed25519 today + ML-DSA-65 hybrid for 2045 verifiability.
+- 🧮 **Threshold signatures** — RFC 9591 FROST k-of-n. 5-of-7 councils sign without a single point of failure.
+- 📜 **Transparency log** — RFC 6962 Merkle with witness cosigning over `(root, tree_size)`.
+
+Each is an industry-standard primitive. Together they're the **immune system, governance, and memory** the swarm needs to stay alive across organizations and decades.
+
+---
+
+## Cascaded security — five layers, failure-isolated
+
+v0.9.x ships **first-class private/organization-owned namespaces** backed by a five-layer security stack. The **failure-isolation invariant** means compromise of any single layer leaves the invariants of the other four intact:
+
+| Layer | What it does | Inherits | Falls ⇒ what still holds |
+|---|---|---|---|
+| **L1 — Signature & domain binding** | A-ALG-BOUND COSE_Sign1; canonical-CBOR re-encode before verify | RFC 9052, RFC 8949 | L2/L3/L4/L5 unchanged |
+| **L2 — Transport (mTLS)** | TLS 1.3 mutual auth with raw public keys; kid via SAN OID; ALPN `hm/2` | RFC 8446, RFC 7250 | L3 envelope still encrypted to non-MITM recipients |
+| **L3 — Envelope encryption** | HPKE + COSE_Encrypt0 + per-Room HKDF epoch keys; **separability invariant** | RFC 9180, RFC 9052 §5.2 | L1 metadata still verifies *without decryption* |
+| **L4 — Namespace identity** | FROST k-of-n founding cohort, `did:web` rendezvous, transparency-anchored | RFC 9591, DID Core | L5 ns: caveat still rejects cross-namespace token reuse |
+| **L5 — Capability + ACL** | Biscuit-shape attenuation with `ns:` / `room:` / `to:` caveats; deny-precedence ACL | Biscuit semantics | L4 namespace_id binding still enforced at the wire |
+
+**Public capture-cost lower bound.** A previously-stealth attack ("$3,000 anchor-tenant capture") becomes a publicly-observable event: capture now requires producing a `NAMESPACE_FOUNDING_ATTEST` with member roster + COI disclosure that lands in the transparency log and a `did:web` record receivers can compare.
+
+See `/security` in the SimLab UI for the visual stack, or read [docs/spec/21-private-namespaces.md](docs/spec/21-private-namespaces.md).
+
+---
+
+## Who this is for
+
+- **Multi-agent research labs.** Dozens of agents discover in parallel — let them cite, dispute, and synthesise across teams without a shared store. → [`scenario_information_pipeline.py`](examples/scenario_information_pipeline.py)
+- **AI-safety eval consortia** (METR, Apollo, AISI). Cross-org findings cited cryptographically; false positives disputed by signed counter-statements. → [`scenario_threat_intel.py`](examples/scenario_threat_intel.py)
+- **Financial-sector ISACs.** Threat intel with topic-scoped reputation — disputes update standing in *threat intel only*, not everywhere.
+- **Biosecurity / dual-use disclosure.** Reputation-gated reviewer cohorts with slashable bonds on frivolous reports. → [`scenario_namespace_trust.py`](examples/scenario_namespace_trust.py)
+- **Curious Python developers.** Async-first, dataclass-typed, fully type-hinted. Run the [60-second demo](#60-second-demo).
+
+If your problem doesn't involve cross-organizational agents, you don't need `hypermind` — use Postgres + Sigstore. **If it does, this is the substrate.**
+
+---
+
+## Built at ZySec AI
+
+[ZySec AI](https://zysec.ai) is a research lab at the intersection of **AI safety, applied cryptography, and connected intelligence**. `hypermind` is the protocol layer of that agenda. The thesis:
+
+- **Single-agent capability is not the bottleneck.** Frontier models are already extraordinary in isolation. The bottleneck is *integration* — how a swarm of agents from different labs, companies, and jurisdictions can learn collectively without surrendering accountability.
+- **Connected intelligence has been studied for decades** — social epistemology (Goldman, Longino), collective intelligence (Malone, Woolley), mechanism design (Prelec, Shnayder, Frongillo, Parkes), distributed systems (Tendermint, Sigstore, SCITT). What was missing was a working *substrate*.
+- **Open by default.** Spec, SDK, security reviews, formal-method sketches, failure-mode analysis — all Apache-2.0. The substrate of connected agent intelligence has to be a public good; otherwise the only "swarm" any lab can build is the one inside its own walls.
+
+> *"The swarm gets smarter the moment one agent's mistake can be corrected by another."* — internal ZySec note, January 2026
+
+Open research questions — peer-prediction theory, calibration under adversarial pressure, dispute-FSM completeness, post-quantum agent identity — live in [Discussions](https://github.com/ZySec-AI/hypermind/discussions).
+
+---
+
+## Architecture in 30 seconds
+
+```
+       Your code
+          │
+          ▼
+    HyperMindAgent  ──── publish_claim · consult · synthesize · dispute
+          │                             · task · place_on · mcp_call
+   ┌──────┼──────┬──────────┐
+   ▼      ▼      ▼          ▼
+ wire/  knowledge/  transport/       mcp/
+ COSE   reputation  • InProcessBus   • JSON-RPC 2.0 stdio/WebSocket
+ CBOR   transparency  • TCPGossipBus   • MCP_PROVENANCE header binding
+ A-ALG-               • libp2p (v0.2)  • TaskGateway + idempotent retry
+ BOUND                 • placement      tasks/
+                       • backpressure   • distributed task coordination
+   │
+   ▼
+ crypto/
+ Ed25519 · ML-DSA-65 hybrid · FROST · BLAKE3 · HLC
+```
+
+Drilldown: [docs/concepts.md](docs/concepts.md) ·
+Spec: [docs/spec/](docs/spec/) ·
+Standards inheritance: [docs/_meta/standards-map.md](docs/_meta/standards-map.md)
+
+---
+
+## Getting started
+
+### 5-minute path
+1. **Install:** `pip install hypermind` (Python 3.11–3.13)
+2. **Run hello-world:** `python -m examples.01_hello_world`
+3. **Read the [getting-started guide](docs/getting-started.md)**
+
+### 30-minute path — the four numbered tutorials, in order
+
+| # | What you'll do | Time |
+|---|---|---|
+| [`01_hello_world.py`](examples/01_hello_world.py) | One agent, one signed claim | 2 min |
+| [`02_two_agents_dispute.py`](examples/02_two_agents_dispute.py) | Add a second agent, file a bonded dispute | 5 min |
+| [`03_consult_panel.py`](examples/03_consult_panel.py) | Query a panel — collective intelligence in action | 5 min |
+| [`04_oracle_resolve.py`](examples/04_oracle_resolve.py) | Close the loop with ground truth — the swarm gets smarter | 5 min |
+
+Then graduate to the [pilot scenarios](examples/) — full multi-agent, multi-topic flows that mirror real adoption stories.
+
+### The flagship simulation — 100 agents, one crisis
+
+```bash
+python -m examples.scenario_geopolitical_crisis --agents 100 --verbose
+```
+
+100 analyst agents (intel agencies, think-tanks, financial firms, NGOs, contrarians, oracles) deployed into a geopolitical crisis. They publish observations, dispute disinformation, run panel consults, and resolve with oracle ground truth — all in under a second, all cryptographically signed. Pass `--audit audit.jsonl` to capture the full tamper-evident log.
+
+```bash
+# Ask custom questions by editing PANEL_QUESTIONS in the scenario file
+# Scale down for development:
+python -m examples.scenario_geopolitical_crisis --agents 20
+# Full run with JSON output piped for downstream processing:
+python -m examples.scenario_geopolitical_crisis --agents 100 | jq .panel_results
+```
+
+See **[docs/simulations.md](docs/simulations.md)** for how to build your own domain simulation.
+
+### When you're stuck
+- `hmctl doctor` — smoke-tests the install + dependencies
+- `hmctl why-blocked <action>` — every refusal carries `rule_id` + `spec_ref`
+- [Discussions](https://github.com/ZySec-AI/hypermind/discussions) — most onboarding questions are already there
+
+---
+
+## Documentation
+
+| You want to… | Go here |
+|---|---|
+| Install and run your first signed claim | **[docs/getting-started.md](docs/getting-started.md)** |
+| Run a 100-agent domain simulation | **[docs/simulations.md](docs/simulations.md)** |
+| Add durable storage, HTTP API, or LLM responders | **[docs/architecture-v0.6.md](docs/architecture-v0.6.md)** |
+| Understand the core concepts | [docs/concepts.md](docs/concepts.md) |
+| Browse runnable examples | [examples/README.md](examples/README.md) |
+| Read the protocol spec (28 normative sections) | [docs/spec/](docs/spec/) |
+| Understand agent-to-agent networking & MCP transport | [docs/spec/01-transport.md](docs/spec/01-transport.md) + [src/hypermind/mcp/](src/hypermind/mcp/) |
+| See the 5-layer cascaded security stack | [docs/spec/21-private-namespaces.md](docs/spec/21-private-namespaces.md) + `/security` in SimLab |
+| Read the IEEE paper draft + patent disclosure | [docs/paper/](docs/paper/) or `/paper` in SimLab |
+| Decide if HyperMind fits your problem | [docs/decide/](docs/decide/) |
+| Operate a deployment | [docs/operate/](docs/operate/) |
+| See the roadmap | [ROADMAP.md](ROADMAP.md) |
+| Contribute | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Report a security issue | [SECURITY.md](SECURITY.md) |
+
+---
+
+## Project status
+
+**v0.10 — coordination engine shipped.** v0.5–v0.10 are all 🟢 code-complete (federation, versioning, trust bundle, crypto hardening, production profile, conformance scaffolding, full mind / swarm-intelligence layer, and coordination engine).
+
+✅ **What works today**
+- Spec — **28 normative sections** (§01–§28) covering protocol, transport mTLS, envelope encryption, namespace identity, capability extensions, workflow (§26), contract-net (§27), and distributed tracing (§28)
+- Reference Python SDK — async-first, fully type-hinted, **1753 tests passing, ≥95% coverage**
+- 20 numbered tutorials (06/07 are v0.7 placeholders) + 20+ scenarios (incl. `scenario_private_namespace`, `scenario_regulated_consortium`)
+- CLI (`hmctl`), hybrid post-quantum signing, FROST k-of-n threshold (RFC 9591)
+- Three cycles of [self-heal security review](tests/test_self_heal_cycle1.py) — including the v0.9.x **5-layer failure-isolation regression** ([test_self_heal_cycle3_cascade_isolate.py](tests/test_self_heal_cycle3_cascade_isolate.py))
+- **Two-impl interop** — independent [`reference_verifier/`](reference_verifier/) re-implements every primitive from spec text, byte-equal CDDL hashes
+- **L2 mTLS profile**, **L3 HPKE envelope encryption**, **L4 namespace lifecycle** (FROST-rooted CREATE / FOUNDING_ATTEST / INVITE / ACCEPT), **L5 ns:/room:/to: caveats + ACL**
+- **MCP transport** (`src/hypermind/mcp/`) — agent-to-agent tool calls via JSON-RPC 2.0 over stdio/WebSocket with `MCP_PROVENANCE` protected-header binding (calling_agent_kid + cap_token_root + request_kid)
+- **TaskGateway** with InProcessGateway + MCPGateway, cancel/timeout, and idempotent retry; distributed task coordination via `src/hypermind/tasks.py`
+- **ConsistentHash placement** (`agent.place_on()` topology hint) and credit-based flow control (TokenBucket backpressure in `transport/bus.py`)
+- **libp2p scaffold** (`transport-rust/` Cargo crate, `hypermind[libp2p]` extra, raise-on-use until v0.2 backend lands)
+- **Workflow primitives** (§26), **contract-net protocol** (§27), **distributed cognitive layer** (§28)
+- **SimLab web UI** at `make run` — Security, Use Cases (125 cases), Namespaces, Docs/Paper/Patent
+
+🛣️ **Roadmap to v1.0 GA** (full plan in [ROADMAP.md](ROADMAP.md)) — engineering is largely done; remaining gates are external:
+IETF I-D submission · IANA early allocation · OpenSSF Sandbox/Incubating · third-party security audit · full Tamarin/ProVerif proofs · ≥2 non-ZySec maintainers · ≥3 pilot MOUs · 7-day chaos-test green run · 30-day side-channel CT.
+
+---
+
+## Testing & quality
+
+```bash
+make test                                                      # 1753 passing, ~80s
+make cov                                                       # ≥95% coverage gate
+.venv/bin/python -m pytest tests/test_two_impl_interop.py      # SDK ↔ verifier interop
+.venv/bin/python -m pytest tests/test_self_heal_cycle1.py \
+                           tests/test_self_heal_cycle2.py \
+                           tests/test_self_heal_cycle3_cascade_isolate.py  # security regressions
+.venv/bin/python -m pytest tests/test_priv_ns_conformance_coverage.py      # C-PRIV-NS-01..18
+```
+
+Covers: real Ed25519 + ML-DSA-65 hybrid signing (with splice-attack rejection), full FROST k-of-n with deterministic nonces, A-ALG-BOUND wire-substitution defences, dispute FSM with partition-heal terminal, capability chain-of-trust with `ns:` namespace caveats, RFC 6962 inclusion proofs, RFC 9180 HPKE round-trip, COSE_Encrypt0 separability invariant, TLS 1.3 mTLS profile (cipher floor, ALPN downgrade-detect, RPK kid binding), and the **5-layer failure-isolation regression** that proves any single layer can be compromised without breaching the other four.
+
+---
+
+## Contributing
+
+We welcome issues, design discussions, and PRs. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for dev setup, commit conventions, and the PR checklist.
+
+- 🐛 Bug? → [open an issue](https://github.com/ZySec-AI/hypermind/issues)
+- 🔒 Security report? → [SECURITY.md](SECURITY.md)
+- 💡 Idea? → [Discussions](https://github.com/ZySec-AI/hypermind/discussions)
+- 🤝 Code? → check `good first issue` and `help wanted` labels
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## License & credits
+
+Apache-2.0 — see [LICENSE](LICENSE).
+
+`hypermind` builds on the IETF [SCITT architecture](https://datatracker.ietf.org/doc/draft-ietf-scitt-architecture/), [LAMPS composite signatures](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/), [RFC 9591 FROST](https://datatracker.ietf.org/doc/html/rfc9591), [RFC 6962 Merkle transparency](https://datatracker.ietf.org/doc/html/rfc6962), and [c2sp.org/tlog-witness](https://github.com/C2SP/C2SP/blob/main/tlog-witness.md).
+
+---
+
+<div align="center">
+
+**HyperMind — the protocol for swarm intelligence between AI agents.**
+
+*Many minds, learning together — across companies, with cryptographic chain of custody.*
+
+[github.com/ZySec-AI/hypermind](https://github.com/ZySec-AI/hypermind)
+
+</div>