shugonet 0.5.0__tar.gz

shugonet-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SamurAI-Official
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shugonet-0.5.0/PKG-INFO

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: shugonet
+Version: 0.5.0
+Summary: Networking integration for connecting multiple Shugocore agents together for collaboration between Shugocore agents in simulation and physical spaces, designed to be used over 5G, 4G, EDGE, LoRa, Wifi-Halow, Wifi, and Bluetooth networks.
+Author: SamurAI-Official
+License: MIT
+Keywords: agent,networking,mesh,memory,fallback,shugocore
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ws
+Requires-Dist: websocket-client>=1.6; extra == "ws"
+Provides-Extra: relay
+Requires-Dist: requests>=2.32.0; extra == "relay"
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: ble
+Requires-Dist: bleak>=0.20; extra == "ble"
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.20; extra == "telemetry"
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
+Dynamic: license-file
+
+# Shogunet
+
+> Networking integration for connecting multiple Shugocore agents together for
+> collaboration between Shugocore agents in simulation and physical spaces,
+> designed to be used over 5G, 4G, EDGE, LoRa, Wifi-Halow, Wifi, and Bluetooth
+> networks.
+
+[![PyPI](https://img.shields.io/pypi/v/shugonet)](https://pypi.org/project/shugonet/)
+![Release](https://img.shields.io/badge/release-v0.5.0-blue)
+![Python](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue)
+![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Android%20%28Termux%2FChaquopy%29-lightgrey)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## Installation
+
+```bash
+pip install shugonet
+```
+
+The core is dependency-free (stdlib-only). Optional extras:
+
+```bash
+pip install shugonet[postgres]   # PostgreSQL mesh backend (PgSemanticMemory parity)
+pip install shugonet[ws]         # rosbridge-style WebSocket transport
+pip install shugonet[relay]      # HTTPS relay transport (5G/4G/EDGE)
+pip install shugonet[serial]     # LoRa SX126x/SX127x serial modules
+pip install shugonet[ble]        # BLE transport
+pip install shugonet[telemetry]  # OpenTelemetry integration
+```
+
+The compiled fleet dashboard ships inside the wheel — no JavaScript toolchain
+is needed at install time.
+
+Shogunet is the networking layer for [ShugoCore](https://github.com/SamurAI-Official/ShugoCore).
+It lets a fleet of ShugoCore agents — running in Gazebo simulation, on servers,
+on robots, or on Android handsets — discover each other, exchange tasks and
+events, and consolidate a *codependent* memory mesh, over whatever networks the
+mission has available, with deterministic fallback between them.
+
+## Design principles
+
+**One protocol, every network.** A single versioned envelope is spoken over all
+transports, from 5G to LoRa. Two codecs exist for it: a JSON codec for
+broadband links and a compact binary codec (16-byte header + TLV payload) for
+constrained links such as LoRa (0.3–27 kbit/s, ~220-byte frames) and BLE.
+
+**Memory invariants survive the network.** ShugoCore's memory tiers map to
+network tiers: Tier 0/1 never leave the agent (N0). Tier 2 semantic facts sync
+between paired agents (N1). Tier 3 is read-only everywhere: only *promotion
+proposals* travel, and application stays operator-attributed (N2).
+
+**Codependent memory.** Facts propagate with provenance
+`(origin_agent_id, fact_id)`; salience merges additively; pruning propagates as
+tombstones; and reinforcement is a *feedback loop* — when a peer's fact proves
+useful, a tiny `reinforce` message flows back so useful memories survive decay
+fleet-wide. Over LoRa, the loop runs on ~50-byte digest frames; bulk fact
+content moves later over any broadband link (digest anti-entropy).
+
+**Pairing is consent.** Only operator-allowlisted agent IDs pair, grants carry
+TTLs, topics are namespaced (`/shugunet/{agent_id}/{topic}`), and every
+ingress/egress field is sanitized and size-capped. Every network event lands in
+a hash-chained audit log.
+
+**Deterministic fallback.** Transports form an ordered, health-ranked chain
+with per-transport circuit breakers. If the LAN drops, traffic falls to the
+relay; if everything drops, a bounded store-and-forward WAL replays on
+reconnect. Total transport exhaustion latches the ShugoCore governor through
+its fallback triggers instead of failing silently.
+
+## Network tiers
+
+| Class | Networks | Protocol response |
+|---|---|---|
+| Broadband IP | 5G, 4G, WiFi | JSON codec, mesh query fan-out, bulk sync; LAN = direct TCP, cellular = relay hub |
+| Midband IP | EDGE, WiFi-Halow | Compact codec, batching, latency-tolerant profiles |
+| Constrained | LoRa | 16-byte header frames ≤ 220 B, P0/P1 priority only, digest anti-entropy, duty-cycle honored |
+| Short-range | Bluetooth (RFCOMM/BLE) | Stream framing or segmented compact codec; pairing-based discovery |
+
+Message priority classes: **P0** control (announce/heartbeat/ack/tombstone) →
+all links · **P1** memory deltas (facts/reinforce/digests) → constrained-capable
+· **P2** tasks and queries → IP links · **P3** bulk snapshots and audit
+shipping → broadband only, deferred under low power / thermal pressure.
+
+## Module map
+
+| Module | Responsibility |
+|---|---|
+| `protocol.py` | Envelope schema, 16-byte binary header, JSON + compact TLV codecs, segmentation, validation |
+| `transports.py` | `BaseTransport`, `LinkProfile` registry (7 networks + loopback), loopback bus |
+| `link_simulator.py` | In-process impairment: bandwidth, latency, jitter, loss, MTU, duty cycle |
+| `discovery.py` | Per-medium peer discovery (multicast beacons, hub rendezvous, pairing, duty-cycled LoRa) |
+| `agent_registry.py` | Pairing = consent, allowlists, TTL grants, topic ACLs, sim/phys manifests |
+| `tcp_transport.py` | Length-prefixed TCP transport with announce handshake (WiFi / WiFi-Halow profiles) |
+| `relay_transport.py` / `relay_server.py` | Cellular path: HTTPS relay hub + long-poll client (5G/4G/EDGE, cross-NAT) |
+| `lora_transport.py` | Serial SX126x/SX127x point-to-point transport (optional `pyserial`) |
+| `bluetooth_transport.py` | RFCOMM (AF_BLUETOOTH) and BLE (optional `bleak`) transports |
+| `transport_fallback.py` | Link-aware chain: eligibility, EWMA health ranking, breakers, QoS |
+| `store_forward.py` | Bounded JSONL WAL outbox/inbox with replay + dedup |
+| `memory_sync.py` / `mesh_query.py` | Codependent memory mesh: fact replication, conflict resolution, fan-out queries |
+| `audit.py`, `fallbacks.py`, `policy.py`, `telemetry.py` | ShugoCore-aligned safety surface |
+| `shugocore_bridge.py` | Adapter hosting a Shogunet node beside a ShugoCore `DecisionEngine` |
+
+## Hosting a fleet
+
+Shogunet runs as a single server process that owns the fleet's trust plane so
+every ShugoCore agent only needs a ~20-line client runtime to join.
+
+### Start a host
+
+```python
+from host import ShugonetHost
+
+host = ShugonetHost(agent_id="fleet-1", tcp_port=9000, relay_port=9001)
+host.start()
+
+# Grant consent to a joining agent (pairing = consent)
+host.pair("agent-001", manifest={"realm": "phys", "role": "perception"})
+
+print(host.status())   # roster, alive count, breaker health, mesh counts
+```
+
+Or from the CLI:
+
+```bash
+python3 host.py --tcp-port 9000 --relay-port 9001
+```
+
+### Join from a ShugoCore process
+
+```python
+from shugonet_runtime import ShugonetAgentRuntime
+
+runtime = ShugonetAgentRuntime(
+    agent_id="agent-001",
+    host_tcp_host="127.0.0.1",
+    host_tcp_port=9000,
+    host_relay_url="http://127.0.0.1:9001",
+    on_message=lambda sender, msg: print(f"from {sender}: {msg}"))
+runtime.connect_to_host()
+
+# Send a task to another agent
+runtime.send("agent-002", "/shugunet/agent-001/task",
+             {"action": "scan", "zone": "north"})
+
+# Search the fleet's memory
+results = runtime.query("obstacle in zone north")
+
+# Sync memory with the fleet
+runtime.sync()
+
+# Leave the fleet
+runtime.stop()
+```
+
+### Cross-platform CLI client
+
+Shogunet ships a standard CLI client that works on macOS, Linux, and Windows:
+
+```bash
+# Install (ships with the wheel)
+pip install shugonet
+
+# Connect and stay connected (foreground daemon)
+shugonet-client run
+
+# One-shot status
+shugonet-client status
+
+# One-shot send to a peer
+shugonet-client send agent-002 /shugunet/agent-001/task '{"action":"scan"}'
+
+# One-shot memory query
+shugonet-client query "obstacle in zone north"
+
+# One-shot digest sync
+shugonet-client sync agent-002
+```
+
+The client is configured via environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `SHUGONET_AGENT_ID` | hostname | Agent identifier |
+| `SHUGONET_HOST` | 127.0.0.1 | ShugonetHost address |
+| `SHUGONET_TCP_PORT` | 9000 | TCP port |
+| `SHUGONET_RELAY_URL` | *(none)* | Relay hub URL |
+| `SHUGONET_REALM` | phys | sim or phys realm |
+| `SHUGONET_LOG_LEVEL` | info | Log verbosity |
+
+Or use it programmatically:
+
+```python
+from shugonet_client import ShugonetClient
+
+client = ShugonetClient(agent_id="robot-1", host="10.0.0.5", tcp_port=9000)
+client.connect()
+client.send("robot-2", "/shugunet/robot-1/status", {"battery": 87})
+print(client.status())
+client.disconnect()
+```
+
+### Routing model
+
+Agents connect **to** the host (hub-and-spoke). The host forwards addressed
+mail to its recipient and fans broadcasts out as addressed copies to every
+other paired agent. Host-addressed mail — heartbeats, mesh queries, memory
+broadcasts — is processed locally by the host's own chain handlers.
+
+**Pairing is enforced twice** — at TCP admission (handshake hook) and again on
+every host-processed or forwarded envelope (the relay path has no registry gate
+of its own, so the host re-checks the sender there).
+
+### Failure semantics
+
+- **Agent crash/disconnect** → host governor latches `pause` (ShugoCore
+  deterministic latch contract).
+- **Message durability** → per-agent `OutboxStore` + `at_least_once` QoS + hub
+  mailbox TTL bounds.
+- **Cross-talk** → chain and mesh recipient guards (hardened in the
+  concurrency suite) hold at host scale.
+
+### Fleet dashboard
+
+Every `ShugunetHost` can expose an operator console — a compiled single-page
+app (TypeScript + SolidJS, built with Vite) served directly by the host over a
+loopback HTTP port. No JavaScript toolchain is needed at install time: the
+built assets ship inside the wheel (`shugonet_web/static`).
+
+```python
+host = ShugonetHost(agent_id="fleet-1", tcp_port=9000, relay_port=9001,
+                    dashboard_port=9002)
+host.start()
+# open http://127.0.0.1:9002 in a browser
+```
+
+The console streams a live event feed (Server-Sent Events), shows the roster,
+transport-chain health, memory-mesh counters, and audit-chain integrity, and
+exposes pair / unpair / resume / broadcast controls. State-changing POSTs are
+audited and can be gated by a token (`dashboard_token=...`).
+
+The SPA source lives in `dashboard/`; rebuild it with:
+
+```bash
+cd dashboard && npm ci && npm run build
+```
+
+## Module map (continued)
+
+| Module | Responsibility |
+|---|---|
+| `host.py` | `ShugunetHost`: admit paired agents, route traffic, seed the mesh |
+| `shugonet_runtime.py` | `ShugonetAgentRuntime`: client half a ShugoCore process instantiates |
+| `shugonet_client.py`  | `ShugonetClient`: cross-platform CLI and programmatic client |
+| `dashboard.py` | `DashboardServer`: stdlib HTTP operator plane (REST + SSE + SPA) |
+| `pg_store.py` | `PgFactStore`: optional PostgreSQL mesh backend (ShugoCore `PgSemanticMemory` parity) |
+
+## Testing
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+The suite is dependency-free and runs everywhere: transports are exercised
+through the loopback bus and the in-process link simulator, which models every
+network's bandwidth, latency, loss, MTU and duty-cycle constraints. The
+integration suite spins up a real `ShugonetHost` with multiple threaded
+`ShugonetAgentRuntime` clients, validates cross-talk isolation, memory
+convergence, peer-lost latching, and unpaired-agent refusal.
+
+## Changelog
+
+### 0.5.0
+
+- **ShugoCore 1.20.0 compatibility**: renamed ``agent_runtime.py`` to
+  ``shugonet_runtime.py`` to avoid naming collision with ShugoCore's own
+  ``agent_runtime`` module. All imports updated accordingly.
+- **Cross-platform CLI client**: ``shugonet-client`` command (installed by
+  ``pip``) with ``run``, ``status``, ``send``, ``query``, and ``sync``
+  subcommands. Configured via ``SHUGONET_*`` environment variables. Works
+  on macOS, Linux, and Windows.
+- **Standard programmatic client**: ``shugonet_client.ShugonetClient`` wraps
+  the full runtime in a simple ``connect()`` / ``send()`` / ``disconnect()``
+  interface.
+- Version bumped 0.4.0 → 0.5.0.
+
+### 0.4.0
+
+- **Fleet dashboard**: stdlib HTTP operator plane (`dashboard.py`) with a
+  compiled TypeScript + SolidJS SPA (`dashboard/` → `shugonet_web/static`).
+  Serves JSON REST, a live SSE event stream, and the console; ships inside the
+  wheel so no JS toolchain is needed at install time.
+- **ShugoCore memory compatibility**: fact schema aligned with
+  `SemanticMemory` / `PgSemanticMemory` columns (`kind`, `metadata`,
+  `created_at`); `pg_store.PgFactStore` mirrors mesh facts into PostgreSQL
+  (optional `postgres` extra).
+- **Version handshake**: `shugonet_version` + `protocol_version` exchanged at
+  TCP admission; mismatches emit a `version_mismatch` audit event and refuse
+  the join.
+- **Bridge sync test**: `tests/test_bridge_sync.py` keeps Shogunet's
+  `shugocore_adapter` and ShugoCore's vendored `shugonet_bridge` from drifting.
+- Version bumped 0.1.0 → 0.4.0.

shugonet-0.5.0/README.md

@@ -0,0 +1,301 @@
+# Shogunet
+
+> Networking integration for connecting multiple Shugocore agents together for
+> collaboration between Shugocore agents in simulation and physical spaces,
+> designed to be used over 5G, 4G, EDGE, LoRa, Wifi-Halow, Wifi, and Bluetooth
+> networks.
+
+[![PyPI](https://img.shields.io/pypi/v/shugonet)](https://pypi.org/project/shugonet/)
+![Release](https://img.shields.io/badge/release-v0.5.0-blue)
+![Python](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue)
+![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Android%20%28Termux%2FChaquopy%29-lightgrey)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## Installation
+
+```bash
+pip install shugonet
+```
+
+The core is dependency-free (stdlib-only). Optional extras:
+
+```bash
+pip install shugonet[postgres]   # PostgreSQL mesh backend (PgSemanticMemory parity)
+pip install shugonet[ws]         # rosbridge-style WebSocket transport
+pip install shugonet[relay]      # HTTPS relay transport (5G/4G/EDGE)
+pip install shugonet[serial]     # LoRa SX126x/SX127x serial modules
+pip install shugonet[ble]        # BLE transport
+pip install shugonet[telemetry]  # OpenTelemetry integration
+```
+
+The compiled fleet dashboard ships inside the wheel — no JavaScript toolchain
+is needed at install time.
+
+Shogunet is the networking layer for [ShugoCore](https://github.com/SamurAI-Official/ShugoCore).
+It lets a fleet of ShugoCore agents — running in Gazebo simulation, on servers,
+on robots, or on Android handsets — discover each other, exchange tasks and
+events, and consolidate a *codependent* memory mesh, over whatever networks the
+mission has available, with deterministic fallback between them.
+
+## Design principles
+
+**One protocol, every network.** A single versioned envelope is spoken over all
+transports, from 5G to LoRa. Two codecs exist for it: a JSON codec for
+broadband links and a compact binary codec (16-byte header + TLV payload) for
+constrained links such as LoRa (0.3–27 kbit/s, ~220-byte frames) and BLE.
+
+**Memory invariants survive the network.** ShugoCore's memory tiers map to
+network tiers: Tier 0/1 never leave the agent (N0). Tier 2 semantic facts sync
+between paired agents (N1). Tier 3 is read-only everywhere: only *promotion
+proposals* travel, and application stays operator-attributed (N2).
+
+**Codependent memory.** Facts propagate with provenance
+`(origin_agent_id, fact_id)`; salience merges additively; pruning propagates as
+tombstones; and reinforcement is a *feedback loop* — when a peer's fact proves
+useful, a tiny `reinforce` message flows back so useful memories survive decay
+fleet-wide. Over LoRa, the loop runs on ~50-byte digest frames; bulk fact
+content moves later over any broadband link (digest anti-entropy).
+
+**Pairing is consent.** Only operator-allowlisted agent IDs pair, grants carry
+TTLs, topics are namespaced (`/shugunet/{agent_id}/{topic}`), and every
+ingress/egress field is sanitized and size-capped. Every network event lands in
+a hash-chained audit log.
+
+**Deterministic fallback.** Transports form an ordered, health-ranked chain
+with per-transport circuit breakers. If the LAN drops, traffic falls to the
+relay; if everything drops, a bounded store-and-forward WAL replays on
+reconnect. Total transport exhaustion latches the ShugoCore governor through
+its fallback triggers instead of failing silently.
+
+## Network tiers
+
+| Class | Networks | Protocol response |
+|---|---|---|
+| Broadband IP | 5G, 4G, WiFi | JSON codec, mesh query fan-out, bulk sync; LAN = direct TCP, cellular = relay hub |
+| Midband IP | EDGE, WiFi-Halow | Compact codec, batching, latency-tolerant profiles |
+| Constrained | LoRa | 16-byte header frames ≤ 220 B, P0/P1 priority only, digest anti-entropy, duty-cycle honored |
+| Short-range | Bluetooth (RFCOMM/BLE) | Stream framing or segmented compact codec; pairing-based discovery |
+
+Message priority classes: **P0** control (announce/heartbeat/ack/tombstone) →
+all links · **P1** memory deltas (facts/reinforce/digests) → constrained-capable
+· **P2** tasks and queries → IP links · **P3** bulk snapshots and audit
+shipping → broadband only, deferred under low power / thermal pressure.
+
+## Module map
+
+| Module | Responsibility |
+|---|---|
+| `protocol.py` | Envelope schema, 16-byte binary header, JSON + compact TLV codecs, segmentation, validation |
+| `transports.py` | `BaseTransport`, `LinkProfile` registry (7 networks + loopback), loopback bus |
+| `link_simulator.py` | In-process impairment: bandwidth, latency, jitter, loss, MTU, duty cycle |
+| `discovery.py` | Per-medium peer discovery (multicast beacons, hub rendezvous, pairing, duty-cycled LoRa) |
+| `agent_registry.py` | Pairing = consent, allowlists, TTL grants, topic ACLs, sim/phys manifests |
+| `tcp_transport.py` | Length-prefixed TCP transport with announce handshake (WiFi / WiFi-Halow profiles) |
+| `relay_transport.py` / `relay_server.py` | Cellular path: HTTPS relay hub + long-poll client (5G/4G/EDGE, cross-NAT) |
+| `lora_transport.py` | Serial SX126x/SX127x point-to-point transport (optional `pyserial`) |
+| `bluetooth_transport.py` | RFCOMM (AF_BLUETOOTH) and BLE (optional `bleak`) transports |
+| `transport_fallback.py` | Link-aware chain: eligibility, EWMA health ranking, breakers, QoS |
+| `store_forward.py` | Bounded JSONL WAL outbox/inbox with replay + dedup |
+| `memory_sync.py` / `mesh_query.py` | Codependent memory mesh: fact replication, conflict resolution, fan-out queries |
+| `audit.py`, `fallbacks.py`, `policy.py`, `telemetry.py` | ShugoCore-aligned safety surface |
+| `shugocore_bridge.py` | Adapter hosting a Shogunet node beside a ShugoCore `DecisionEngine` |
+
+## Hosting a fleet
+
+Shogunet runs as a single server process that owns the fleet's trust plane so
+every ShugoCore agent only needs a ~20-line client runtime to join.
+
+### Start a host
+
+```python
+from host import ShugonetHost
+
+host = ShugonetHost(agent_id="fleet-1", tcp_port=9000, relay_port=9001)
+host.start()
+
+# Grant consent to a joining agent (pairing = consent)
+host.pair("agent-001", manifest={"realm": "phys", "role": "perception"})
+
+print(host.status())   # roster, alive count, breaker health, mesh counts
+```
+
+Or from the CLI:
+
+```bash
+python3 host.py --tcp-port 9000 --relay-port 9001
+```
+
+### Join from a ShugoCore process
+
+```python
+from shugonet_runtime import ShugonetAgentRuntime
+
+runtime = ShugonetAgentRuntime(
+    agent_id="agent-001",
+    host_tcp_host="127.0.0.1",
+    host_tcp_port=9000,
+    host_relay_url="http://127.0.0.1:9001",
+    on_message=lambda sender, msg: print(f"from {sender}: {msg}"))
+runtime.connect_to_host()
+
+# Send a task to another agent
+runtime.send("agent-002", "/shugunet/agent-001/task",
+             {"action": "scan", "zone": "north"})
+
+# Search the fleet's memory
+results = runtime.query("obstacle in zone north")
+
+# Sync memory with the fleet
+runtime.sync()
+
+# Leave the fleet
+runtime.stop()
+```
+
+### Cross-platform CLI client
+
+Shogunet ships a standard CLI client that works on macOS, Linux, and Windows:
+
+```bash
+# Install (ships with the wheel)
+pip install shugonet
+
+# Connect and stay connected (foreground daemon)
+shugonet-client run
+
+# One-shot status
+shugonet-client status
+
+# One-shot send to a peer
+shugonet-client send agent-002 /shugunet/agent-001/task '{"action":"scan"}'
+
+# One-shot memory query
+shugonet-client query "obstacle in zone north"
+
+# One-shot digest sync
+shugonet-client sync agent-002
+```
+
+The client is configured via environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `SHUGONET_AGENT_ID` | hostname | Agent identifier |
+| `SHUGONET_HOST` | 127.0.0.1 | ShugonetHost address |
+| `SHUGONET_TCP_PORT` | 9000 | TCP port |
+| `SHUGONET_RELAY_URL` | *(none)* | Relay hub URL |
+| `SHUGONET_REALM` | phys | sim or phys realm |
+| `SHUGONET_LOG_LEVEL` | info | Log verbosity |
+
+Or use it programmatically:
+
+```python
+from shugonet_client import ShugonetClient
+
+client = ShugonetClient(agent_id="robot-1", host="10.0.0.5", tcp_port=9000)
+client.connect()
+client.send("robot-2", "/shugunet/robot-1/status", {"battery": 87})
+print(client.status())
+client.disconnect()
+```
+
+### Routing model
+
+Agents connect **to** the host (hub-and-spoke). The host forwards addressed
+mail to its recipient and fans broadcasts out as addressed copies to every
+other paired agent. Host-addressed mail — heartbeats, mesh queries, memory
+broadcasts — is processed locally by the host's own chain handlers.
+
+**Pairing is enforced twice** — at TCP admission (handshake hook) and again on
+every host-processed or forwarded envelope (the relay path has no registry gate
+of its own, so the host re-checks the sender there).
+
+### Failure semantics
+
+- **Agent crash/disconnect** → host governor latches `pause` (ShugoCore
+  deterministic latch contract).
+- **Message durability** → per-agent `OutboxStore` + `at_least_once` QoS + hub
+  mailbox TTL bounds.
+- **Cross-talk** → chain and mesh recipient guards (hardened in the
+  concurrency suite) hold at host scale.
+
+### Fleet dashboard
+
+Every `ShugunetHost` can expose an operator console — a compiled single-page
+app (TypeScript + SolidJS, built with Vite) served directly by the host over a
+loopback HTTP port. No JavaScript toolchain is needed at install time: the
+built assets ship inside the wheel (`shugonet_web/static`).
+
+```python
+host = ShugonetHost(agent_id="fleet-1", tcp_port=9000, relay_port=9001,
+                    dashboard_port=9002)
+host.start()
+# open http://127.0.0.1:9002 in a browser
+```
+
+The console streams a live event feed (Server-Sent Events), shows the roster,
+transport-chain health, memory-mesh counters, and audit-chain integrity, and
+exposes pair / unpair / resume / broadcast controls. State-changing POSTs are
+audited and can be gated by a token (`dashboard_token=...`).
+
+The SPA source lives in `dashboard/`; rebuild it with:
+
+```bash
+cd dashboard && npm ci && npm run build
+```
+
+## Module map (continued)
+
+| Module | Responsibility |
+|---|---|
+| `host.py` | `ShugunetHost`: admit paired agents, route traffic, seed the mesh |
+| `shugonet_runtime.py` | `ShugonetAgentRuntime`: client half a ShugoCore process instantiates |
+| `shugonet_client.py`  | `ShugonetClient`: cross-platform CLI and programmatic client |
+| `dashboard.py` | `DashboardServer`: stdlib HTTP operator plane (REST + SSE + SPA) |
+| `pg_store.py` | `PgFactStore`: optional PostgreSQL mesh backend (ShugoCore `PgSemanticMemory` parity) |
+
+## Testing
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+The suite is dependency-free and runs everywhere: transports are exercised
+through the loopback bus and the in-process link simulator, which models every
+network's bandwidth, latency, loss, MTU and duty-cycle constraints. The
+integration suite spins up a real `ShugonetHost` with multiple threaded
+`ShugonetAgentRuntime` clients, validates cross-talk isolation, memory
+convergence, peer-lost latching, and unpaired-agent refusal.
+
+## Changelog
+
+### 0.5.0
+
+- **ShugoCore 1.20.0 compatibility**: renamed ``agent_runtime.py`` to
+  ``shugonet_runtime.py`` to avoid naming collision with ShugoCore's own
+  ``agent_runtime`` module. All imports updated accordingly.
+- **Cross-platform CLI client**: ``shugonet-client`` command (installed by
+  ``pip``) with ``run``, ``status``, ``send``, ``query``, and ``sync``
+  subcommands. Configured via ``SHUGONET_*`` environment variables. Works
+  on macOS, Linux, and Windows.
+- **Standard programmatic client**: ``shugonet_client.ShugonetClient`` wraps
+  the full runtime in a simple ``connect()`` / ``send()`` / ``disconnect()``
+  interface.
+- Version bumped 0.4.0 → 0.5.0.
+
+### 0.4.0
+
+- **Fleet dashboard**: stdlib HTTP operator plane (`dashboard.py`) with a
+  compiled TypeScript + SolidJS SPA (`dashboard/` → `shugonet_web/static`).
+  Serves JSON REST, a live SSE event stream, and the console; ships inside the
+  wheel so no JS toolchain is needed at install time.
+- **ShugoCore memory compatibility**: fact schema aligned with
+  `SemanticMemory` / `PgSemanticMemory` columns (`kind`, `metadata`,
+  `created_at`); `pg_store.PgFactStore` mirrors mesh facts into PostgreSQL
+  (optional `postgres` extra).
+- **Version handshake**: `shugonet_version` + `protocol_version` exchanged at
+  TCP admission; mismatches emit a `version_mismatch` audit event and refuse
+  the join.
+- **Bridge sync test**: `tests/test_bridge_sync.py` keeps Shogunet's
+  `shugocore_adapter` and ShugoCore's vendored `shugonet_bridge` from drifting.
+- Version bumped 0.1.0 → 0.4.0.