hypermind 2.3.0__tar.gz → 2.4.0__tar.gz

{hypermind-2.3.0 → hypermind-2.4.0}/.gitignore

@@ -134,6 +134,9 @@ persona_trace.json
 .mcp.json
 trace.json
 
+# `hmctl show -o` — generated canvas artifact (serve mode writes no files)
+hypermind-network.html
+
 # -----------------------------------------------------------------------------
 # Local runtime data — never commit server state.
 # `.data/` is the canonical docker-compose mount location; `data/` is legacy.

hypermind-2.4.0/.gitleaksignore

@@ -0,0 +1,7 @@
+# Gitleaks false positives — documentation placeholders, not real secrets.
+# The curl-auth-header rule fires on the literal `sk-your-key` placeholder in
+# the deploy troubleshooting docs. Fixed at HEAD (env-var references now);
+# these fingerprints cover the two occurrences in history (commit 6cb2ff1)
+# that the full-history push scan still reports.
+6cb2ff17366b511c3992e9186763817040df7ba3:docs/deploy/troubleshooting.md:curl-auth-header:255
+6cb2ff17366b511c3992e9186763817040df7ba3:docs/deploy/troubleshooting.md:curl-auth-header:259

{hypermind-2.3.0 → hypermind-2.4.0}/CHANGELOG.md

@@ -14,6 +14,85 @@ changes only on major-version bumps.
 
 ## [Unreleased]
 
+## [2.4.0] — 2026-08-24
+
+### Added
+- **`hmctl show` — live network canvas (`hypermind.viz`).** A read-only
+  infinite-canvas dashboard of the swarm: graph (pan/zoom, community halos,
+  per-agent detail drawer), agents table with reputation meters and outcome
+  sparklines, conversation stream, claims, disputes (FSM badges + transition
+  history), research artefacts, and a timeline scrubber that replays how the
+  network evolved. Two modes from one renderer: **serve live** (the new
+  default — `hmctl show` starts a loopback-only HTTP server on
+  `127.0.0.1:8791`, opens the browser, and the page polls a fresh snapshot
+  every `--interval` seconds, re-rendering in place with a live/reconnecting
+  chip) and **static artifact** (`-o file.html` — a fully self-contained
+  page with zero network code, safe to share or archive as audit evidence).
+  Sources, in priority order: `--relata-url` + `--namespace` (live Relata
+  ledger), a `hmctl orgs simulate --export` JSONL bundle (re-read whenever
+  the file changes on disk), `RELATA_URL` from the environment or
+  `~/.hypermind/env` (the hands-free default once `hmctl setup` has run),
+  or `--demo` (a zero-dependency in-process demo swarm). Re-running
+  `hmctl show` while a previous one is serving just re-opens the page.
+  Untrusted text (findings, reasons, statements) reaches the DOM via
+  `textContent` only — never `innerHTML`.
+- **Ledger tenancy onboarding: `hmctl setup` + `hypermind.storage.tenancy`.**
+  Closes the onboarding gap where a fresh Relata deployment + `hmctl mcp
+  install` pointed at a tenant nobody ever created (Relata never auto-creates
+  tenants on first `X-Organization-Id`; the namespace↔tenant mapping is 1:1).
+  New `hypermind.storage.tenancy` module: `ensure_tenant()` (idempotent
+  create; 409 = already exists; 404/501 = server build without a tenant admin
+  API → `X-Organization-Id` label scoping, still supported), `probe_key_role()`
+  (admin / tenant / invalid / unknown), `verify_ledger()` (read-only
+  reachable → tenant → Hm\* types → key check), `bootstrap_ledger()` (ensure
+  tenant + register the four Hm types via the existing #192 provisioning path
+  + verify). New `hmctl setup` command with three paths: **adopt** (deployment
+  already bootstrapped — verify + persist the tenant key), **elevate**
+  (supply an admin key once: create tenant, register types, then persist the
+  daily key), **local** (`--local`: SQLite ledger, zero network). Everything
+  is idempotent.
+- **Admin/master key handling contract (`hmctl setup`).** The admin key is
+  never read from the environment — `--admin-key` flag or hidden prompt only,
+  held in memory for exactly the privileged calls, and never persisted. A
+  master key handed in as `--key` is probed on the server, detected, warned
+  about, rerouted to the bootstrap path, and *not* written to
+  `~/.hypermind/env` unless the operator explicitly consents
+  (`--allow-admin-key`). Keys are echoed as SHA-256 fingerprints only, never
+  in full.
+- **`hmctl mcp serve --namespace`** — binds the swarm and the Relata tool
+  provider to one ledger tenant (they are 1:1). Also read from
+  `HYPERMIND_RELATA_NAMESPACE` (which `hmctl setup` writes) and from the
+  `namespace` key of the TOML config. The startup banner now shows the
+  active tenant.
+- **`hmctl mcp install` harvests ledger tenancy.** `RELATA_TOKEN` and
+  `HYPERMIND_RELATA_NAMESPACE` join the auto-harvested env vars, sourced from
+  the current shell first and `~/.hypermind/env` second — the tenant + token
+  `hmctl setup` chose now reach host-launched MCP servers, which start with a
+  blank environment.
+- **`hmctl doctor` ledger checks.** When `RELATA_URL` is configured, doctor
+  verifies the chain `hmctl setup` establishes — server reachable → tenant →
+  Hm\* types registered → `RELATA_TOKEN` accepted — with fix hints pointing
+  at `hmctl setup`. Unset `RELATA_URL` reports "local mode" instead.
+- **`hmctl/envfile.py`** — merge-preserving writer for `~/.hypermind/env`
+  (always mode 0600; unknown keys, comments, and ordering survive rewrites).
+  `hmctl config` now uses it, so keys written by `hmctl setup` (or by hand)
+  are no longer clobbered when the wizard re-saves; the wizard also prompts
+  for `RELATA_TOKEN` / `HYPERMIND_RELATA_NAMESPACE` and displays them in its
+  status table.
+
+### Fixed
+- **`RelataBackend` reads survive real-server row quirks** (found by live
+  validation against a fresh Relata deployment, 2026-08-24):
+  `load_claims()` no longer crashes with `KeyError('wire_b64')` on the
+  internal `_sentinel` objects server builds keep in the `HmClaim` table —
+  every restore path (`attach_storage()`, `hmctl show --relata-url`,
+  `from_relata()`) was affected. The claim, stub, dispute, and reputation
+  loaders now `SELECT *` and project client-side: some Relata builds
+  intermittently return a tiny subset of rows (or none) for multi-column
+  projections while `SELECT *` returns them all, which silently dropped
+  disputes and, on some calls, every claim from ledger-sourced snapshots.
+  Regression-pinned in `tests/test_storage_relata_sentinels.py`.
+
 ## [2.3.0] — 2026-07-31
 
 Bundles the four epics from the "swarm can research a topic end-to-end"

