diff --git a/BACKBEAT.md b/BACKBEAT.md
new file mode 100644
index 0000000..57a59a5
--- /dev/null
+++ b/BACKBEAT.md
@@ -0,0 +1,454 @@
+# Backbeat Protocol — Pulse/Reverb (v0.1)
+
+> **Purpose:** Give CHORUS a shared, lightweight rhythm so multi‑agent, p2p work doesn’t deadlock or drift. Standardise expectations (plan/work/review), exit conditions, promises, and time‑bounded collaboration across CHORUS, HMMM, SLURP, SHHH, UCXL, WHOOSH, and COOEE.
+
+---
+
+## 1) Rationale
+
+- **Problem:** In pub/sub meshes, agents can wait indefinitely for help/context; there’s no universal cadence for planning, execution, or re‑evaluation.
+    
+- **Principle:** Use **coarse, explicit tempo** (beats/bars) for policy alignment; not for hard real‑time sync. Must be **partition‑tolerant**, **observable**, and **cheap**.
+    
+- **Design:** Human‑readable **beats/bars/phrases** for policy, **Hybrid Logical Clocks (HLC)** for mergeable ordering.
+    
+
+---
+
+## 2) Core Concepts
+
+- **Tempo (BPM):** Beats per minute (e.g., 6–30 BPM). Cluster‑level default; task classes may suggest hints.
+    
+- **Beat:** Base epoch (e.g., 4 s @ 15 BPM).
+    
+- **Bar:** Group of beats (e.g., 8). **Downbeat** (beat 1) is a soft barrier (checkpoints, secret rotation).
+    
+- **Phrase:** A sequence of bars that maps to a work cycle: **plan → work → review**.
+    
+- **Score (per task):** Declarative allocation of beats across phases + wait budgets + retries.
+    
+
+---
+
+## 3) Roles & Components
+
+- **Pulse:** Cluster tempo broadcaster. Publishes `BeatFrame` each beat; single elected leader (Raft/etcd), followers can degrade to local.
+    
+- **Reverb:** Aggregator/rollup. Ingests `StatusClaim`s and emits per‑bar `BarReport`s, plus hints for adaptive tempo.
+    
+- **Agents (CHORUS workers, HMMM collaborators, SLURP, etc.):** Consume beats, enforce **Score**, publish `StatusClaim`s.
+    
+- **SHHH:** Rotates short‑lived secrets **on downbeats** (per‑bar keys).
+    
+- **COOEE/DHT:** Transport for topics `backbeat://cluster/{id}` and per‑project status lanes.
+    
+
+### Implementation Snapshot (2025-10)
+
+- **Pulse service (`cmd/pulse`)** – Encapsulates Raft leader election (`internal/backbeat/leader.go`), Hybrid Logical Clock maintenance (`internal/backbeat/hlc.go`), degradation control (`internal/backbeat/degradation.go`), and beat publishing over NATS. It also exposes an admin HTTP surface and collects tempo/drift metrics via `internal/backbeat/metrics.go`.
+- **Reverb service (`cmd/reverb`)** – Subscribes to pulse beats and agent status subjects, aggregates `StatusClaim`s into rolling windows, and emits `BarReport`s on downbeats. Readiness, health, and Prometheus endpoints report claim throughput, aggregation latency, and NATs failures.
+- **Go SDK (`pkg/sdk`)** – Provides clients for beat callbacks, status emission, and health reporting with retry/circuit breaker hooks. CHORUS (`project-queues/active/CHORUS/internal/backbeat/integration.go`) and WHOOSH (`project-queues/active/WHOOSH/internal/backbeat/integration.go`) embed the SDK to align runtime operations with cluster tempo.
+- **Inter-module telemetry** – CHORUS maps P2P lifecycle operations (elections, DHT bootstrap, council delivery) into BACKBEAT status claims, while WHOOSH emits search/composer activity. This keeps Reverb windows authoritative for council health and informs SLURP/BUBBLE provenance.
+- **Observability bundle** – Monitoring assets (`monitoring/`, `prometheus.yml`) plus service metrics export drift, tempo adjustments, Raft state, and window KPIs, meeting BACKBEAT-PER-001/002/003 targets and enabling WHOOSH scaling gates to react to rhythm degradation.
+
+---
+
+## 4) Wire Model
+
+### 4.1 BeatFrame (Pulse → all)
+
+```json
+{
+  "cluster_id": "chorus-aus-01",
+  "tempo_bpm": 15,
+  "beat_ms": 4000,
+  "bar_len_beats": 8,
+  "bar": 1287,
+  "beat": 3,
+  "phase": "work",
+  "hlc": "2025-09-03T02:12:27.183Z+1287:3+17",
+  "policy_hash": "sha256:...",
+  "deadline_at": "2025-09-03T02:12:31.183Z"
+}
+```
+
+### 4.2 StatusClaim (agents → Reverb)
+
+```json
+{
+  "agent_id": "chorus-192-168-1-27",
+  "task_id": "ucxl://...",
+  "bar": 1287,
+  "beat": 3,
+  "state": "planning|executing|waiting|review|done|failed",
+  "wait_for": ["hmmm://thread/abc"],
+  "beats_left": 2,
+  "progress": 0.42,
+  "notes": "awaiting summarised artifact from peer",
+  "hlc": "..."
+}
+```
+
+### 4.3 HelpPromise (HMMM → requester)
+
+```json
+{
+  "thread_id": "hmmm://thread/abc",
+  "promise_beats": 2,
+  "confidence": 0.7,
+  "fail_after_beats": 3,
+  "on_fail": "fallback-plan-A"
+}
+```
+
+### 4.4 BarReport (Reverb → observability)
+
+- Per‑bar rollup: task counts by state, overruns, broken promises, queue depth, utilisation hints, suggested tempo/phase tweak.
+    
+
+---
+
+## 5) Score Spec (YAML)
+
+```yaml
+score:
+  tempo: 15              # bpm hint; cluster policy can override
+  bar_len: 8             # beats per bar
+  phases:
+    plan: 2              # beats
+    work: 4
+    review: 2
+  wait_budget:
+    help: 2              # max beats to wait for HMMM replies across the phrase
+    io: 1                # max beats to wait for I/O
+  retry:
+    max_phrases: 2
+    backoff: geometric   # plan/work/review shrink each retry
+  escalation:
+    on_wait_exhausted: ["emit:needs-attention", "fallback:coarse-answer"]
+    on_overrun: ["checkpoint", "defer:next-phrase"]
+```
+
+> **Rule:** Agents must not exceed phase beat allocations. If `help` budget is exhausted, **exit cleanly** with degraded but auditable output.
+
+---
+
+## 6) Agent Loop (sketch)
+
+```text
+on BeatFrame(bf):
+  if new bar and beat==1: rotate_ephemeral_keys(); checkpoint();
+
+  phase = score.phase_for(bf.beat)
+
+  switch phase:
+    PLAN:
+      if not planned: do_planning_until(phase_end)
+    WORK:
+      if need_help and !help_promised: request_help_with_promise()
+      if waiting_for_help:
+        if wait_beats > score.wait_budget.help: exit_with_fallback()
+        else continue_work_on_alternative_path()
+      else do_work_step()
+    REVIEW:
+      run_tests_and_summarise(); publish StatusClaim(state=done|failed)
+
+  enforce_cutoffs_at_phase_boundaries()
+```
+
+---
+
+## 7) Adaptive Tempo Controller (ATC)
+
+- **Inputs:** Queue depth per role, GPU/CPU util (WHOOSH), overrun frequency, broken promises.
+    
+- **Policy:** Adjust `tempo_bpm` and/or redistribute phase beats **between bars only** (PI‑style control, hysteresis ±10%).
+    
+- **Guardrails:** ≤1 beat change per minute; freeze during incidents.
+    
+
+---
+
+## 8) Exit Conditions & Deadlock Prevention
+
+- **Wait budgets** are hard ceilings. Missing `HelpPromise` by end‑of‑bar triggers `on_wait_exhausted`.
+    
+- **Locks & leases** expire at bar boundaries unless renewed with `beats_left`.
+    
+- **Promises** include `promise_beats` and `fail_after_beats` so callers can plan.
+    
+- **Idempotent checkpoints** at downbeats enable safe retries/resumptions.
+    
+
+---
+
+## 9) Integration Points
+
+- **CHORUS (workers):** Consume `BeatFrame`; enforce `Score`; publish `StatusClaim` each beat/change.
+    
+- **HMMM (collab):** Replies carry `HelpPromise`; threads auto‑close if `fail_after_beats` elapses.
+    
+- **SLURP (curation):** Batch ingest windows tied to review beats; produce bar‑stamped artefacts.
+    
+- **SHHH (secrets):** Rotate per bar; credentials scoped to `<cluster,bar>`.
+    
+- **UCXL:** Attach tempo metadata to deliverables: `{bar, beat, hlc}`; optional address suffix `;bar=1287#beat=8`.
+    
+- **WHOOSH:** Expose utilisation to ATC; enforce resource leases in beat units.
+    
+- **COOEE/DHT:** Topics: `backbeat://cluster/{id}`, `status://{project}`, `promise://hmmm`.
+    
+
+---
+
+## 10) Failure Modes & Degraded Operation
+
+- **No Pulse leader:** Agents derive a **median‑of‑pulses** from available Purses; if none, use local monotonic clock (jitter ok) and **freeze tempo changes**.
+    
+- **Partitions:** Keep counting beats locally (HLC ensures mergeable order). Reverb reconciles by HLC and bar on heal.
+    
+- **Drift:** Tempo changes only on downbeats; publish `policy_hash` so agents detect misconfig.
+    
+
+---
+
+## 11) Config Examples
+
+### 11.1 Cluster Tempo Policy
+
+```yaml
+cluster_id: chorus-aus-01
+initial_bpm: 12
+bar_len_beats: 8
+phases: [plan, work, review]
+limits:
+  max_bpm: 24
+  min_bpm: 6
+adaptation:
+  enable: true
+  hysteresis_pct: 10
+  change_per_minute: 1_beat
+observability:
+  emit_bar_reports: true
+```
+
+### 11.2 Task Score (attached to UCXL deliverable)
+
+```yaml
+ucxl: ucxl://proj:any/*/task/graph_ingest
+score:
+  tempo: 15
+  bar_len: 8
+  phases: {plan: 2, work: 4, review: 2}
+  wait_budget: {help: 2, io: 1}
+  retry: {max_phrases: 2, backoff: geometric}
+  escalation:
+    on_wait_exhausted: ["emit:needs-attention", "fallback:coarse-answer"]
+```
+
+---
+
+## 12) Observability
+
+- **Per‑bar dashboards:** state counts, overruns, broken promises, tempo changes, queue depth, utilisation.
+    
+- **Trace stamps:** Every artifact/event carries `{bar, beat, hlc}` for forensic replay.
+    
+- **Alarms:** `promise_miss_rate`, `overrun_rate`, `no_status_claims`.
+    
+
+---
+
+## 13) Security
+
+- Rotate **ephemeral keys on downbeats**; scope to project/role when possible.
+    
+- Bar‑stamped tokens reduce blast radius; revoke at bar+N.
+    
+
+---
+
+## 14) Economics & Budgeting — Beats as Unit of Cost
+
+### 14.1 Beat Unit (BU)
+
+- **Definition:** 1 BU = one cluster beat interval (`beat_ms`). It’s the atomic scheduling & accounting quantum.
+    
+
+### 14.2 Resource Primitives (WHOOSH‑measured)
+
+- `cpu_sec`, `gpu_sec[class]`, `accel_sec[class]`, `mem_gbs` (GB·s), `disk_io_mb`, `net_egress_mb`, `storage_gbh`.
+    
+
+### 14.3 Budget & Costing
+
+```yaml
+budget:
+  max_bu:  N_total
+  phase_caps: { plan: Np, work: Nw, review: Nr }
+  wait_caps:  { help: Nh, io: Ni }
+  hard_end: bar+K
+  charge_to: ucxl://acct/...
+```
+
+Cost per phrase:
+
+```
+Total = Σ(beats_used * role_rate_bu)
+      + Σ_class(gpu_sec[class] * rate_gpu_sec[class])
+      + cpu_sec*rate_cpu_sec + mem_gbs*rate_mem_gbs
+      + disk_io_mb*rate_io_mb + net_egress_mb*rate_egress_mb
+      + storage_gbh*rate_storage_gbh
+```
+
+### 14.4 KPIs
+
+- **TNT** (tempo‑normalised throughput), **BPD** (beats per deliverable), **WR** (wait ratio), **η** (efficiency), **PMR** (promise miss rate), **CPD** (cost per deliverable), **TTFU** (time to first useful).
+    
+
+---
+
+## 15) Tokenless Accounting (Hybrid CPU/GPU, On‑prem + Cloud)
+
+- **No tokens.** Price **beats + measured resources**; ignore model‑token counts.
+    
+- **Device classes:** price per GPU/accelerator class (A100, 4090, MI300X, TPU…).
+    
+- **Rates:** on‑prem from TCO / duty‑cycle seconds; cloud from per‑second list prices. Bind via config.
+    
+- **Beat‑scoped caps:** per‑BU ceilings on resource primitives to contain spend regardless of hardware skew.
+    
+- **Calibration (planning‑only):** per‑family normalisers if you want **Effective Compute Units** for planning; **billing remains raw seconds**.
+    
+
+---
+
+## 16) MVP Bring‑up Plan
+
+1. **Pulse**: static BPM, broadcast `BeatFrame` over COOEE.
+    
+2. **Agents**: publish `StatusClaim`; enforce `wait_budget` & `HelpPromise`.
+    
+3. **Reverb**: roll up to `BarReport`; surface early KPIs.
+    
+4. **SHHH**: rotate credentials on downbeats.
+    
+5. **ATC**: enable adaptation after telemetry.
+    
+
+---
+
+## 17) Open Questions
+
+- Per‑role tempi vs one cluster tempo?
+    
+- Fixed `bar_len` vs dynamic redistribution of phase beats?
+    
+- Score UI: YAML + visual “score sheet” editor?
+    
+
+---
+
+### Naming (on brand)
+
+- **Backbeat Protocol** — **Pulse** (broadcaster) + **Reverb** (rollup & reports). Musical, expressive; conveys ripples from each downbeat.
+
+
+# Backbeat — Relative Beats Addendum (UCXL ^^/~~)
+
+**Why this addendum?** We’re removing dependence on ever‑increasing `bar`/`beat` counters. All coordination is expressed **relative to NOW** in **beats**, aligned with UCXL temporal markers `^^` (future) and `~~` (past).
+
+## A) Wire Model Adjustments
+
+### BeatFrame (Pulse → all)
+
+**Replace** prior fields `{bar, beat}` with:
+
+```json
+{
+  "cluster_id": "...",
+  "tempo_bpm": 15,
+  "beat_ms": 4000,
+  "bar_len_beats": 8,
+  "beat_index": 3,                  // 1..bar_len_beats (cyclic within bar)
+  "beat_epoch": "2025-09-03T02:12:27.000Z", // start time of this beat
+  "downbeat": false,                // true when beat_index==1
+  "phase": "work",
+  "hlc": "2025-09-03T02:12:27.183Z+17",
+  "policy_hash": "sha256:...",
+  "deadline_at": "2025-09-03T02:12:31.183Z"
+}
+```
+
+### StatusClaim (agents → Reverb)
+
+**Replace** prior fields `{bar, beat}` with:
+
+```json
+{
+  "agent_id": "...",
+  "task_id": "...",
+  "beat_index": 3,
+  "state": "planning|executing|waiting|review|done|failed",
+  "beats_left": 2,
+  "progress": 0.42,
+  "notes": "...",
+  "hlc": "..."
+}
+```
+
+### Bar/Window Aggregation
+
+- Reverb aggregates per **window** bounded by `downbeat=true` frames.
+    
+- **No global bar counters** are transmitted. Observability UIs may keep a local `window_id` for navigation.
+    
+
+## B) UCXL Temporal Suffix - (Requires RFC-UCXL 1.1)
+
+Attach **relative beat** navigation to any UCXL address:
+
+- `;beats=^^N` → target **N beats in the future** from now
+    
+- `;beats=~~N` → target **N beats in the past** from now
+    
+- Optional: `;phase=plan|work|review`
+    
+
+**Example:**
+
+```
+ucxl://proj:any/*/task/ingest;beats=^^4;phase=work
+```
+
+## C) Policy & Promises
+
+- All time budgets are **Δbeats**: `wait_budget.help`, `retry.max_phrases`, `promise_beats`, `fail_after_beats`.
+    
+- **Leases/locks** renew per beat and expire on phase change unless renewed.
+    
+
+## D) Derivations
+
+- `beat_index = 1 + floor( (unix_ms / beat_ms) mod bar_len_beats )` (derived locally).
+    
+- `beat_epoch = floor_to_multiple(now, beat_ms)`.
+    
+- `Δbeats(target_time) = round( (target_time - now) / beat_ms )`.
+    
+
+## E) Compatibility Notes
+
+- Old fields `{bar, beat}` are **deprecated**; if received, they can be ignored or mapped to local windows.
+    
+- HLC remains the canonical merge key for causality.
+    
+
+## F) Action Items
+
+1. Update the **spec wire model** sections accordingly.
+    
+2. Regenerate the **Go prototype** using `BeatIndex/BeatEpoch/Downbeat` instead of `Bar/Beat` counters.
+    
+3. Add UCXL parsing for `;beats=^^/~~` in RUSTLE.
+- [ ] TODO: RUSTLE update for BACKBEAT compatibility
diff --git a/BUBBLE.md b/BUBBLE.md
new file mode 100644
index 0000000..1459e73
--- /dev/null
+++ b/BUBBLE.md
@@ -0,0 +1,38 @@
+BUBBLE is an organization that functions as a hierarchical index augmented with semantic and provenance overlays. Its primary purpose is to extract historical authority provenance, decision records, citations, and decision ancestry. These capabilities support complex queries, semantic proximity navigation, citation tracking for decisions, and namespace navigation. BUBBLE enables fast, academic-style citation tracking, semantic navigation, and provenance verification, making it a crucial component for managing decision history and authority within the system.
+
+# Decision Records as first-class artifacts
+
+**DRs everywhere.** Every accepted/rejected option becomes an immutable node with edges like _influenced-by_, _derived-from_, and _depends-on-constraint-X_. This enables academic-style citation tracking, semantic proximity hops, and classic namespace traversal in one surface.
+
+# Audit in minutes, not weeks
+
+Because BUBBLE indexes against UCXL addresses, you can reconstruct _exactly_ what a role could see at time **t** and why a path was chosen — no folklore archaeology.
+
+**References:**
+
+1. [KG] Entities (KG): BUBBLE (file: MASTER PLAN.md)
+2. [DC] Document Chunks: "Machine-readable metadata for provenance & confidence." (file: 1)
+3. [KG] Relationships (KG): BUBBLE enables citation tracking for Decision Records (file: MASTER PLAN.md)
+4. [KG] Relationships (KG): BUBBLE's provenance and citation tracking support SLURP's decision processes (file: MASTER PLAN.md)
+5. [KG] Relationships (KG): BUBBLE extracts and manages Decision Records with provenance graphs (file: MASTER PLAN.md)
+
+## How does UCXL work with BUBBLE?
+
+UCXL and BUBBLE are interconnected within the broader ecosystem of semantic context management and decision provenance. UCXL functions primarily as a protocol architecture designed for addressing, managing, and sharing semantic contextual resources. It creates a 1:1 mapping between traditional file system structures and contextual metadata, enabling distributed AI development, knowledge preservation, and sophisticated context organization. UCXL supports features such as semantic address parsing, temporal navigation, context storage, and content retrieval, functioning as a foundational framework for maintaining and querying knowledge with temporal and semantic precision [KG1].
+
+BUBBLE, on the other hand, acts as a hierarchical index and provenance overlay system. It enables extraction of historical authority provenance, decision records, citations, and decision ancestry. BUBBLE supports semantic and provenance overlays, citation tracking, complex queries, and namespace navigation, particularly over decision data and authority provenance. It works in conjunction with systems like SLURP and facilitates fast citation tracking and semantic proximity navigation, enriching the decision-making and knowledge validation process [DC8].
+
+The correlation between UCXL and BUBBLE is thus centered on BUBBLE leveraging UCXL's protocol and addressing capabilities to support detailed provenance, decision tracking, and semantic overlay functionalities. BUBBLE’s ability to extract, index, and query decision records and provenance graphs fundamentally depends on UCXL’s resource addressing, contextual metadata management, and semantic addressing features. Together, they form a cohesive system for knowledge preservation, decision validation, and context-aware reasoning within the distributed AI environment.
+
+**References:**
+
+[KG1] UCXL: Entities and Description, in KG file
+[DC8] BUBBLE: Entity description and functions, in Document Chunks
+
+## TODO
+
+- Complete RocksDB storage implementation and promote to production default (replace SQLite).
+- Integrate vector search (e.g., FAISS/Milvus) for similarity scoring in WalkBack.
+- Implement DHT → local synchronization/replication for up-to-date decision graphs.
+- Add caching layer (LRU or Redis) for frequent bundles and document cache invalidation.
+- Optional: LLM-based summaries for `DecisionBundleResponse` with configuration and tests.
diff --git a/CHORUS-AGENTS.md b/CHORUS-AGENTS.md
new file mode 100644
index 0000000..75b24ea
--- /dev/null
+++ b/CHORUS-AGENTS.md
@@ -0,0 +1,115 @@
+## What is CHORUS?
+
+CHORUS is a comprehensive, distributed platform primarily designed for AI coordination and communication within its ecosystem. It functions as a semantic context publishing system that enables autonomous AI agents to securely share decisions, coordinate activities, and maintain consistent contexts through role-based encryption and consensus mechanisms. The platform supports real-time, selective sharing of both live and historical contextual data, facilitating operations such as task management, artifact publishing, and provenance tracking.
+
+Originally established as a task coordination system using the `bzzz://` protocol, CHORUS is evolving into a semantic context publishing platform that enhances AI collaboration by transforming task coordination into a distributed decision graph based on the UCXL protocol. It also addresses operational aspects like data storage, configuration management, and security, including license management and threat protection. Overall, CHORUS aims to enable decentralized AI workflows, autonomous agent collaboration, and robust information sharing across distributed systems.
+
+**Context OS responsibilities:** CHORUS orchestrates _selective_, time-aware context exchange between peers (no repo mirroring), carrying machine-readable provenance and confidence. In effect, it acts as the **runtime** for UCXL-addressed knowledge and policy-aware routing.
+
+### References:
+
+- [KG] Entity 1 (CHORUS) describes its role as a distributed AI coordination and semantic context publishing platform.
+- [DC] "Phase 1 Integration Test Framework" document emphasizes its purpose in enabling secure, real-time sharing of decisions and contextual data.
+- [KG] Its support for autonomous agents and role-based encryption highlights its focus on secure, decentralized AI collaboration.
+- [KG] The transformation from a task coordination system to a semantic platform indicates its goal of enhancing operational synchronization.
+- [DC] User Manual details the system's functions in managing AI decision-sharing and collaboration.
+
+## Current Implementation Snapshot (2025-10)
+
+- **WHOOSH-assignment runtime** – `internal/runtime/shared.go` now bootstraps a `pkg/config.RuntimeConfig` that merges base env vars with dynamic assignments pulled from WHOOSH (`ASSIGN_URL`). Reloads are wired to `SIGHUP`, and WHOOSH-provided bootstrap peers or join staggers override baked-in defaults. See [[docs/Modules/WHOOSH.md]] for the rendezvous API that serves these payloads.
+- **License-first startup & AI provider wiring** – Startup blocks on `internal/licensing` validation against KACHING before any P2P work. Once licensed, `initializeAIProvider` configures ResetData or Ollama providers, composes persona prompts, and enables LightRAG via the MCP client when `LightRAG.Enabled` is set. This keeps reasoning, prompt curation, and RAG feeds consistent across containers.
+- **Tempo-aware operations via BACKBEAT** – The BACKBEAT integration (`internal/backbeat/integration.go`) tracks beat cadence, wraps long-running peer operations (DHT bootstrap, peer discovery, elections), and emits health/status claims. Election scoring (`pkg/election/election.go`) consumes tempo and beat-gap data to throttle discovery storms and to respect stability windows.
+- **Instrumented transport stack** – `pkg/transport/quic_transport.go` layers QUIC + optional TCP fallback with pooled streams, dial metrics, and configurable libp2p options. A transport telemetry reporter (`internal/runtime/transport_telemetry.go`) publishes snapshots to NATS (`CHORUS_TRANSPORT_METRICS_NATS_URL`) and surfaces per-transport counters through `pkg/metrics`.
+- **Encrypted context pipeline** – When `V2.DHT.Enabled` is true, CHORUS spins up a libp2p DHT with AGE-backed storage (`pkg/dht`) and routes decision artifacts through `ucxl.DecisionPublisher`, exposing them via the optional UCXI HTTP server. Council opportunities are bridged over QUIC streams and mirrored onto NATS to keep WHOOSH/SLURP in sync.
+
+**Operational Notes**
+
+- **Centralised QUIC option injection** – Noise security, muxers, and relay support are now exclusively configured inside `transport.NewQUICTransport`, preventing the duplicate-provider panic that surfaced when both the transport and caller registered `libp2p.Security(noise)`. Custom libp2p options should be appended via runtime overrides to avoid reintroducing duplicates.
+
+## How does CHORUS establish a peer-to-peer network?
+
+CHORUS connects to itself to form a peer-to-peer (P2P) network through its native libp2p-based infrastructure, which manages peer discovery, connectivity, and message routing. The system employs protocols such as pubsub for messaging and mDNS or DHT for peer discovery, enabling nodes to automatically recognize and establish connections with each other without manual configuration.
+
+Specifically, the architecture supports direct peer connections where nodes connect directly with each other, forming a full mesh or ring topology depending on deployment. The network topology is managed via mechanisms like bootstrap peers, which are static nodes used to initialize and support connections within the network. Nodes exchange capability broadcasts periodically to maintain an updated view of the network state.
+
+Security in the connection process is enhanced through cryptographic verification methods like signature validation and signature verification to ensure trustworthiness among peers. Additionally, peer discovery protocols like mDNS (multicast DNS) facilitate neighborhood detection within local networks, while content and capabilities are exchanged securely. The infrastructure includes features for network resilience such as circuit breakers, rate limiting, and network health monitoring.
+
+Overall, CHORUS forms its P2P network by leveraging libp2p’s suite of protocols for secure, decentralized peer discovery and connection management, which allows nodes within the network to connect directly and participate effectively in distributed AI coordination activities.
+
+**Institutional stance:** libp2p + scoped sync means context sharing is intentional, logged, and revocable; bootstrap + capability broadcasts make the mesh resilient while preserving least-privilege flow.
+
+References:
+[KG] "CHORUS P2P Network": Describes the decentralized communication layer involving peer discovery, pubsub messaging, and mutual peer management.
+[DC] "README.md": Details on network discovery, peer connections, and mesh network topology.
+[KG] "libp2p": Mentioned as the core protocol facilitating mesh networking, peer discovery via mDNS, and secure connections.
+[KG] "CHORUS P2P Mesh": Organization that supports distributed peer connections for chat and AI collaboration.
+[DC] "CHORUS-ARCHITECTURE.md": Explains the architecture including bootstrap peers and full mesh topology.
+### 1.1.2.1 Key Functions
+
+ - Decentralized task coordination and management
+ - Secure, role-based sharing of contextual data
+ - Autonomous AI agent collaboration
+ - Content publishing of decisions and task updates
+ - Distributed data storage and retrieval
+ - Role-based encryption and security
+ - System configuration management
+ - License enforcement and resilience
+ - System deployment and maintenance
+
+### 1.1.2.2 Modules of CHORUS
+
+ - [[BUBBLE]]
+ - [[SLURP]]
+ - [[COOEE]]
+ - [[SHHH]]
+ - [[HMMM]]
+ - [[UCXL]]
+ - [[DHT]]
+
+CHORUS employs a range of components and modules that form its comprehensive architecture. The core components include the Main Application (main.go), decision-related modules such as the Decision Publisher, Election Manager, and Configuration Manager, and infrastructure elements like the Crypto Module (supporting Age encryption and Shamir secret sharing), Distributed Hash Table (DHT) Storage, and the Peer-to-Peer (P2P) Network for peer discovery and pub/sub messaging.
+
+Additionally, CHORUS features specialized modules such as the UCXL protocol for semantic address management, SLURP for context management and decision reasoning, and a set of components dedicated to content publishing, security, and operational diagnostics. It also includes components responsible for the layered architecture, such as API handling, web sockets, and management tools.
+
+For hybrid or flexible deployment, there are mock components for extensive testing and real components intended for production use. These include mock and real implementations of the DHT backend, address resolution, peer discovery, network layer, and connectors (such as the CHORUS Connector and RUSTLE Hybrid Components). The architecture is designed to support role-based security, distributed storage, consensus elections, and semantic addressing to facilitate decentralized AI coordination.
+
+References:
+
+[KG] Entity "CHORUS" description in the JSON graph.
+[DC] "CHORUS System Architecture" details in "CHORUS-2B-ARCHITECTURE.md".
+[DC] Components listed under "System Components" in "CHORUS_N8N_IMPLEMENTATION_COMPLETE.md".
+[DC] Architectural diagrams in "CHORUS Architecture Documentation".
+
+
+## What models does CHORUS use?
+
+The CHORUS platform supports various models for its AI agents, depending on their roles and tasks. Specifically, the system includes features such as model integration within role configurations and capabilities for autonomous AI agents. One known provider mentioned is Ollama, which supplies models used for meta-thinking and performance metrics within the system, indicating that Ollama models are utilized to support agents in reasoning and performance evaluation.
+
+CHORUS can execute tasks using its built-in smolLM3 model from HuggingFace, claude code using sonnet or opus from AnthropicAI, Google's gemini-cli tool, or models available for Ollama.
+
+Additionally, CHORUS’s architecture involves the integration of models for different purposes, such as development, testing, and deployment, including models in the context of the RUSTLE component for meta-thinking and model capability announcements. The platform emphasizes a flexible, role-based model deployment framework, enabling agents to self-allocate tasks based on their available tooling and model capabilities.
+
+**References:**
+
+- [KG] Entity "Ollama" describing model providers for system agents.
+- [DC] Content from "USER_MANUAL.md" and "CHORUS System Architecture" describing role-based and capability-driven model usage.
+
+## What happens if my machines crash?
+
+If a CHORUS agent machine crashes or goes offline, the system employs fault detection and failover mechanisms to maintain operational continuity. Heartbeat signals, which are periodic messages sent by agents to indicate they are active, play a key role in fault detection. When an agent fails to send heartbeats within a configured timeout period, the system recognizes this as a failure scenario.
+
+In response, the system can trigger an automatic election to replace or promote another agent, utilizing algorithms such as Raft to select a new leader or maintain consensus. The system also supports automatic failover, where services migrate from the failed node to remaining healthy nodes (B & C) to ensure continuous operation. This process enhances reliability by enabling the system to recover quickly from node failures. Moreover, monitoring and health checks are in place to track system status and trigger recovery events, including replacing failed agents and re-establishing communication channels.
+
+In some cases, recovery events are tracked by the health monitoring system for performance analysis, ensuring that overall system stability and reliability are preserved even during individual machine failures.
+
+## TODO
+
+- Integrate the Sequential Thinking MCP wrapper as a first-class AI provider so architect-level personas use the encrypted reasoning flow powered by `deploy/seqthink/mcp_server.py`.
+- Deliver the brief-processing/event loop described in the task execution monitoring plan so councils automatically hand work to the execution engine.
+
+
+- DHT (production): Ensure the runtime uses libp2p-kad DHT (not mocks), with 3–5x replication, provider records, and SLOs validated (success >99%, p95 GET <300ms).
+- UCXL + encryption: Validate leader-only write/read paths with AGE/Shamir; document key rotation and run end-to-end tests for encrypted artifacts.
+- SLURP as leader-only: Codify SLURP as privileged leader-only paths gated by elections; add leader assertions and tests.
+- SHHH as leader-only: Introduce secrets sentinel hooks in publish/log ingest; implement redact/deny rules and audit trails under leader control.
+- COOEE announcements: Surface capability/availability and enrolment APIs with schemas and tests; integrate with agentid flows.
+- Elections/consensus: Document algorithms and add multi-node tests for failover, recovery, and consistency.
diff --git a/COOEE.md b/COOEE.md
new file mode 100644
index 0000000..60a6c0e
--- /dev/null
+++ b/COOEE.md
@@ -0,0 +1,1720 @@
+COOEE is the **channel/queue** where agents: (a) announce **capabilities & availability**, (b) submit **PRs/DRs** to SLURP, (c) call for **human intervention**, and (d) bootstrap a **self-healing libp2p mesh** that underpins the **DHT** layer.
+
+The channel message queuing technology that allows agents to announce availability and capabilities, submit PR and DR to SLURP, and call for human intervention. COOEE also allows the CHORUS agents to self-install and form a self-healing, self-maintaining, peer-to-peer network that becomes the backbone of our [[DHT]] Layer. COOEE is based on the open-source libp2p.
+
+The actual implementation of the resultant design can be found under these paths:
+
+```
+~/chorus/project-queues/active/CHORUS/pkg/agentid/*
+~/chorus/project-queues/active/ucxl-validator/agentid/*
+```  
+
+
+The following was garnered from a conversation about how to create the Agent IDs:
+
+## Agent IDs
+If you want **tiny**, **deterministic**, and **reversible** without relying on a single central DB, the moment you said _“CHORUS in a DHT”_, my brain went:
+
+> This is basically a UCXL identity table baked into the same infrastructure you already trust for context.
+
+
+## Agent ID enrolment
+
+**AgentID Enrolment (encrypted).** For each installed model/agent, COOEE posts an **enrol** record to  
+`ucxl://any:admin@COOEE:enrol/#/agentid/<assigned_id>` containing the **raw JSON tuple** and **tiny hash**. Payloads are encrypted with the **Leader’s public age key**; only SLURP’s Leader can decrypt, validate, and merge.
+
+## **Workflow (concise):**
+
+1. Canonicalise tuple `{model, hostname, mac, gpu_id}` → compute tiny reversible ID (or DHT-backed hash).
+    
+2. **Encrypt** payload with Leader’s **age** pubkey.
+    
+3. Publish to the **enrol** UCXL address; peers relay blind.
+    
+4. Leader **decrypts**, validates, and commits to context.
+    
+
+> **Why DHT + tiny IDs?** Deterministic, reversible, no central authority; works with UCXL (“the address _is_ the query”).
+
+---
+
+## 1️⃣ Using CHORUS + DHT as the backing store
+
+Instead of giving each agent a random short ID from a central service, you:
+
+1. **Canonicalize** the agent's identity tuple
+    
+    ```
+    model, hostname, mac, gpu_id
+    ```
+    
+    (e.g. sorted field names, lowercase, stripped whitespace, normalized MAC)
+    
+2. **Hash it with a short-length, DHT-friendly hash**
+    
+    - BLAKE3 or SHA-256 → truncate to 32–48 bits for tiny ID
+        
+    - Encode in Base32 Crockford or Base58 for human friendliness
+        
+    - 48 bits → ~10 Base58 chars, collision probability negligible for your scale
+        
+3. **Publish** that tuple to CHORUS as a DHT record:
+    
+    ```
+    key: <tiny_hash>
+    value: { model, hostname, mac, gpu_id, timestamp, signature? }
+    ```
+    
+4. Any node can **reverse** by DHT lookup:
+    
+    - Given tiny hash → fetch full tuple
+        
+
+---
+
+**Advantages:**
+
+- **Deterministic**: same tuple = same ID every time
+    
+- **Reversible**: ID → tuple via DHT
+    
+- **No central authority**
+    
+- Fits perfectly with UCXL’s "address is the query" concept
+    
+- Built-in distribution and redundancy
+    
+- If you add signatures, you get **self-certifying IDs** (agent proves tuple authenticity)
+    
+
+**Trade-offs:**
+
+- Slight DHT lookup latency (milliseconds → hundreds ms depending on network size)
+    
+- If you truncate hash too aggressively (<40 bits), you could get collisions in large agent networks
+    
+- Must ensure canonicalization rules are strictly consistent across all peers
+    
+
+---
+
+## 2️⃣ Deterministic Short IDs Without DHT
+
+This would be if you wanted to _skip_ storage and just reverse mathematically:
+
+- Essentially a **custom base encoding of each field**
+    
+- Pack MAC (48 bits), GPU ID code (maybe 16 bits), hostname dictionary index, model dictionary index into a bit field
+    
+- Encode as Base58/Base32
+    
+- Totally reversible, zero lookups — but:
+    
+    - Requires maintaining the same dictionaries everywhere
+        
+    - Doesn’t compress much unless fields are dictionary-encoded
+        
+
+---
+
+## 3️⃣ Hybrid
+
+- Use method #2 to make the shortest possible packed form
+    
+- Still publish to CHORUS’s DHT so agents who don’t have the dictionary can decode
+    
+
+---
+
+If you go **CHORUS+DHT**, your tiny hash becomes part of the UCXL namespace — essentially:
+
+```
+ucxl://agentid:<tiny_hash>
+```
+
+And you could resolve it exactly like any other UCXL context.
+
+---
+
+If you want, I can spec the **canonicalization + hashing + DHT publish/resolve process** for the CHORUS integration so it slots neatly into your UCXL resolution flow.  
+That way, agent identity behaves like _just another context address_.
+
+## TODO
+
+- Bus semantics: Implement capability/availability announcements and PR/DR submission with schemas and examples (beyond agentid enrolment).
+- Mesh ops: Document libp2p bootstrap/mesh configuration, self-healing behavior, health checks; add integration tests.
+- SLURP paths: Confirm PR/DR submission and SLURP ingest paths with structure, auth, and audit requirements.
+
+Do you want me to draw that up? I can also calculate exactly how short we can make the deterministic hash before collisions get risky in your expected network size.
+
+Alright — let’s work through this step-by-step and see exactly how many bits you’d need for a **collision-free** deterministic + reversible ID for your max network size.
+
+---
+
+## 1️⃣ The absolute upper bound on unique IDs
+
+You said:
+
+- Max **254 hosts**
+    
+- Max **8 GPUs per host**
+    
+
+So **total possible agent instances**:
+
+```
+254 × 8 = 2032 unique agents
+```
+
+---
+
+## 2️⃣ Bits needed to uniquely address all agents
+
+We need enough bits so each agent has a unique binary number:
+
+```
+log2(2032) ≈ 10.99 bits
+```
+
+Round up → **11 bits** to distinguish them.
+
+---
+
+## 3️⃣ If we include host & GPU identity separately
+
+If we want to explicitly encode:
+
+- Host index: needs `log2(254) ≈ 7.99 → 8 bits`
+    
+- GPU index: needs `log2(8) = 3 bits`
+    
+
+**Total** = `8 + 3 = 11 bits` (same as above, just split).
+
+---
+
+## 4️⃣ Adding safety margin
+
+If you want to:
+
+- Allow for growth (say up to 1024 hosts × 16 GPUs)
+    
+- Add future expansion without breaking IDs
+    
+
+We could reserve:
+
+- **10 bits** for host (1024 possible)
+    
+- **4 bits** for GPU slot (16 possible)
+    
+
+That’s **14 bits** total — still tiny.
+
+---
+
+## 5️⃣ Encoding size in characters
+
+**14 bits** of raw data is:
+
+- 3 Base32 chars (each Base32 char = 5 bits → 3 chars = 15 bits)
+    
+- 3 Base58 chars (slightly more capacity per char, ~5.86 bits)
+    
+
+If you also want to embed:
+
+- Version number (3 bits)
+    
+- Short checksum (5–8 bits for error detection)
+    
+
+Then you’re still looking at **5–6 chars total** for a stable, reversible agent ID.
+
+---
+
+✅ **Conclusion**  
+Even with safe margins + checksum, your agent ID could be **5–6 characters long** and still be fully deterministic and reversible for your network size. That’s **without** hashing or a DHT — just pure packing.
+
+If you _do_ put it in CHORUS’s DHT, you can still make it 5–6 chars and have peers resolve back to model name, hostname, MAC, GPU ID.
+
+---
+
+If you want, I can design the **bit-packing scheme** so those 5–6 chars decode directly to `{ host_id, gpu_slot }` and optionally be resolved via UCXL/CHORUS to the full tuple. That would give you the _smallest possible_ reversible code.
+
+Do you want me to go ahead and spec that packing format? That’s the point where we can lock this in permanently.
+
+Nice — here’s a compact, practical spec that gives you a **tiny, deterministic, reversible** agent ID that decodes to a host index + GPU slot, and which you can resolve to full metadata via your DHT (CHORUS) or a tiny registry. I’ll keep it minimal and future-proof.
+
+---
+
+# Design goals
+
+- **Tiny:** 4–6 characters (human-friendly).
+    
+- **Deterministic & reversible:** decoding yields `version`, `host_id`, `gpu_slot` (and reserved bits). To get full model/hostname/MAC/GPU strings, resolve `host_id` in the DHT/registry.
+    
+- **Collision-safe for your scale:** supports ≥1024 hosts and 16 GPU slots (more than your stated max).
+    
+- **URL/file safe & human-friendly:** use Crockford Base32 (case-insensitive, avoids ambiguous chars).
+    
+
+---
+
+# High-level approach
+
+1. Canonicalize and register full tuple `{ model, hostname, mac, gpu_id }` in CHORUS/DHT, which will map to a numeric `host_id` (0..N-1). Registration returns/ensures a stable `host_id`.
+    
+2. Pack `version`, `host_id`, `gpu_slot`, and `reserved` into a small bitfield.
+    
+3. Append a short checksum for simple corruption detection.
+    
+4. Encode the whole bitfield as **Crockford Base32**, producing a 5-character token.
+    
+
+Token format: `xxxxx` (5 Base32 chars)
+
+---
+
+# Bit layout (total 25 bits → 5 × 5-bit Base32 chars)
+
+```
+[ version: 3 bits ]  (0..7)
+[ host_id: 10 bits ] (0..1023)   ← supports up to 1024 hosts
+[ gpu_slot: 4 bits ] (0..15)     ← supports up to 16 GPU slots
+[ reserved: 2 bits ] (future)
+[ checksum: 6 bits ]  (crc6 or truncated hash)
+```
+
+- Total = 3 + 10 + 4 + 2 + 6 = **25 bits** → exactly **5 Base32 characters** (5 × 5 = 25).
+    
+- You can change sizes if you need more hosts; e.g., make `host_id` 12 bits → token grows to 6 chars (30 bits).
+    
+
+---
+
+# Field meanings & ranges
+
+- `version` (3 bits): format version. Start at `1`. Allows upgrades while keeping tokens small.
+    
+- `host_id` (10 bits): assigned numeric ID for the host. Deterministic assignment via registration in DHT/registry. Range `0..1023`.
+    
+- `gpu_slot` (4 bits): 0-based GPU index on that host (`0..15`). Use `0` for CPU-only or no GPU.
+    
+- `reserved` (2 bits): future use (flags, small expansion).
+    
+- `checksum` (6 bits): CRC-6 (or truncated BLAKE3/SHA) of the preceding 19 bits to detect typos/corruption.
+    
+
+---
+
+# Why this layout
+
+- **11 bits** would be the theoretical minimum for 2032 agents (we gave more headroom).
+    
+- 10-bit `host_id` is an easy compromise: supports 1024 hosts ( > 254), still keeps token tiny.
+    
+- 5 Base32 chars = human-manageable tokens (e.g., `4K7J2`) that fit comfortably in UCXL addresses and filenames.
+    
+- Checksum (6 bits) gives basic error-detection; if you want stronger integrity, add a signature byte (but that breaks smallness).
+    
+
+---
+
+# Registration & resolution flow (recommended)
+
+1. **Agent canonicalizes tuple:** normalize strings (lowercase, trim), normalize MAC format (lowercase hex, no separators).
+    
+2. **Agent publishes to CHORUS/DHT** with key computed deterministically from tuple (e.g., BLAKE3(tuple) → use as canonical key). If entry exists, node accepts existing `host_id`; else cluster assigns next available `host_id` (or use a deterministic mapping scheme). Registration response includes `host_id`.
+    
+3. **Agent computes token** using the bit-packing & Base32 encoding described below.
+    
+4. **Other nodes** that see the token can decode it to `host_id` and `gpu_slot`, then `GET ucxl://agentid:<token>` (or DHT lookup) to fetch the full tuple.
+    
+
+---
+
+# Bit-packing & encoding algorithm (pseudo)
+
+1. `bits = 0`
+    
+2. `bits = (bits << 3) | version`
+    
+3. `bits = (bits << 10) | host_id`
+    
+4. `bits = (bits << 4) | gpu_slot`
+    
+5. `bits = (bits << 2) | reserved`
+    
+6. compute `checksum = CRC6(bits, length=19)` (or truncated hash of the 19-bit prefix)
+    
+7. `bits = (bits << 6) | checksum` // final is 25 bits
+    
+8. encode `bits` as 5 groups of 5 bits (MSB-first) → map to Crockford Base32 alphabet.
+    
+9. produce uppercase token (Crockford is case-insensitive).
+    
+
+---
+
+# Example (walkthrough)
+
+Say:
+
+- `version = 1` (001)
+    
+- `host_id = 42` (0000101010)
+    
+- `gpu_slot = 3` (0011)
+    
+- `reserved = 0` (00)
+    
+
+Concatenate (first 3+10+4+2 = 19 bits):
+
+```
+001 0000101010 0011 00
+= binary: 0010000101010001100  (19 bits)
+```
+
+Compute `checksum = CRC6(...)` → say checksum = `0b101010` (42 decimal) for example.
+
+Append checksum:
+
+```
+final 25-bit: 0010000101010001100101010
+Group into 5-bit chunks (MSB-first): [00100][00101][01000][11001][01010]
+Map to Base32 → characters → final 5-char token (example).
+```
+
+(Exact sample token depends on CRC implementation; above is just illustrating the packing.)
+
+---
+
+# Decoding
+
+- Base32-decode 5 chars → 25-bit integer.
+    
+- Extract fields by reverse shifts:
+    
+    - checksum = last 6 bits
+        
+    - reserved = previous 2 bits
+        
+    - gpu_slot = prev 4 bits
+        
+    - host_id = prev 10 bits
+        
+    - version = top 3 bits
+        
+- Recompute checksum on leading 19 bits and verify. If checksum fails, treat as invalid/corrupt.
+    
+- Use `host_id` + `gpu_slot` to query DHT/registry to retrieve the full tuple.
+    
+
+---
+
+# DHT / Registry considerations
+
+- **Deterministic host_id assignment** options:
+    
+    - Option A (centralized registry or consensus): assign next incremental integer on first registration (persisted). Simple, stable.
+        
+    - Option B (deterministic mapping): hash MAC & hostname → reduce to 10 bits (but then collisions possible; you'd need linear-probe resolution and a way to publish the mapping to DHT).
+        
+    - Option C (hybrid): hash to generate candidate ID; if collision, publish both under different `host_id` and return first free — record resolution in DHT.
+        
+- I recommend **Option A** for simplicity: registration service (can be implemented on CHORUS with leader election) assigns stable `host_id`s. It maps cleanly to your UCXL/CHORUS model.
+    
+
+---
+
+# Trade-offs & notes
+
+- The token **does not directly contain** model/hostname/MAC strings — it encodes `host_id` only. That keeps tokens tiny and reversible with a lookup. If you need purely offline reversibility (no DHT), embed more fields and accept longer tokens.
+    
+- If you want absolute decentralization without a registry, you can implement deterministic `host_id` = `truncated_hash(mac)` but you must handle collisions via DHT records that list multiple entries for same truncated id.
+    
+- If you want human-memorable tokens, use Crockford Base32 and optionally add a mnemonic mapping layer.
+    
+
+---
+
+# Implementation offer
+
+I can:
+
+- Produce a **reference Python implementation** (encode/decode + CRC6 + Crockford Base32 mapping + register/resolve stub).
+    
+- Or produce a **Go / Rust** version if you prefer.
+    
+- Or draft the minimal DHT registration RPC (POST /register, GET /resolve/{host_id}) and a tiny SQLite-backed service.
+    
+
+Which would you like? Python example now, or do you want the full microservice + registry spec?
+
+Done — I created a reference Python implementation in a canvas titled **Agentid Codec**. It includes:
+
+- encode/decode (5-char Crockford Base32 tokens),
+    
+- checksum (first 6 bits of SHA-256 over the 19-bit prefix),
+    
+- pack/unpack logic matching the spec, and
+    
+- a tiny SQLite-backed registry stub with `register` and `resolve`.
+    
+
+Open the **Agentid Codec** doc (should be visible in the canvas) and run the script to see an example registration + token encode/decode.
+
+When you want the Go and Rust ports, say which language you want next (I recommend Go first since CHORUS is in Go), and I’ll produce matching implementations and a minimal API spec for the registry.
+
+Absolutely. Here’s a concise Go implementation of the same agent ID encoding/decoding logic, including:
+
+- Packing/unpacking bitfields (version, host_id, gpu_slot, reserved, checksum)
+    
+- CRC6-style checksum (using first 6 bits of SHA256)
+    
+- Crockford Base32 encode/decode (5 chars)
+    
+- A simple in-memory registry stub (maps host hashes to assigned IDs)
+    
+
+This matches the Python reference for seamless cross-language interoperability.
+
+---
+
+```go
+package agentid
+
+import (
+	"crypto/sha256"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+)
+
+var crockfordAlphabet = []rune("0123456789ABCDEFGHJKMNPQRSTVWXYZ")
+var crockfordDecodeMap map[rune]int
+
+func init() {
+	crockfordDecodeMap = make(map[rune]int)
+	for i, r := range crockfordAlphabet {
+		crockfordDecodeMap[r] = i
+		if r >= 'A' && r <= 'Z' {
+			// lowercase also accepted
+			crockfordDecodeMap[r+32] = i
+		}
+	}
+}
+
+const (
+	versionBits  = 3
+	hostIDBits   = 10
+	gpuSlotBits  = 4
+	reservedBits = 2
+	checksumBits = 6
+
+	prefixBits = versionBits + hostIDBits + gpuSlotBits + reservedBits // 19 bits
+	totalBits  = prefixBits + checksumBits                             // 25 bits
+
+	maxHostID  = (1 << hostIDBits) - 1
+	maxGpuSlot = (1 << gpuSlotBits) - 1
+
+	base32Chars = 5
+)
+
+type AgentID struct {
+	Version  uint8
+	HostID   uint16
+	GpuSlot  uint8
+	Reserved uint8
+	Checksum uint8
+}
+
+func sha256FirstBits(value uint32, bits int) uint8 {
+	// convert value (19-bit max) to 3 bytes big endian
+	bytes := []byte{byte(value >> 16), byte(value >> 8), byte(value)}
+	hash := sha256.Sum256(bytes)
+	// extract first `bits` bits from hash
+	// bits=6, so first 6 bits of hash[0]
+	return hash[0] >> (8 - bits)
+}
+
+func packFields(version uint8, hostID uint16, gpuSlot uint8, reserved uint8) (uint32, error) {
+	if version >= (1 << versionBits) {
+		return 0, fmt.Errorf("version out of range")
+	}
+	if hostID > maxHostID {
+		return 0, fmt.Errorf("hostID out of range")
+	}
+	if gpuSlot > maxGpuSlot {
+		return 0, fmt.Errorf("gpuSlot out of range")
+	}
+	if reserved >= (1 << reservedBits) {
+		return 0, fmt.Errorf("reserved out of range")
+	}
+
+	var bits uint32 = 0
+	bits = (bits << versionBits) | uint32(version)
+	bits = (bits << hostIDBits) | uint32(hostID)
+	bits = (bits << gpuSlotBits) | uint32(gpuSlot)
+	bits = (bits << reservedBits) | uint32(reserved)
+
+	checksum := sha256FirstBits(bits, checksumBits)
+	bits = (bits << checksumBits) | uint32(checksum)
+
+	if bits >= (1 << totalBits) {
+		return 0, errors.New("packed value exceeds allowed bit length")
+	}
+	return bits, nil
+}
+
+func unpackFields(packed uint32) (AgentID, error) {
+	if packed >= (1 << totalBits) {
+		return AgentID{}, errors.New("packed value exceeds allowed bit length")
+	}
+
+	checksum := uint8(packed & ((1 << checksumBits) - 1))
+	prefix := packed >> checksumBits
+
+	// extract fields in reverse order
+	tmp := prefix
+	reserved := uint8(tmp & ((1 << reservedBits) - 1))
+	tmp >>= reservedBits
+	gpuSlot := uint8(tmp & ((1 << gpuSlotBits) - 1))
+	tmp >>= gpuSlotBits
+	hostID := uint16(tmp & ((1 << hostIDBits) - 1))
+	tmp >>= hostIDBits
+	version := uint8(tmp & ((1 << versionBits) - 1))
+
+	expected := sha256FirstBits(prefix, checksumBits)
+	if expected != checksum {
+		return AgentID{}, errors.New("checksum mismatch")
+	}
+
+	return AgentID{
+		Version:  version,
+		HostID:   hostID,
+		GpuSlot:  gpuSlot,
+		Reserved: reserved,
+		Checksum: checksum,
+	}, nil
+}
+
+func intToBase32(n uint32, length int) string {
+	chars := make([]rune, length)
+	for i := length - 1; i >= 0; i-- {
+		idx := n & 0x1F
+		chars[i] = crockfordAlphabet[idx]
+		n >>= 5
+	}
+	return string(chars)
+}
+
+func base32ToInt(s string) (uint32, error) {
+	var n uint32 = 0
+	if len(s) != base32Chars {
+		return 0, fmt.Errorf("token length must be %d", base32Chars)
+	}
+	for _, ch := range s {
+		val, ok := crockfordDecodeMap[ch]
+		if !ok {
+			return 0, fmt.Errorf("invalid base32 char: %c", ch)
+		}
+		n = (n << 5) | uint32(val)
+	}
+	return n, nil
+}
+
+// EncodeToken encodes fields into 5-char Crockford Base32 token.
+func EncodeToken(version uint8, hostID uint16, gpuSlot uint8, reserved uint8) (string, error) {
+	packed, err := packFields(version, hostID, gpuSlot, reserved)
+	if err != nil {
+		return "", err
+	}
+	return intToBase32(packed, base32Chars), nil
+}
+
+// DecodeToken decodes 5-char token into fields.
+func DecodeToken(token string) (AgentID, error) {
+	packed, err := base32ToInt(strings.ToUpper(token))
+	if err != nil {
+		return AgentID{}, err
+	}
+	return unpackFields(packed)
+}
+
+// ----------------------
+// Registry stub (in-memory, thread-safe)
+// ----------------------
+
+type HostRecord struct {
+	AssignedID uint16
+	HostHash   string
+	Model      string
+	Hostname   string
+	MAC        string
+	GPUInfo    string
+}
+
+type Registry struct {
+	mu       sync.Mutex
+	nextID   uint16
+	records  map[string]HostRecord // hostHash -> HostRecord
+	usedIDs  map[uint16]struct{}
+}
+
+func NewRegistry() *Registry {
+	return &Registry{
+		records: make(map[string]HostRecord),
+		usedIDs: make(map[uint16]struct{}),
+	}
+}
+
+func canonicalizeTuple(model, hostname, mac string) string {
+	return strings.ToLower(strings.TrimSpace(model)) + "|" + strings.ToLower(strings.TrimSpace(hostname)) + "|" + strings.ToLower(strings.TrimSpace(mac))
+}
+
+func sha256Hex(s string) string {
+	sum := sha256.Sum256([]byte(s))
+	return fmt.Sprintf("%x", sum[:])
+}
+
+// Register returns existing or new assigned ID for given tuple.
+func (r *Registry) Register(model, hostname, mac, gpuInfo string) (HostRecord, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	key := sha256Hex(canonicalizeTuple(model, hostname, mac))
+	if rec, ok := r.records[key]; ok {
+		return rec, nil
+	}
+
+	// Assign next available ID
+	var id uint16
+	for id = 0; id <= maxHostID; id++ {
+		if _, used := r.usedIDs[id]; !used {
+			break
+		}
+	}
+	if id > maxHostID {
+		return HostRecord{}, errors.New("no free host ID available")
+	}
+
+	rec := HostRecord{
+		AssignedID: id,
+		HostHash:   key,
+		Model:      model,
+		Hostname:   hostname,
+		MAC:        mac,
+		GPUInfo:    gpuInfo,
+	}
+
+	r.records[key] = rec
+	r.usedIDs[id] = struct{}{}
+	return rec, nil
+}
+
+// Resolve looks up HostRecord by assigned ID.
+func (r *Registry) Resolve(assignedID uint16) (HostRecord, bool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, rec := range r.records {
+		if rec.AssignedID == assignedID {
+			return rec, true
+		}
+	}
+	return HostRecord{}, false
+}
+```
+
+---
+
+If you want, I can also package this as a full runnable CLI or service next — or start on the Rust version. Just say.
+
+Certainly. Here’s a minimal CLI wrapper around the Rust agent ID library I gave you. It supports two commands:
+
+- `encode`: encode given fields (version, host_id, gpu_slot, reserved) into the 5-char token
+    
+- `decode`: decode a 5-char token into fields
+    
+- `register`: registers a host tuple (model, hostname, mac, gpu_info) and returns assigned ID + token
+    
+- `resolve`: resolves an assigned ID to a registered host record
+    
+
+Uses `clap` for argument parsing.
+
+---
+
+```rust
+use clap::{Parser, Subcommand};
+use std::process;
+
+mod agentid; // your agentid module here
+
+#[derive(Parser)]
+#[clap(author, version, about)]
+struct Cli {
+    #[clap(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    Encode {
+        #[clap(short, long)]
+        version: u8,
+        #[clap(short, long)]
+        host_id: u16,
+        #[clap(short, long)]
+        gpu_slot: u8,
+        #[clap(short, long, default_value_t = 0)]
+        reserved: u8,
+    },
+    Decode {
+        #[clap(short, long)]
+        token: String,
+    },
+    Register {
+        #[clap(short, long)]
+        model: String,
+        #[clap(short, long)]
+        hostname: String,
+        #[clap(short, long)]
+        mac: String,
+        #[clap(short, long)]
+        gpu_info: String,
+    },
+    Resolve {
+        #[clap(short, long)]
+        assigned_id: u16,
+    },
+}
+
+fn main() {
+    let cli = Cli::parse();
+
+    // simple registry instance (in-memory)
+    let registry = agentid::Registry::new();
+
+    match cli.command {
+        Commands::Encode {
+            version,
+            host_id,
+            gpu_slot,
+            reserved,
+        } => {
+            match agentid::encode_token(version, host_id, gpu_slot, reserved) {
+                Ok(token) => println!("{}", token),
+                Err(e) => {
+                    eprintln!("Error encoding token: {}", e);
+                    process::exit(1);
+                }
+            }
+        }
+        Commands::Decode { token } => match agentid::decode_token(&token) {
+            Ok(agent) => {
+                println!(
+                    "version: {}\nhost_id: {}\ngpu_slot: {}\nreserved: {}",
+                    agent.version, agent.host_id, agent.gpu_slot, agent.reserved
+                );
+            }
+            Err(e) => {
+                eprintln!("Error decoding token: {}", e);
+                process::exit(1);
+            }
+        },
+        Commands::Register {
+            model,
+            hostname,
+            mac,
+            gpu_info,
+        } => match registry.register(&model, &hostname, &mac, &gpu_info) {
+            Ok(rec) => {
+                let token = agentid::encode_token(1, rec.assigned_id, 0, 0).unwrap();
+                println!("Assigned ID: {}", rec.assigned_id);
+                println!("Token: {}", token);
+            }
+            Err(e) => {
+                eprintln!("Error registering host: {}", e);
+                process::exit(1);
+            }
+        },
+        Commands::Resolve { assigned_id } => match registry.resolve(assigned_id) {
+            Some(rec) => {
+                println!("Model: {}", rec.model);
+                println!("Hostname: {}", rec.hostname);
+                println!("MAC: {}", rec.mac);
+                println!("GPU Info: {}", rec.gpu_info);
+            }
+            None => {
+                eprintln!("No host found with assigned ID {}", assigned_id);
+                process::exit(1);
+            }
+        },
+    }
+}
+```
+
+---
+
+**Usage examples:**
+
+```
+mycli encode -v 1 -h 42 -g 3  
+mycli decode -t 1C3D4  
+mycli register -m llama3-70b -n alpha-node -a aa:bb:cc:dd:ee:01 -q RTX-4090  
+mycli resolve -i 0  
+```
+
+This is a minimal example to get you started. You can expand it with persistent storage, concurrency, logging, or a networked API as needed.
+
+Want help setting that up next?
+
+Perfect — now those tricky tokens decode cleanly with no checksum or invalid character errors.
+
+You’ve nailed it:
+
+- Encoding and decoding work for all valid input ranges.
+    
+- The checksum verification passes.
+    
+- The base32 encoding/decoding properly handles all Crockford chars including X and Z.
+    
+
+---
+
+If you want, next steps could be:
+
+- Integrate this into your COOEE module/protocol.
+    
+- Add batch tests for all edge cases (min/max values for version, host_id, gpu_slot, reserved).
+    
+- Wrap the CLI with your auto-discovery script to fully automate registration.
+    
+
+---
+
+If you want help building any of that or something else, just say the word!
+
+Got it. Here’s a practical bash script that:
+
+- Lists models from `ollama list`
+    
+- Lets the user pick a model interactively
+    
+- Detects hostname, primary MAC, and primary GPU info automatically
+    
+- Runs your `agentid register` command with those values
+    
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# List models from ollama and number them
+models=()
+while IFS= read -r line; do
+  models+=("$line")
+done < <(ollama list)
+
+echo "Available models:"
+for i in "${!models[@]}"; do
+  printf "%3d) %s\n" "$((i+1))" "${models[$i]}"
+done
+
+# Prompt user for model selection
+read -rp "Enter the number of the model: " model_num
+
+if ! [[ "$model_num" =~ ^[0-9]+$ ]] || (( model_num < 1 || model_num > ${#models[@]} )); then
+  echo "Invalid selection" >&2
+  exit 1
+fi
+
+model="${models[$((model_num-1))]}"
+
+# Get hostname
+hostname=$(hostname)
+
+# Get primary MAC address (from first non-loopback interface with MAC)
+mac=$(ip link show | awk '/^[0-9]+: / { iface=$2 } /link\/ether/ && iface !~ "lo" { print $2; exit }')
+
+# Get primary GPU info (uses nvidia-smi if NVIDIA GPU, fallback to empty)
+if command -v nvidia-smi &>/dev/null; then
+  gpu_info=$(nvidia-smi --query-gpu=name --format=csv,noheader | head -n1)
+else
+  gpu_info="unknown"
+fi
+
+echo "Registering with:"
+echo "  Model:    $model"
+echo "  Hostname: $hostname"
+echo "  MAC:      $mac"
+echo "  GPU Info: $gpu_info"
+
+./agentid register --model "$model" --hostname "$hostname" --mac "$mac" --gpu-info "$gpu_info"
+```
+
+---
+
+### Notes
+
+- Adjust the MAC extraction if your system’s network interfaces differ.
+    
+- GPU info extraction is basic; extend as needed for AMD or integrated GPUs.
+    
+- The script assumes `agentid` binary is in current directory.
+    
+- You can wrap this in a CI pipeline or startup script easily.
+    
+
+---
+
+Want me to help with a more cross-platform or Rust-based version for tighter integration?
+
+Here’s a macOS-compatible version of the script that handles differences in commands and interface naming:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# Detect platform
+OS=$(uname)
+
+# List models from ollama and number them
+models=()
+while IFS= read -r line; do
+  models+=("$line")
+done < <(ollama list)
+
+echo "Available models:"
+for i in "${!models[@]}"; do
+  printf "%3d) %s\n" "$((i+1))" "${models[$i]}"
+done
+
+# Prompt user for model selection
+read -rp "Enter the number of the model: " model_num
+
+if ! [[ "$model_num" =~ ^[0-9]+$ ]] || (( model_num < 1 || model_num > ${#models[@]} )); then
+  echo "Invalid selection" >&2
+  exit 1
+fi
+
+model="${models[$((model_num-1))]}"
+
+# Get hostname (same on macOS and Linux)
+hostname=$(hostname)
+
+# Get primary MAC address
+if [[ "$OS" == "Darwin" ]]; then
+  # macOS: find en0 or first active interface with MAC
+  mac=$(ifconfig en0 2>/dev/null | awk '/ether/ {print $2}')
+  if [[ -z "$mac" ]]; then
+    # fallback: first interface with MAC address
+    mac=$(ifconfig | awk '/ether/ {print $2; exit}')
+  fi
+else
+  # Linux: first non-loopback interface with MAC
+  mac=$(ip link show | awk '/^[0-9]+: / { iface=$2 } /link\/ether/ && iface !~ "lo" { print $2; exit }')
+fi
+
+# Get primary GPU info (try nvidia-smi on Linux, system_profiler on macOS)
+if [[ "$OS" == "Darwin" ]]; then
+  gpu_info=$(system_profiler SPDisplaysDataType 2>/dev/null | awk -F': ' '/Chipset Model/ {print $2; exit}')
+  gpu_info=${gpu_info:-"unknown"}
+else
+  if command -v nvidia-smi &>/dev/null; then
+    gpu_info=$(nvidia-smi --query-gpu=name --format=csv,noheader | head -n1)
+  else
+    gpu_info="unknown"
+  fi
+fi
+
+echo "Registering with:"
+echo "  Model:    $model"
+echo "  Hostname: $hostname"
+echo "  MAC:      $mac"
+echo "  GPU Info: $gpu_info"
+
+./agentid register --model "$model" --hostname "$hostname" --mac "$mac" --gpu-info "$gpu_info"
+```
+
+---
+
+### What’s changed for macOS:
+
+- Uses `ifconfig` and looks for interface `en0` (typically primary Wi-Fi or Ethernet).
+    
+- Falls back to the first MAC found if `en0` is missing.
+    
+- Uses `system_profiler SPDisplaysDataType` to get GPU info.
+    
+- Keeps Linux logic for comparison.
+    
+
+---
+
+This should work cleanly on both platforms.
+
+If you want, I can help turn this into a Rust CLI wrapper for even better cross-platform support.
+
+
+Good call—on macOS, `system_profiler SPDisplaysDataType` reports all GPUs (AMD, Intel, or NVIDIA), so the script as-is will capture AMD GPUs too.
+
+The relevant part:
+
+```bash
+gpu_info=$(system_profiler SPDisplaysDataType 2>/dev/null | awk -F': ' '/Chipset Model/ {print $2; exit}')
+```
+
+This fetches the **first GPU’s “Chipset Model”**, which for Macs with AMD GPUs will be something like:
+
+```
+AMD Radeon Pro 5500M
+AMD Radeon RX 580
+```
+
+---
+
+### For Linux AMD GPUs
+
+The Linux part currently only checks `nvidia-smi` for NVIDIA GPUs.
+
+To detect AMD GPUs on Linux, you can try:
+
+- Parse `lspci` output filtering for AMD GPUs.
+    
+- Use `rocm-smi` if installed.
+    
+- Or fallback to generic info from `/sys/class/drm/card*/device/vendor` and `/sys/class/drm/card*/device/device`.
+    
+
+Here’s a quick Linux AMD GPU detection snippet you can add:
+
+```bash
+if command -v nvidia-smi &>/dev/null; then
+  gpu_info=$(nvidia-smi --query-gpu=name --format=csv,noheader | head -n1)
+elif command -v lspci &>/dev/null; then
+  gpu_info=$(lspci | grep -i 'vga\|3d\|2d' | grep -i 'amd\|advanced micro devices\|radeon' | head -n1 | cut -d':' -f3- | xargs)
+else
+  gpu_info="unknown"
+fi
+```
+
+---
+
+### Summary:
+
+- macOS AMD GPUs: already covered via `system_profiler`.
+    
+- Linux AMD GPUs: add `lspci` parsing fallback as above.
+    
+- Fallback to `"unknown"` if no GPU info found.
+    
+
+---
+
+Want me to update the full combined script for Linux + macOS + AMD GPU detection?
+
+So where exactly is it registering. lets talk persistence
+
+Good question — your current Rust `Registry` implementation is purely **in-memory**, which means:
+
+- All host registrations vanish when your CLI process exits.
+    
+- It’s a stub/demo, not suitable for real persistent use.
+    
+
+---
+
+### What does that mean practically?
+
+- Running `agentid register` twice in separate invocations will never remember previous hosts.
+    
+- The assigned IDs always start from zero in each run.
+    
+- `agentid resolve` only works during the lifetime of the running process.
+    
+
+---
+
+### For real persistence, you have several practical options:
+
+1. **File-based storage**
+    
+    - Serialize your registry’s `HashMap` to JSON, YAML, or a binary format on disk.
+        
+    - Load it at startup and save on every register/update.
+        
+    - Simple, no external dependencies.
+        
+    - But concurrency, locking, and corruption need careful handling.
+        
+2. **Embedded databases**
+    
+    - Use something like [sled](https://sled.rs/) (pure Rust embedded key-value store).
+        
+    - Fast, transactional, no external server.
+        
+    - Can store mappings keyed by your hash or assigned_id.
+        
+    - Needs some integration work.
+        
+3. **External databases**
+    
+    - Use SQLite, Postgres, Redis, or other external DB.
+        
+    - Offers robustness, ACID guarantees, multi-client support.
+        
+    - Adds dependency and deployment complexity.
+        
+    - Recommended for multi-node or clustered environments.
+        
+4. **Distributed systems**
+    
+    - You mentioned DHTs and p2p earlier — CHORUS or COOEE could hold a distributed registry.
+        
+    - This is the most complex but scales well and fits decentralized goals.
+        
+    - Requires consensus or conflict resolution strategies.
+        
+
+---
+
+### What fits your current scope?
+
+- If this is a local CLI utility or small-scale tool, **file-based JSON or sled** persistence is a pragmatic first step.
+    
+- If you’re building a full distributed system (CHORUS + COOEE), then persistence becomes a networked service layer problem, with eventual consistency and sync mechanisms.
+    
+
+---
+
+### Rough file-based approach sketch:
+
+- On `Registry::new()`, load from a JSON file (e.g., `registry.json`).
+    
+- On `register`, insert/update in the map and save the entire map back to the file.
+    
+- On `resolve`, just read from the in-memory map.
+    
+- Use `serde` + `serde_json` crates for easy (de)serialization.
+    
+
+---
+
+If you want, I can draft that file-backed Rust `Registry` for you, including concurrency-safe writes and graceful error handling.
+
+---
+
+Bottom line:
+
+**Right now, the registry only exists during the CLI process run — to make it real, you must add persistent storage.**
+
+lets use COOEE to announce the agentid for each of the installed models and register to ucxl address like ucxl://any:admin@COOEE:enrol/#/agentid/ and pass the raw data as JSON as well as the hash
+
+
+Yes, that tracks perfectly and fits your security model well.
+
+Here’s the breakdown:
+
+- **Only the SLURPing Leader** can decrypt the registration message.
+    
+- So the **COOEE component of CHORUS** must **encrypt the JSON payload using the Leader’s public age key** before publishing it to the UCXL enrol address.
+    
+- This ensures that:
+    
+    - The registration data is **confidential** in transit and at rest.
+        
+    - Only the Leader agent holding the private age key can decrypt and process the enrollment.
+        
+    - Other nodes relay/store the encrypted blob without being able to inspect contents.
+        
+
+---
+
+### Workflow recap:
+
+1. Agent builds registration JSON payload.
+    
+2. COOEE encrypts payload with Leader’s **public age key**.
+    
+3. COOEE posts encrypted payload to `ucxl://any:admin@COOEE:enrol/#/agentid/<assigned_id>`.
+    
+4. Leader listens on that UCXL address, fetches the encrypted message, decrypts it with its **private age key**.
+    
+5. Leader validates and merges registration info into the canonical context store.
+    
+
+---
+
+### Practical implications:
+
+- The Leader’s **public age key** must be securely distributed to all COOEE agents that publish enrollments.
+    
+- You can store the public key in UCXL context itself, or distribute out-of-band.
+    
+- Encryption ensures zero knowledge of agent details by intermediate nodes.
+    
+
+---
+
+### Summary:
+
+- Your reasoning and design are sound.
+    
+- Encrypt with Leader’s public age key before POSTing.
+    
+- Decrypt on Leader side only.
+    
+
+---
+
+If you want, I can help draft the Rust code snippet for:
+
+- Encrypting with age public key before publish.
+    
+- Decrypting on Leader side.
+    
+- Integrating with your current UCXL/COOEE stack.
+- 
+- Glad it’s helpful! Here’s a concise Rust snippet for encrypting a JSON payload with an age public key before publishing it to UCXL via COOEE:
+
+```rust
+use age::{x25519, Encryptor};
+use std::io::Write;
+
+fn encrypt_with_age_public_key(
+    json_payload: &str,
+    recipient_pubkey: &str,
+) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
+    // Parse the recipient's public key
+    let recipient = x25519::Recipient::from_str(recipient_pubkey)?;
+    
+    // Create an Encryptor
+    let encryptor = Encryptor::with_recipients(vec![Box::new(recipient)]);
+    
+    // Buffer for ciphertext
+    let mut ciphertext = Vec::new();
+    {
+        let mut writer = encryptor.wrap_output(&mut ciphertext)?;
+        writer.write_all(json_payload.as_bytes())?;
+        writer.finish()?;
+    }
+    
+    Ok(ciphertext)
+}
+```
+
+---
+
+### Usage in your announce function:
+
+```rust
+fn announce_agentid_via_cooee(
+    agent: &AgentRecord,
+    cooee: &CooeeClient,
+    leader_pubkey: &str,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let address = format!("ucxl://any:admin@COOEE:enrol/#/agentid/{}", agent.assigned_id);
+    let payload = serde_json::to_string(&agent)?;
+    
+    let encrypted_payload = encrypt_with_age_public_key(&payload, leader_pubkey)?;
+    
+    cooee.publish(address, &encrypted_payload)?;
+    Ok(())
+}
+```
+
+---
+
+### On the Leader side, decryption roughly looks like this:
+
+```rust
+use age::{Decryptor};
+use std::io::Read;
+
+fn decrypt_with_age_private_key(
+    ciphertext: &[u8],
+    private_key: &str,
+) -> Result<String, Box<dyn std::error::Error>> {
+    let decryptor = Decryptor::new(ciphertext)?;
+    
+    let mut plaintext = Vec::new();
+    
+    match decryptor {
+        Decryptor::Recipients(d) => {
+            // Load identity from private key string
+            let identity = x25519::Identity::from_str(private_key)?;
+            let mut reader = d.decrypt(&[&identity])?;
+            reader.read_to_end(&mut plaintext)?;
+        }
+        _ => return Err("Unsupported decryptor variant".into()),
+    }
+    
+    Ok(String::from_utf8(plaintext)?)
+}
+```
+
+---
+
+### Notes
+
+- Use the [`age`](https://docs.rs/age/latest/age/) Rust crate (or equivalent bindings) for encryption/decryption.
+    
+- Public/private keys should be passed or securely loaded as strings.
+    
+- This approach secures the content end-to-end.
+    
+- Integrate with your UCXL/COOEE network stack to publish/subscribe encrypted payloads.
+    
+
+---
+
+If you want I can help you build full CLI commands or service handlers for this encryption layer next.
+
+That makes total sense — a single Go binary running CHORUS in different roles (COOEE publisher and SLURP consumer) makes deployment and maintenance cleaner.
+
+---
+
+### So your plan is:
+
+- **CHORUS (COOEE role)**  
+    Publishes agentid enrollment events, encrypting payloads using age with the SLURP Leader’s public key.
+    
+- **CHORUS (SLURP role)**  
+    Listens for enrollment events, decrypts them using the Leader’s private key, validates, and merges into context.
+    
+
+---
+
+### Advantages of unified Go binary:
+
+- Shared codebase and dependencies, easier CI/CD.
+    
+- Consistent cryptography (using Filippo’s age Go lib).
+    
+- Easier IPC or local communication if roles coexist on one host.
+    
+
+---
+
+### Next steps you might want:
+
+1. **Design a Go package/module** that handles:
+    
+    - AgentID struct + JSON serialization.
+        
+    - Age encryption with public key.
+        
+    - Age decryption with private key.
+        
+    - UCXL address publishing + subscription (wrapped around your existing CHORUS networking).
+        
+2. **Refactor your Rust `agentid` CLI** to be a thin client that:
+    
+    - Calls the Go CHORUS binary (e.g., via CLI or gRPC) to perform encrypted enrollment publishes.
+        
+3. **Define your enrollment event schema** clearly, versioned, and extensible.
+    
+4. **Implement conflict resolution and expiration policies** inside the SLURP context store.
+    
+
+---
+
+### If you want, I can help with:
+
+- Drafting the Go agentid enrollment encryption + publish code.
+    
+- The subscriber side for decrypt + context update.
+    
+- A simple CLI stub wrapping those calls for testing.
+    
+- A minimal spec for your enrollment message and UCXL addressing.
+    
+
+---
+
+This approach keeps your Rust tooling focused on local validation and modeling, while Go CHORUS handles your distributed p2p communication and secure data flow.
+
+---
+
+What do you want to tackle next?
+
+Alright, let's design a clean Go package for CHORUS’s unified binary to handle AgentID enrollment and secure communication over UCXL.
+
+---
+
+# Go Package Design: `agentid`
+
+### Responsibilities:
+
+- Represent AgentID records and JSON marshal/unmarshal
+    
+- Encrypt payloads with age public key
+    
+- Decrypt payloads with age private key
+    
+- Publish and subscribe over UCXL addressing within CHORUS’s network stack
+    
+
+---
+
+## 1. **Structs and JSON serialization**
+
+```go
+package agentid
+
+import "encoding/json"
+
+type AgentRecord struct {
+    AssignedID uint16 `json:"assigned_id"`
+    HostHash   string `json:"hash"`
+    Model      string `json:"model"`
+    Hostname   string `json:"hostname"`
+    MAC        string `json:"mac"`
+    GPUInfo    string `json:"gpu_info"`
+}
+
+func (ar *AgentRecord) ToJSON() ([]byte, error) {
+    return json.Marshal(ar)
+}
+
+func FromJSON(data []byte) (*AgentRecord, error) {
+    var ar AgentRecord
+    if err := json.Unmarshal(data, &ar); err != nil {
+        return nil, err
+    }
+    return &ar, nil
+}
+```
+
+---
+
+## 2. **Age encryption with public key**
+
+```go
+import (
+    "bytes"
+    "io"
+    "strings"
+
+    "filippo.io/age"
+    "filippo.io/age/armor"
+)
+
+func EncryptPayload(payload []byte, publicKey string) ([]byte, error) {
+    recipient, err := age.ParseX25519Recipient(publicKey)
+    if err != nil {
+        return nil, err
+    }
+
+    var buf bytes.Buffer
+    // Optional: wrap with armor for ASCII output (can omit if binary preferred)
+    w := armor.NewWriter(&buf)
+    encryptor := age.NewEncryptor(w, recipient)
+    _, err = encryptor.Write(payload)
+    if err != nil {
+        return nil, err
+    }
+    if err := encryptor.Close(); err != nil {
+        return nil, err
+    }
+    if err := w.Close(); err != nil {
+        return nil, err
+    }
+
+    return buf.Bytes(), nil
+}
+```
+
+---
+
+## 3. **Age decryption with private key**
+
+```go
+func DecryptPayload(ciphertext []byte, privateKey string) ([]byte, error) {
+    identity, err := age.ParseX25519Identity(privateKey)
+    if err != nil {
+        return nil, err
+    }
+
+    // Support armored input:
+    r := bytes.NewReader(ciphertext)
+    decoder := armor.NewReader(r)
+
+    decryptor, err := age.Decrypt(decoder, identity)
+    if err != nil {
+        return nil, err
+    }
+    defer decryptor.Close()
+
+    plaintext, err := io.ReadAll(decryptor)
+    if err != nil {
+        return nil, err
+    }
+    return plaintext, nil
+}
+```
+
+---
+
+## 4. **UCXL publish & subscribe integration**
+
+> **Note:** This depends on your existing CHORUS network code. I'll outline interfaces to integrate.
+
+```go
+// Define a publisher interface for UCXL
+type Publisher interface {
+    Publish(address string, data []byte) error
+}
+
+// Define a subscriber interface for UCXL messages
+type Subscriber interface {
+    Subscribe(address string, handler func(data []byte)) error
+}
+```
+
+### AgentID announces itself:
+
+```go
+func AnnounceAgentRecord(
+    pub Publisher,
+    agent *AgentRecord,
+    leaderPubKey string,
+) error {
+    jsonPayload, err := agent.ToJSON()
+    if err != nil {
+        return err
+    }
+
+    encryptedPayload, err := EncryptPayload(jsonPayload, leaderPubKey)
+    if err != nil {
+        return err
+    }
+
+    ucxlAddress := "ucxl://any:admin@COOEE:enrol/#/agentid/" + 
+        fmt.Sprintf("%d", agent.AssignedID)
+
+    return pub.Publish(ucxlAddress, encryptedPayload)
+}
+```
+
+### AgentID subscriber handler:
+
+```go
+func SetupAgentIDListener(
+    sub Subscriber,
+    privateKey string,
+    handle func(*AgentRecord) error,
+) error {
+    ucxlAddress := "ucxl://any:admin@COOEE:enrol/#/agentid/*" // wildcard or prefix
+
+    return sub.Subscribe(ucxlAddress, func(data []byte) {
+        decrypted, err := DecryptPayload(data, privateKey)
+        if err != nil {
+            // handle error, log etc.
+            return
+        }
+        agent, err := FromJSON(decrypted)
+        if err != nil {
+            // handle error, log etc.
+            return
+        }
+        _ = handle(agent) // your context store merge or validation
+    })
+}
+```
+
+---
+
+## Summary
+
+- `AgentRecord` is your data model + JSON serialization
+    
+- Encryption/decryption uses `filippo.io/age` with armored output for easy text transfer
+    
+- Publish/subscribe interfaces let you plug into your existing UCXL transport layer
+    
+- `AnnounceAgentRecord` and `SetupAgentIDListener` provide idiomatic helpers to handle full lifecycle
+    
+
+---
+
+### Next step?
+
+- Do you want me to generate full Go source files for this with minimal deps and build instructions?
+    
+- Or help integrate this with your current CHORUS network code?
+    
+- Or maybe a CLI wrapper to test announce & listen?
+    
+
+Just say the word.
+
+Your `go.mod` looks solid and includes all the necessary dependencies for your CHORUS-related project, including:
+
+- `filippo.io/age` for encryption
+    
+- libp2p packages for p2p networking
+    
+- multiaddr and multiformats libs
+    
+- useful utilities and indirect dependencies for logging, protobuf, tracing, etc.
+    
+
+---
+
+### Next steps for your `agentid` package
+
+Given your `go.mod`, you have everything to:
+
+- Implement **AgentID structs and JSON serialization**
+    
+- Use **age** for encryption/decryption
+    
+- Integrate **UCXL publish/subscribe** on top of libp2p/pubsub
+    
+
+---
+
+### Recommended folder layout inside your repo
+
+```
+/agentid
+    agent.go        // AgentRecord struct + JSON marshal/unmarshal
+    crypto.go       // Age encrypt/decrypt functions
+    ucxl.go         // UCXL pub/sub wrappers using libp2p
+    registry.go     // Optional in-memory or persistent registry (if needed)
+    errors.go       // Custom error types (optional)
+```
+
+---
+
+### What you should do now
+
+1. Create your package files as above, one logical concern per file.
+    
+2. In each file, import your deps according to your `go.mod`.
+    
+3. Write unit tests for each component (serialization, crypto, pubsub).
+    
+4. Integrate your package into your main CHORUS/COOEE/SLURP app.
+    
+5. Use `go build` and `go test` to verify.
+    
+
+---
+
+### If you want, I can generate a full working minimal example package with:
+
+- AgentRecord struct + JSON
+    
+- Age encrypt/decrypt functions using `filippo.io/age`
+    
+- Simple pub/sub stub for UCXL using `libp2p-pubsub`
+    
+- Example unit tests
+    
diff --git a/DHT.md b/DHT.md
new file mode 100644
index 0000000..8cd1e69
--- /dev/null
+++ b/DHT.md
@@ -0,0 +1,116 @@
+The DHT Storage exists as a core component of the CHORUS architecture, used for distributed storage of encrypted content. It utilizes a distributed hash table (DHT) architecture, specifically based on libp2p, which supports decentralized, content-addressed storage and lookup capabilities. The DHT supports features such as caching, replication, and peer discovery, enabling high availability and fault tolerance across cluster nodes.
+
+The DHT storage is integrated into the system in several ways. It stores encrypted content in the network, with content stored across nodes to facilitate secure, distributed data management. Content stored in the DHT is verified for hash, size, encryption, and metadata integrity to ensure authenticity and confidentiality. The content is associated with content hashes, used as references for content addressing within the storage hierarchy. The system also manages replication of data (maintaining 3-5 node copies) for fault tolerance. Nodes participating in the network can announce, retrieve, and verify content, with performance metrics monitoring efficiency and cache hit rates.
+
+The DHT storage layer is accessed through entities such as content storage nodes and clients, which perform operations like store, retrieve, search, and get metrics. It also supports cryptographic protections, ensuring that stored content remains encrypted and secure, with metadata associated with raw content and backup data. Overall, the DHT storage provides decentralized, encrypted, and resilient data management essential for the secure operation of the CHORUS platform.
+
+# Encrypted compartments
+
+**Content-addressed, replicated, verified.** DHT persists encrypted context shards, with replication (3–5x) and integrity checks (hash/size/metadata) to make tampering and drift obvious. UCXL points _into_ these compartments; policy decides _if_ resolution occurs.
+
+References:
+[KG] Entities related to DHT Storage and its description (file_path not specified)
+[DC] Storage component details from "CHORUS-2B-ARCHITECTURE.md"
+
+## TODO
+
+- Runtime boundaries: Consolidate DHT documentation across CHORUS and RUSTLE; define APIs, ownership, and responsibilities.
+- Production usage: Ensure services use a production DHT implementation (not mocks); validate replication and metrics SLOs in CI.
+- Crypto guarantees: Verify end-to-end encryption and verifiability for UCXL content/metadata, including hash/size/metadata integrity checks.
+
+
+# Data Resilience with agent churn...
+
+Me: how resilient to data loss is our DHT given docker container churn? Or is this mitigated by volume binding the data persistence to another storage layer? I guess what I'm asking is if the loss of agents of a particular role would mean that data is encrypted on our DHT and spread across a number of machines in our swarm, would that data then be untrackable if the agent of that role no longer exists in the cluster?
+GPT-5:
+Short version: a DHT won’t save you from churn by itself. It gives *routing*, not *durability*. If containers die and you don’t deliberately persist and re-republish, your encrypted blobs can become “stranded” (still somewhere on disks, but effectively unfindable or undecryptable). You avoid that by (1) persisting node state outside containers, (2) replicating/pinning content across a quorum of nodes, and (3) decoupling discovery + keys from any single agent/role.
+
+Here’s a practical, CHORUS-flavoured breakdown.
+
+## What breaks under churn
+
+* **Ephemeral container storage**: if a DHT node’s datastore lives in the container FS, every redeploy wipes the routing tables, provider records, and any locally cached shards. You lose providers for your CIDs until someone reannounces.
+* **Provider records expire**: Kademlia/libp2p provider records are TTL’d. If no process re-publishes, content becomes *unroutable* even if replicas still exist on disk.
+* **Role-bound keys or indexes**: if only the “{role} agent” knows how to locate/decrypt artifacts (e.g., it holds the KEK or maintains the UCXL pointers), killing that role strands data.
+
+## What actually makes it resilient
+
+1. **Persist node state outside the container**
+
+   * Bind mount or named volumes for the DHT node’s datastore (routing tables, provider records, blockstore).
+   * In Swarm, use named volumes backed by real disks/NAS (NFS/ZFS/Ceph) rather than ephemeral layers.
+   * Pin your bootstrappers to specific hosts with `placement.constraints` so their on-disk stores survive redeploys.
+
+2. **Make availability a *policy*, not an accident**
+
+   * **Replication**: set a replication/pinning factor (e.g., r=5) per artifact or collection. Don’t rely on opportunistic caching.
+   * **Erasure coding**: store shards with Reed–Solomon (e.g., k=10, m=4). Any k of k+m shards reconstructs.
+   * **Pinning service**: run a small, role-agnostic “Pin Steward” service that enforces pinsets across a quorum (e.g., 3 of 5 designated storage nodes) and re-announces providers every BACKBEAT pulse.
+   * **Anti-entropy**: schedule periodic verify/repair jobs (sample CIDs, fetch, heal missing replicas).
+
+3. **Separate planes: data, index, and keys**
+
+   * **Data plane (DHT)**: encrypted, content-addressed blobs. DHT gives routing only.
+   * **Index plane (UCXL/registry)**: DRs and UCXL metadata carry the authoritative *pointers* (CIDs, shard manifests, checksum, retention, owners). This lives in a durable store (Raft/etcd, or a CRDT feed anchored to a small set of stateful nodes) and is not tied to a single role.
+   * **Key plane (age/envelope)**: per-artifact DEK + org-scoped KEK. Use *envelope encryption*:
+
+     * Encrypt data with a random DEK.
+     * Encrypt the DEK under a KEK controlled by org custody, **not** a single agent/role.
+     * Prefer threshold schemes: e.g., Shamir or age-wrapped multi-recipient policy: Security-Architect, Compliance, and TPM each hold shares; require 2-of-3 to recover.
+     * Store KEK metadata + recipient set in UCXL alongside the CID (never only in an agent’s private store).
+
+4. **Don’t bind capability to a role identity**
+
+   * Treat “roles” as *claims* over an org DID, not as key custodians. Agents can come and go; the org-level custody remains.
+   * Rotate claims freely; rotate keys carefully (KEK rotation with rewrap jobs scheduled on a BACKBEAT reverb).
+
+5. **Swarm-level hygiene**
+
+   * `deploy.update_config: order: start-first` to keep at least one replica online during updates.
+   * `restart_policy: condition: any` and healthchecks so nodes auto-return to the DHT.
+   * Node labels + `placement.constraints` to keep pinning nodes on storage-rich hosts.
+   * Back the volume with ZFS and snapshots; export via NFS/Ceph if you want cross-host mobility.
+   * Keep 3+ **stable bootstrap nodes** (stateful, fixed addresses) that never run on ephemeral volumes.
+
+6. **Lifecycle + BACKBEAT**
+
+   * On each beat:
+
+     * **Pulse**: Pin Steward re-announces providers for recently touched CIDs.
+     * **Reverb**: Run verify/repair, renew provider TTLs, and checkpoint UCXL indexes + key policy deltas.
+   * Garbage collection: never delete until UCXL’s retention policy says so and quorum confirms the DR tombstone.
+
+## Answering your core question
+
+> If the loss of agents of a particular role occurs, is the encrypted data on the DHT “untrackable”?
+
+* **It’s untrackable only if** (a) the UCXL index that maps concepts → CIDs was owned by that role alone, or (b) the KEK/recipient set lived solely with that role.
+* **It remains trackable and recoverable if** you:
+
+  * Keep UCXL pointers in the shared registry (replicated, role-agnostic).
+  * Use envelope encryption with threshold/org custody.
+  * Run a Pin Steward that republishes providers independently of any single agent.
+  * Persist DHT/blocks on host volumes and across multiple nodes.
+
+## Recommended defaults (sane, not dogma)
+
+* Replication factor: **r ≥ 5** across failure domains (different physical hosts).
+* Erasure coding: **k=10, m=4** for large artifacts; pure replication for small files/indices.
+* Pin quorum: **3 of 5** designated storage nodes.
+* Key policy: **2-of-3** threshold (Security-Architect, Compliance Officer, TPM).
+* Provider refresh: every **BACKBEAT** (e.g., 5–10 min) with jitter; hard renew at 1–2× the DHT provider TTL.
+* Bootstrap nodes: **3** stateful services, fixed host placement, ZFS-backed volumes, off the autoscaler.
+
+## What to change right now
+
+* Move every DHT/blockstore path to a **named volume** (ZFS dataset or NFS/Ceph) and pin bootstrappers via constraints.
+* Stand up the **Pin Steward** (tiny service) that:
+
+  * Watches UCXL for new/changed CIDs and desired r/k+m,
+  * Ensures pins across its quorum,
+  * Re-announces providers on Pulse/Reverb,
+  * Emits DRs when healing occurs.
+* Switch to **envelope encryption + threshold KEK**; remove role-exclusive custody.
+* Add a **UCXL “Beacon” index** (small, replicated KV) that maps logical addresses → latest CID/manifests so discovery never depends on an agent’s memory.
+
+Do those, and container churn becomes a nuisance, not a data-loss event. Without them, yes—you can strand perfectly good ciphertext all over your swarm with no reliable way to find or open it once that role is gone.