hypermind 2.3.0__tar.gz → 2.4.1__tar.gz

{hypermind-2.3.0 → hypermind-2.4.1}/.github/workflows/release.yml

@@ -40,6 +40,9 @@ jobs:
     name: test (py${{ matrix.python }})
     needs: guard-source-branch
     runs-on: ubuntu-latest
+    # A wedged self-hosted runner would otherwise sit on the 360-min default
+    # (observed 2026-08-24: run tests step stalled 24+ min vs ~6 min baseline).
+    timeout-minutes: 25
     strategy:
       fail-fast: false
       matrix:
@@ -59,6 +62,7 @@ jobs:
   build:
     name: build sdist + wheel
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     needs: test
     outputs:
       hashes: ${{ steps.hash.outputs.hashes }}
@@ -159,6 +163,7 @@ jobs:
   publish-pypi:
     name: publish → PyPI
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     needs: build
     if: startsWith(github.ref, 'refs/tags/v')
     environment:
@@ -232,6 +237,7 @@ jobs:
   docker:
     name: docker — hub.docker.com/openworkbench/hypermind
     runs-on: ubuntu-latest
+    timeout-minutes: 45  # multi-arch (amd64+arm64) QEMU build; observed ~95s warm, ~15 min cold
     needs: build
     if: startsWith(github.ref, 'refs/tags/v')
     permissions:

{hypermind-2.3.0 → hypermind-2.4.1}/.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.1/.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.1}/CHANGELOG.md

@@ -14,6 +14,129 @@ changes only on major-version bumps.
 
 ## [Unreleased]
 
+(nothing yet)
+
+## [2.4.1] — 2026-08-24
+
+### Fixed
+- **Relata read path broken by relata-db ≥2026-08-10 builds (`AS OF CURRENT`).**
+  Every `RelataBackend` read (`load_claims`, `load_claim_stubs`, head-seq,
+  recent-findings) carried a bi-temporal `AS OF CURRENT` clause; on the
+  2026-08-10 server build that filter reduces `HmClaim` queries to the
+  table's internal sentinel rows only (live-validated 2026-08-24: 1
+  sentinel row returned vs 411 claims without the clause), so every
+  Relata-backed read — restore-on-startup, `hmctl show --relata-url`,
+  replay — silently came back empty. A plain `SELECT` is already
+  current-state semantics and works on every build; the clause is removed
+  from all four read sites.
+- **`from_relata()` node labels.** DB-sourced canvases showed bare hex ids;
+  the per-author label is now harvested from the GAP-R10 claim stubs
+  alongside unit/role.
+- **`hmctl show` community/unit mapping (org structure was invisible).**
+  Communities detected from cite/vouch affinity were labelled anonymously
+  ("community 1/2/…") and org structure (e.g. a university template's
+  departments) leaked into the *topic* filter instead. The canvas now:
+  - names each community after its members' dominant `unit` (nodes carry
+    `community`; `meta.communities` lists them; clusters with no unit info
+    keep the stable generic label);
+  - ships a dedicated **community filter** (`#hm-community`) across the
+    agents / conversation / claims panes, and the cluster legend uses the
+    real names;
+  - `from_relata()` harvests per-author unit/role from the GAP-R10 claim
+    stub columns, so DB-sourced canvases carry attribution without a live
+    world;
+  - `RelataBackend.append_claim()` derives `label`/`unit`/`role` from the
+    claim payload when the caller passes none (GAP-R10 parity for the bare
+    agent path — `world.persist_claim` → `append_claim(stmt)` used to
+    persist empty attribution for every plain `publish_claim()`).
+  Regression-pinned in `tests/viz/` (naming, fallback label, from_relata
+  enrichment, filter markup).
+- **`HyperMindAgent.cite()` default-uncertainty crash.** The no-`uncertainty=`
+  branch built `Uncertainty(alpha=9.0, beta=1.0)` against the current
+  `(kind, params)` constructor, so every cite without an explicit
+  `Uncertainty` raised `TypeError`. Found live during tenant-onboarding
+  validation (2026-08-24); regression-pinned in
+  `tests/test_agent_cite_default.py`.
+
+## [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.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hypermind
-Version: 2.3.0
+Version: 2.4.1
 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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/pyproject.toml

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