{hypermind-2.3.0 → hypermind-2.4.0}/CLAUDE.md

@@ -139,7 +139,7 @@ The living-simulation + research engine (spec: `docs/spec/20-swarm-intelligence.
 - `replay.py` — `export_jsonl` dumps every record (signed claims as wire bytes + disputes/reputation/evidence/hypotheses); `replay_to_relata` re-inserts a run **without re-running the LLM work**.
 - `sim.stream()` / `select_experts()` — streaming **tools-off** query over learned knowledge; consults a panel ranked by `hits × (1 + 0.7×rep + 0.3×fact_richness)`; `model=`/`client=` enable **learn-large / serve-small**. `_fact_richness()` is a log-damped ratio of confirmed/total facts for the expert's topic.
 - `tool_providers.py` / `mcp_config.py` — per-cycle tool gateway + MCP auto-discovery. `distributed/` — TCP master/worker for horizontal scale. `templates/` — preset org factories.
-- **Storage**: real `RelataBackend` (typed HmClaim/HmDispute/HmReputation) + `RelataMemoryStore` (evidence + hypotheses). Provision the Hm types once (admin token) — see `deploy/relata-serve.sh`. Multi-node federation is real over `transport/tcp.py::TCPGossipBus`.
+- **Storage**: real `RelataBackend` (typed HmClaim/HmDispute/HmReputation) + `RelataMemoryStore` (evidence + hypotheses). Provision the tenant + Hm types once via `hmctl setup` (admin key is prompted, never env-read — see `storage/tenancy.py`); `deploy/relata-serve.sh` / hypermind-deploy's `scripts/bootstrap-ledger.sh` do the same for scripted deployments. Multi-node federation is real over `transport/tcp.py::TCPGossipBus`.
 
 ### Other production modules
 
@@ -250,9 +250,9 @@ When changing a public verb, check that every example in `examples/` still runs
 
 ## Active milestone
 
-As of 2026-07-31, the SDK is at **2.3.0** on the **engineering GA** line (engineering GA shipped 2026-07-09 as 1.0.0; SemVer is binding). The protocol core, the full swarm-intelligence / mind layer, the `hypermind.orgs` deep-research engine (decomposition + self-refine, reasoning strategies + structured outcome parsing, hypothesis lifecycle with prediction-matching, architecture-native metrics, evidence retention + citations, cross-sim learned-fit persistence via KernelStore, streaming query, full-run replay, real Relata ledger + TCP federation, PDF/site-crawl discovery + RelataDB `document_ingest` alignment, goal-driven charter-decomposed swarms), and the independent Rust second-language port (`rust/`) have all landed. Remaining gates are **ecosystem, not code** — IETF I-D submission, IANA early-allocation, OpenSSF Sandbox/Incubating acceptance, third-party security audit, full Tamarin/ProVerif proofs, NLnet/Alpha-Omega awards, ≥2 non-ZySec maintainers, ≥3 pilot MOUs, 7-day chaos-test green run, side-channel CT 30d-green. See [`docs/project/roadmap.md`](docs/project/roadmap.md) for item-numbered status.
+As of 2026-08-24, the SDK is at **2.4.0** on the **engineering GA** line (engineering GA shipped 2026-07-09 as 1.0.0; SemVer is binding). The protocol core, the full swarm-intelligence / mind layer, the `hypermind.orgs` deep-research engine (decomposition + self-refine, reasoning strategies + structured outcome parsing, hypothesis lifecycle with prediction-matching, architecture-native metrics, evidence retention + citations, cross-sim learned-fit persistence via KernelStore, streaming query, full-run replay, real Relata ledger + TCP federation, PDF/site-crawl discovery + RelataDB `document_ingest` alignment, goal-driven charter-decomposed swarms), and the independent Rust second-language port (`rust/`) have all landed. Remaining gates are **ecosystem, not code** — IETF I-D submission, IANA early-allocation, OpenSSF Sandbox/Incubating acceptance, third-party security audit, full Tamarin/ProVerif proofs, NLnet/Alpha-Omega awards, ≥2 non-ZySec maintainers, ≥3 pilot MOUs, 7-day chaos-test green run, side-channel CT 30d-green. See [`docs/project/roadmap.md`](docs/project/roadmap.md) for item-numbered status.
 
-> **Recent releases.** v2.0.0 (SemVer-major consolidation: wire-version 3 supported, deprecated-API removal, libp2p first-class transport binding, TAL v0.2 wire messages, Sealed/Citeable lattice, second-language port in progress). v2.1.0–v2.1.5 (2026-07-27): Rust port landed (`rust/`), L1–L5 autonomy stack, FTS5 storage, MoA endpoint, IEEE-defensible eval benchmark, dark-theme HTML report. v2.2.0 (2026-07-28): autonomy pass (#983) — SSRF redirect/hostname hardening, deployment `profiles`, `coevolution`, `silent_failures`/`health`, `reputation_store`, `CachingResponder`/`DifficultyRouter`, hybrid SQLite search, active grounding gates (defaults changed, API-compatible). v2.2.1 (2026-07-29): CAP_REVOKE gossip + canonical-CBOR gate (#943 P1), TAL v0.2 signed wire messages (#943 P2), bi-temporal recall + cross-namespace Merkle citation proofs (#942), streamable-HTTP MCP gateway (#1013). v2.3.0 (2026-07-31): PDF/site-crawl discovery (#1018), RelataDB `document_ingest` alignment (#1019), goal-driven charter swarms (#1020), intra-expert research probe gate (#1021). The 2026-07-25 security-hardening fixes (issues #839-#844) shipped in 2.0 Phase 0. See [`CHANGELOG.md`](CHANGELOG.md) and [`docs/project/v2.0-plan.md`](docs/project/v2.0-plan.md).
+> **Recent releases.** v2.0.0 (SemVer-major consolidation: wire-version 3 supported, deprecated-API removal, libp2p first-class transport binding, TAL v0.2 wire messages, Sealed/Citeable lattice, second-language port in progress). v2.1.0–v2.1.5 (2026-07-27): Rust port landed (`rust/`), L1–L5 autonomy stack, FTS5 storage, MoA endpoint, IEEE-defensible eval benchmark, dark-theme HTML report. v2.2.0 (2026-07-28): autonomy pass (#983) — SSRF redirect/hostname hardening, deployment `profiles`, `coevolution`, `silent_failures`/`health`, `reputation_store`, `CachingResponder`/`DifficultyRouter`, hybrid SQLite search, active grounding gates (defaults changed, API-compatible). v2.2.1 (2026-07-29): CAP_REVOKE gossip + canonical-CBOR gate (#943 P1), TAL v0.2 signed wire messages (#943 P2), bi-temporal recall + cross-namespace Merkle citation proofs (#942), streamable-HTTP MCP gateway (#1013). v2.3.0 (2026-07-31): PDF/site-crawl discovery (#1018), RelataDB `document_ingest` alignment (#1019), goal-driven charter swarms (#1020), intra-expert research probe gate (#1021). v2.4.0 (2026-08-24): `hmctl show` live network canvas (`hypermind.viz`), ledger tenancy onboarding (`hmctl setup` + `hypermind.storage.tenancy`), admin-key handling contract, `mcp serve --namespace`, doctor ledger checks, live-validated Relata read fixes (sentinel rows, projection quirk). The 2026-07-25 security-hardening fixes (issues #839-#844) shipped in 2.0 Phase 0. See [`CHANGELOG.md`](CHANGELOG.md) and [`docs/project/v2.0-plan.md`](docs/project/v2.0-plan.md).
 
 > **Note on doc locations (2026-07-25):** `CHARTER.md`, `GOVERNANCE.md`, `MAINTAINERS.md`, `ROADMAP.md`, and `REPO_MAP.md` were moved from the repo root into [`docs/project/`](docs/project/) (renamed lowercase). Root retains only the GitHub platform files (`README`, `LICENSE`, `SECURITY`, `CODE_OF_CONDUCT`, `CONTRIBUTING`, `CHANGELOG`, `CODEOWNERS`) plus `CLAUDE.md`. See [`docs/INDEX.md`](docs/INDEX.md) for the full doc map.
 

{hypermind-2.3.0 → hypermind-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hypermind
-Version: 2.3.0
+Version: 2.4.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
@@ -91,7 +91,7 @@ Agents share what they learn, dispute what they doubt, and build reputation over
 [![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-5093-brightgreen)](#status)
-[![Version](https://img.shields.io/badge/version-2.3.0-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.4.0-blue)](CHANGELOG.md)
 
 **[Quickstart](#quickstart-30-seconds)** ·
 **[MCP tools](#mcp-tools-63-tools)** ·
@@ -128,6 +128,7 @@ hits = await hm.retrieve("key size", min_trust=0.6)                 # → trust-
 ```bash
 hmctl mcp install          # auto-wires the host (read-only by default; --write to publish)
 hmctl mcp install --local  # fully offline: Ollama auto-detect + SQLite ledger, no API key
+hmctl setup                # using a Relata ledger? one command: tenant + types + key, verified
 ```
 
 Then just talk naturally — *"What does the swarm know about CRISPR off-target effects?"*,
@@ -337,6 +338,7 @@ hmctl ingest notes.md --topic research # ingest documents into the swarm
 hmctl dataset export --format dpo --out dpo.jsonl   # export fine-tuning dataset
 hmctl population create my-lab --template research_lab --size 5
 hmctl eval                             # run the calibration metric suite
+hmctl show                             # live network canvas (serve + auto-open; -o out.html for a static artifact)
 hmctl orgs simulate --template university --topic "…" --rounds 6 --live
 hmctl doctor                           # smoke-test the install
 ```
@@ -378,7 +380,7 @@ hmctl mcp install # wires Claude Desktop/Cursor + auto-adds fetch/Serper/SearchA
 
 ## Status
 
-**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **2.3.0** (2026-07-31).
+**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **2.4.0** (2026-08-24).
 Remaining gates are **ecosystem, not code** (see [roadmap](docs/project/roadmap.md) §External).
 
 - **Protocol** — 33 numbered spec sections (§00–§32) + independent [`reference_verifier/`](reference_verifier/) proving two-impl interop + second-language [`rust/`](rust/) port (v2.1.0)

{hypermind-2.3.0 → hypermind-2.4.0}/README.md

@@ -13,7 +13,7 @@ Agents share what they learn, dispute what they doubt, and build reputation over
 [![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-5093-brightgreen)](#status)
-[![Version](https://img.shields.io/badge/version-2.3.0-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.4.0-blue)](CHANGELOG.md)
 
 **[Quickstart](#quickstart-30-seconds)** ·
 **[MCP tools](#mcp-tools-63-tools)** ·
@@ -50,6 +50,7 @@ hits = await hm.retrieve("key size", min_trust=0.6)                 # → trust-
 ```bash
 hmctl mcp install          # auto-wires the host (read-only by default; --write to publish)
 hmctl mcp install --local  # fully offline: Ollama auto-detect + SQLite ledger, no API key
+hmctl setup                # using a Relata ledger? one command: tenant + types + key, verified
 ```
 
 Then just talk naturally — *"What does the swarm know about CRISPR off-target effects?"*,
@@ -259,6 +260,7 @@ hmctl ingest notes.md --topic research # ingest documents into the swarm
 hmctl dataset export --format dpo --out dpo.jsonl   # export fine-tuning dataset
 hmctl population create my-lab --template research_lab --size 5
 hmctl eval                             # run the calibration metric suite
+hmctl show                             # live network canvas (serve + auto-open; -o out.html for a static artifact)
 hmctl orgs simulate --template university --topic "…" --rounds 6 --live
 hmctl doctor                           # smoke-test the install
 ```
@@ -300,7 +302,7 @@ hmctl mcp install # wires Claude Desktop/Cursor + auto-adds fetch/Serper/SearchA
 
 ## Status
 
-**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **2.3.0** (2026-07-31).
+**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **2.4.0** (2026-08-24).
 Remaining gates are **ecosystem, not code** (see [roadmap](docs/project/roadmap.md) §External).
 
 - **Protocol** — 33 numbered spec sections (§00–§32) + independent [`reference_verifier/`](reference_verifier/) proving two-impl interop + second-language [`rust/`](rust/) port (v2.1.0)

{hypermind-2.3.0 → hypermind-2.4.0}/docs/configuration.md

@@ -18,6 +18,53 @@ tuning knob in a formatted table.
 
 ---
 
+## Ledger onboarding (`hmctl setup`)
+
+When `RELATA_URL` points at a Relata deployment, claims live in a **tenant**
+— the Relata tenant the HyperMind namespace maps to, 1:1 (`HYPERMIND_RELATA_NAMESPACE`).
+Relata does not auto-create tenants, so a fresh deployment needs one round of
+onboarding before the SDK can persist anything:
+
+```bash
+hmctl setup                       # interactive: url, tenant, keys — verifies as it goes
+hmctl setup --admin-key … --key … # non-interactive elevate + adopt
+hmctl setup --local               # no Relata: SQLite ledger, zero network
+```
+
+Everything `hmctl setup` does is idempotent — re-running against a
+bootstrapped server is a no-op re-verify. Docker deployments bootstrapped by
+[hypermind-deploy](https://github.com/ZySec-AI/hypermind-deploy)'s
+`start.sh` only need the **adopt** path (verify + persist the tenant key).
+
+**Key model (security-relevant):**
+
+| Key | Scope | Where it lives |
+|---|---|---|
+| tenant / daily key | read + write on one tenant's data | `RELATA_TOKEN` in `~/.hypermind/env` |
+| admin / master key | tenant creation, type registration | **nowhere** — prompted or `--admin-key`, used once in memory |
+
+The admin key is never read from the environment and never persisted by the
+SDK. If a master key is passed as the daily key (`--key`), `hmctl setup`
+probes its actual role on the server, warns that it is over-privileged,
+uses it ephemerally for bootstrap, and refuses to persist it without
+explicit consent (`--allow-admin-key`). Keys are displayed as SHA-256
+fingerprints only.
+
+`hmctl doctor` re-checks the chain on every run: server reachable → tenant →
+Hm\* types registered → token accepted, with fix hints pointing back at
+`hmctl setup`.
+
+**Tenant data isolation is a server-side guarantee.** The SDK sends
+`X-Organization-Id` on every request and namespace-filters reputation rows it
+reads, but query-result scoping is enforced by Relata, not the client. On the
+free Relata profile (verified live 2026-08-24) all tenants' rows are returned
+to every tenant — onboarding still works, but tenants on such a build share
+one data plane. Enforce isolation at the Relata tier (licensed profile or a
+Relata build with row-level org scoping) before relying on it for
+multi-tenant deployments.
+
+---
+
 ## LLM / Responder
 
 | Variable | Default | Description |
@@ -46,7 +93,7 @@ tuning knob in a formatted table.
 | `RELATA_BEARER_TOKEN` | *(none)* | Bearer token for authenticating requests to RelataDB. Also accepted as `RELATA_TOKEN`. Required when the RelataDB instance is protected by token auth (e.g. managed cloud deployments). Source: `src/hypermind/integrations/client.py`. |
 | `RELATA_TOKEN` | *(none)* | Alias for `RELATA_BEARER_TOKEN` (checked as fallback). |
 | `RELATA_MCP_PURPOSE` | `intops` | Purpose tag stamped on claims written through the MCP server. Legacy alias `RELATA_PURPOSE` is also accepted. Source: `src/hypermind/config.py`. |
-| `HYPERMIND_RELATA_NAMESPACE` | `hypermind` | Relata tenant namespace shared across SDK paths (client, OrgSim, MCP server). Per-org namespaces are sub-scoped as `<tenant>:<org>` inside this tenant. Source: `src/hypermind/config.py`. |
+| `HYPERMIND_RELATA_NAMESPACE` | `hypermind` | Relata tenant namespace shared across SDK paths (client, OrgSim, `mcp serve`). Per-org namespaces are sub-scoped as `<tenant>:<org>` inside this tenant. Written by `hmctl setup`; `hmctl mcp serve --namespace` overrides per-launch. Source: `src/hypermind/config.py`. |
 | `HYPERMIND_DB` | `~/.hypermind/cache.db` | Path to the local SQLite cache database. Auto-activated when `RELATA_URL` is not set. Persists claims, agent state, and hypothesis records across restarts. |
 | `HYPERMIND_STORAGE` | *(auto)* | Force a storage backend: `relata` or `sqlite`. When unset the SDK selects `relata` if `RELATA_URL` is present, otherwise `sqlite`. Source: `src/hypermind/storage/__init__.py`. |
 | `HYPERMIND_NAMESPACE` | *(sandbox default)* | Default namespace ID used when creating the storage backend. Source: `src/hypermind/storage/__init__.py`. |
@@ -443,7 +490,8 @@ The `hm-moa` model on the OpenAI-compatible endpoint is configured via the `HYPE
 ## See also
 
 - `hmctl env-vars` — print a live table of all tuning knobs with current values
-- `hmctl doctor` — health-check that reports `HYPERMIND_SSE_PORT`, `HYPERMIND_WEBHOOK_PORT`, and `HYPERMIND_WEBHOOK_SECRET` status
+- `hmctl setup` — one-command ledger onboarding: ensure tenant, register Hm\* types, verify, persist the daily key
+- `hmctl doctor` — health-check that reports `HYPERMIND_SSE_PORT`, `HYPERMIND_WEBHOOK_PORT`, `HYPERMIND_WEBHOOK_SECRET`, and (when `RELATA_URL` is set) the ledger tenant/types/token chain
 - `hmctl config` — interactive wizard for setting the most common variables
 - `hmctl status` — shows LLM, Relata, web search backend, MCP servers, and what to fix
 - [docs/integrations.md](integrations.md) — integration guide and advanced tuning knobs

{hypermind-2.3.0 → hypermind-2.4.0}/docs/deploy/add-tool-provider.md

@@ -546,7 +546,7 @@ def handler(args: dict) -> str:
 
 **Set in `.env`:**
 ```
-MY_API_KEY=sk-your-key-here
+MY_API_KEY=<your-provider-key>
 ```
 
 ---

{hypermind-2.3.0 → hypermind-2.4.0}/docs/deploy/quickstart.md

@@ -49,7 +49,7 @@ The script will:
 HyperMind setup — press Enter to keep the shown default.
 
   RELATA_TOKEN (data-store auth) [existing-token-or-generated]: 
-  OPENAI_API_KEY [keep existing]: sk-your-key-here
+  OPENAI_API_KEY [keep existing]: <your-openai-key>
   OPENAI_BASE_URL [https://api.minimax.io/v1]: 
   HYPERMIND_LLM_MODEL [MiniMax-M3]: 
 

{hypermind-2.3.0 → hypermind-2.4.0}/docs/deploy/troubleshooting.md

@@ -251,13 +251,13 @@ Examples:
 
 **Step 4: Test provider is reachable**
 ```bash
-# From host
+# From host (exports your real key first: export OPENAI_API_KEY=...)
 curl https://api.openai.com/v1/models \
-  -H "Authorization: Bearer sk-your-key"
+  -H "Authorization: Bearer $OPENAI_API_KEY"
 
-# From inside container
+# From inside container (reads the key the container already has)
 docker exec hm-engine curl https://api.openai.com/v1/models \
-  -H "Authorization: Bearer sk-your-key"
+  -H "Authorization: Bearer \$OPENAI_API_KEY"
 ```
 
 If connection failed: Check firewall/proxy.

{hypermind-2.3.0 → hypermind-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "2.3.0"
+version = "2.4.0"
 description = "Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile"
 readme = "README.md"
 requires-python = ">=3.12,<3.15"

{hypermind-2.3.0 → hypermind-2.4.0}/src/hmctl/cli.py

@@ -55,6 +55,7 @@ def main() -> None:
       hmctl mcp install         wire into Claude Desktop / Cursor
       hmctl status              health-check your installation
       hmctl doctor              smoke-test SDK invariants
+      hmctl show                agents/comms/reputation as a canvas map
     """
 
 
@@ -68,6 +69,17 @@ from hmctl.eval_cmd import eval_group as _eval_group
 
 main.add_command(_eval_group, name="eval")
 
+# `hmctl show` — read-only infinite-canvas map of agents/communications/
+# reputation/communities, with a timeline scrubber.
+from hmctl.show_cmd import show_cmd as _show_cmd
+
+main.add_command(_show_cmd, name="show")
+
+# `hmctl setup` — one-command ledger onboarding (tenant + types + key → env).
+from hmctl.setup_cmd import setup_cmd as _setup_cmd
+
+main.add_command(_setup_cmd, name="setup")
+
 
 @main.command()
 @click.option(
@@ -348,6 +360,64 @@ def doctor(check_clock: bool, strict_pq: bool) -> None:
                 "HMAC verification in production."
             )
 
+    # (4) Ledger tenancy — when a Relata deployment is configured, verify the
+    # tenant/key/types chain `hmctl setup` establishes. Bounded timeout so
+    # doctor stays fast against a down server.
+    try:
+        from hmctl.envfile import read_env_file
+
+        _file_env = read_env_file()
+    except Exception:
+        _file_env = {}
+    _ledger_url = _os_doctor.environ.get("RELATA_URL") or _file_env.get("RELATA_URL") or ""
+    if _ledger_url:
+        from hypermind.storage.tenancy import verify_ledger
+
+        _ledger_tenant = (
+            _os_doctor.environ.get("HYPERMIND_RELATA_NAMESPACE")
+            or _file_env.get("HYPERMIND_RELATA_NAMESPACE")
+            or "hypermind"
+        )
+        _ledger_token = _os_doctor.environ.get("RELATA_TOKEN") or _file_env.get("RELATA_TOKEN")
+        _led = verify_ledger(
+            _ledger_url,
+            tenant=_ledger_tenant,
+            token=_ledger_token,
+            expect_types=("HmClaim", "HmDispute", "HmReputation", "HmTranscript"),
+            timeout_s=2.0,
+        )
+        if not _led.reachable:
+            click.echo(f"[doctor] ledger ~ {_ledger_url} unreachable (skipping tenant checks)")
+            _warnings.append(
+                f"RELATA_URL is set but {_ledger_url} did not answer /health — "
+                "claims will not persist to the ledger."
+            )
+        else:
+            _missing = [t for t, s in _led.types.items() if s not in ("registered", "exists")]
+            if _led.key_role == "invalid":
+                click.echo(
+                    f"[doctor] ledger ~ {_ledger_url} reachable, but RELATA_TOKEN was rejected"
+                )
+                _warnings.append(
+                    "RELATA_TOKEN rejected by the ledger — re-run `hmctl setup` with a valid key."
+                )
+            elif _missing:
+                click.echo(
+                    f"[doctor] ledger ~ {_ledger_url} reachable, types missing: "
+                    f"{', '.join(_missing)}"
+                )
+                _warnings.append(
+                    f"Ledger types not registered ({', '.join(_missing)}) — run "
+                    "`hmctl setup --admin-key …` to provision them."
+                )
+            else:
+                click.echo(
+                    f"[doctor] ledger ✓ {_ledger_url} · tenant '{_ledger_tenant}' · "
+                    f"key {_led.key_role} ({_led.key_fingerprint}) · types registered"
+                )
+    else:
+        click.echo("[doctor] ledger ~ not configured (local mode — see `hmctl setup --local`)")
+
     for _msg in _warnings:
         click.echo(f"[doctor] warn   {_msg}", err=True)
     for _msg in _errors:
@@ -2235,6 +2305,16 @@ def config_cmd(non_interactive: bool) -> None:
         existing.get("RELATA_URL", "[dim]not set[/]"),
         "✓" if existing.get("RELATA_URL") else "~",
     )
+    table.add_row(
+        "RELATA_TOKEN",
+        "***" if existing.get("RELATA_TOKEN") else "[dim]not set[/]",
+        "✓" if existing.get("RELATA_TOKEN") else "~",
+    )
+    table.add_row(
+        "HYPERMIND_RELATA_NAMESPACE",
+        existing.get("HYPERMIND_RELATA_NAMESPACE", "[dim]hypermind (default)[/]"),
+        "✓" if existing.get("HYPERMIND_RELATA_NAMESPACE") else "~",
+    )
     table.add_row(
         "HYPERMIND_DB", existing.get("HYPERMIND_DB", f"[dim]auto ({_HM_HOME}/cache.db)[/]"), "✓"
     )
@@ -2290,6 +2370,12 @@ def config_cmd(non_interactive: bool) -> None:
         "RELATA_URL",
         "e.g. http://localhost:5432 or https://your-tenant.relatadb.dev",
     )
+    prompt_field(
+        "Tenant key", "RELATA_TOKEN", "prefer `hmctl setup` — it verifies first", secret=True
+    )
+    prompt_field(
+        "Tenant / namespace", "HYPERMIND_RELATA_NAMESPACE", "the Relata tenant claims write to"
+    )
     console.print()
 
     console.print("[bold]SQLite local cache[/]")
@@ -2305,25 +2391,11 @@ def config_cmd(non_interactive: bool) -> None:
         console.print("[dim]No changes.[/]")
         return
 
-    # Write env file
-    lines = ["# HyperMind configuration — managed by hmctl config\n"]
-    sections = {
-        "LLM": ["OPENAI_API_KEY", "OPENAI_BASE_URL", "HYPERMIND_LLM_MODEL", "ANTHROPIC_API_KEY"],
-        "RelataDB": ["RELATA_URL"],
-        "SQLite": ["HYPERMIND_DB"],
-        "Observability": ["OTEL_EXPORTER_OTLP_ENDPOINT"],
-    }
-    for section, keys in sections.items():
-        written = False
-        for k in keys:
-            if updates.get(k):
-                if not written:
-                    lines.append(f"\n# {section}\n")
-                    written = True
-                lines.append(f"{k}={updates[k]}\n")
-
-    with open(env_file, "w") as f:
-        f.writelines(lines)
+    # Write env file — merge-preserving: keys this wizard doesn't know about
+    # (e.g. those written by `hmctl setup`, or hand-added) survive the rewrite.
+    from hmctl.envfile import update_env_file
+
+    update_env_file({k: v for k, v in updates.items() if v}, path=env_file)
 
     console.print(f"[green]✓[/] Saved to {env_file}")
     console.print("\n[bold]Restart the MCP server to apply changes:[/]")
@@ -3215,6 +3287,17 @@ main.add_command(mcp_group, name="mcp")
     default=False,
     help="Derive the --sign-as seed from this machine's hardware id (deterministic across restarts).",
 )
+@click.option(
+    "--namespace",
+    "namespace",
+    envvar="HYPERMIND_RELATA_NAMESPACE",
+    default=None,
+    help=(
+        "Ledger tenant / HyperMind namespace for both the client and the Relata "
+        "tool provider (they are 1:1). Defaults to 'integrations' when unset; "
+        "`hmctl setup` writes this env var. [env: HYPERMIND_RELATA_NAMESPACE]"
+    ),
+)
 @click.option(
     "--log-level",
     "log_level",
@@ -3230,6 +3313,7 @@ def mcp_serve_cmd(
     writable: bool,
     sign_as_path: str | None,
     machine_identity: bool,
+    namespace: str | None,
     sse_port: int | None,
     tcp_port: int | None,
     ws_port: int | None,
@@ -3243,6 +3327,8 @@ def mcp_serve_cmd(
     Pass --sign-as PATH to attribute every call to a named, revocable identity.
     Pass --log-level info (or debug/warning/error) to stream logs to stderr.
     Pass --config /path/to/mcp.toml to load all options from a TOML file (CLI flags override).
+    Pass --namespace (or set HYPERMIND_RELATA_NAMESPACE, written by `hmctl setup`)
+    to bind the swarm and the Relata tool provider to one ledger tenant.
     """
     # Load TOML config file; CLI flags always win (ParameterSource.DEFAULT check).
     if config_path:
@@ -3269,6 +3355,8 @@ def mcp_serve_cmd(
             sign_as_path = str(_cfg["sign_as"])
         if "machine_identity" in _cfg and _src("machine_identity") == ParameterSource.DEFAULT:
             machine_identity = bool(_cfg["machine_identity"])
+        if "namespace" in _cfg and _src("namespace") == ParameterSource.DEFAULT:
+            namespace = str(_cfg["namespace"])
         if "log_level" in _cfg and _src("log_level") == ParameterSource.DEFAULT:
             log_level = str(_cfg["log_level"])
 
@@ -3541,7 +3629,11 @@ def mcp_serve_cmd(
                     )
 
         server, client = build_mcp_server(
-            swarm=swarm, writable=writable, sign_as=sign_as, responder=responder
+            swarm=swarm,
+            writable=writable,
+            sign_as=sign_as,
+            responder=responder,
+            **({"namespace": namespace} if namespace else {}),
         )
 
         # Resolve TCP port BEFORE the banner so the banner shows the actual port.
@@ -3579,6 +3671,7 @@ def mcp_serve_cmd(
             f"  config  {'✓ ' + str(_HM_HOME) + '/env' if has_env_file else f'✗ not found  →  touch {_HM_HOME}/env  (KEY=VALUE, one per line)'}",
             f"  otel    {'✓ ' + otel_ep if otel_ep else '✗ off  →  set OTEL_EXPORTER_OTLP_ENDPOINT'}",
             f"  relata  {'✓ ' + relata if relata else '✗ off  →  get Relata at relatadb.dev or: docker pull openworkbench/relata-db:latest'}",
+            f"  tenant  {namespace or 'integrations'}  (namespace ↔ Relata tenant; hmctl setup to change)",
         ]
 
         # web_search row — show active backend + tool count wired into hm_ask
@@ -3891,16 +3984,28 @@ def mcp_install_cmd(
     # Gap #5: Claude Desktop / Cursor launches hmctl in a blank env — shell API keys
     # are invisible to the host.  Auto-harvest known LLM keys from the current
     # shell into the mcp.json entry so the host always sees them.
+    # Ledger tenancy joins the harvest: the tenant + token `hmctl setup` chose
+    # must reach the host-launched server, or MCP writes to the wrong tenant.
+    # Source precedence: current shell first, then ~/.hypermind/env (setup's
+    # persistence target) — the shell never gets shadowed by a stale file.
     _KEY_VARS = [
         "OPENAI_API_KEY",
         "ANTHROPIC_API_KEY",
         "OPENAI_BASE_URL",
         "HYPERMIND_LLM_MODEL",
         "RELATA_URL",
+        "RELATA_TOKEN",
+        "HYPERMIND_RELATA_NAMESPACE",
         "HYPERMIND_DB",
     ]
+    try:
+        from hmctl.envfile import read_env_file
+
+        _file_env = read_env_file()
+    except Exception:
+        _file_env = {}
     for _kv in _KEY_VARS:
-        _val = os.environ.get(_kv)
+        _val = os.environ.get(_kv) or _file_env.get(_kv)
         if _val and _kv not in merged_env:
             merged_env[_kv] = _val