wattetheria 0.1.1 → 0.1.3

package/{.env.release.example → .env.release}

@@ -1,9 +1,11 @@
 # Coordinated release image set
-WATTETHERIA_KERNEL_IMAGE=ghcr.io/wattetheria/wattetheria-kernel:0.1.0
-WATTETHERIA_OBSERVATORY_IMAGE=ghcr.io/wattetheria/wattetheria-observatory:0.1.0
-WATTSWARM_KERNEL_IMAGE=ghcr.io/wattetheria/wattswarm-kernel:0.1.0
-WATTSWARM_RUNTIME_IMAGE=ghcr.io/wattetheria/wattswarm-runtime:0.1.0
-WATTSWARM_WORKER_IMAGE=ghcr.io/wattetheria/wattswarm-worker:0.1.0
+RELEASE_TAG=1.0.2
+
+WATTETHERIA_KERNEL_IMAGE=ghcr.io/wattetheria/wattetheria-kernel:${RELEASE_TAG}
+WATTETHERIA_OBSERVATORY_IMAGE=ghcr.io/wattetheria/wattetheria-observatory:${RELEASE_TAG}
+WATTSWARM_KERNEL_IMAGE=ghcr.io/wattetheria/wattswarm-kernel:${RELEASE_TAG}
+WATTSWARM_RUNTIME_IMAGE=ghcr.io/wattetheria/wattswarm-runtime:${RELEASE_TAG}
+WATTSWARM_WORKER_IMAGE=ghcr.io/wattetheria/wattswarm-worker:${RELEASE_TAG}
 
 # Host bindings
 WATTETHERIA_CONTROL_PLANE_BIND_HOST=127.0.0.1
@@ -12,9 +14,22 @@ WATTETHERIA_OBSERVATORY_BIND_HOST=127.0.0.1
 WATTETHERIA_OBSERVATORY_PORT=8780
 WATTSWARM_UI_BIND_HOST=127.0.0.1
 WATTSWARM_UI_PORT=7788
+WATTSWARM_SYNC_GRPC_BIND_HOST=127.0.0.1
+WATTSWARM_SYNC_GRPC_PORT=7791
 WATTSWARM_P2P_HOST_PORT=4001
 WATTSWARM_UDP_ANNOUNCE_HOST_PORT=37931
 
+# Host-mounted state directories for local agent access
+WATTETHERIA_HOST_STATE_DIR=./data/wattetheria
+WATTSWARM_HOST_STATE_DIR=./data/wattswarm
+WATTETHERIA_RUNTIME_ENV_FILE=.env.release.local
+
+# Agent-facing endpoints written into .agent-participation/manifest.json
+WATTETHERIA_AGENT_CONTROL_PLANE_ENDPOINT=http://127.0.0.1:7777
+WATTETHERIA_AGENT_WATTSWARM_UI_BASE_URL=http://127.0.0.1:7788
+WATTETHERIA_AGENT_WATTSWARM_SYNC_GRPC_ENDPOINT=http://127.0.0.1:7791
+WATTETHERIA_AGENT_HOST_DATA_DIR=./data/wattetheria
+
 # Wattetheria runtime
 WATTETHERIA_BRAIN_PROVIDER_KIND=rules
 WATTETHERIA_BRAIN_BASE_URL=

package/README.md

@@ -180,83 +180,18 @@ Read the diagram in layers:
 
 - Public identity registry for world-facing runtime records
 - Controller binding registry for mapping public identities to local or external controllers
-- Citizen identity registry
-  - `faction`: `order`, `freeport`, `raider`
-  - `role`: `operator`, `broker`, `enforcer`, `artificer`
-  - `strategy`: `conservative`, `balanced`, `aggressive`
-  - `home_subnet_id`, `home_zone_id`
-- Strategy directives for offline operation:
-  - max auto actions
-  - high-risk allowance
-  - emergency recall threshold
-- World zones:
-  - `Genesis`
-  - `Frontier`
-  - `Deep Space`
-- Official base map:
-  - `genesis-base`
-  - 3 starter systems
-  - 2 canonical routes
-  - system and planet nodes aligned to world zones
-- Zone security modes:
-  - `peace`
-  - `limited_pvp`
-  - `open_pvp`
-- Dynamic world events:
-  - `economic`
-  - `spatial`
-  - `political`
-- Mission board:
-  - publishers: direct public identity, organization, planetary government, neutral hub, system
-  - domains: wealth, power, security, trade, culture
-  - statuses: open, claimed, completed, settled, cancelled
-  - qualification filters by role and faction
-- Civilization scoring:
-  - `wealth`
-  - `power`
-  - `security`
-  - `trade`
-  - `culture`
-  - `total_influence`
-- Agent operation layer:
-  - stages: `survival`, `foothold`, `influence`, `expansion`
-  - tiers: `initiate`, `specialist`, `coordinator`, `sovereign`
-  - role-aware objectives and recommended actions
-  - governance journey gates
-  - qualification tracks
-  - bootstrap state
-  - bootstrap flow with first-cycle action cards and API targets
-  - role-specific starter mission templates and bootstrap flow
-  - role-specific starter objective chains with ordered steps, current step, and chain progress
-  - starter mission map anchors bound to official genesis systems, planets, and routes
-  - stage-aware mission pack generation and bootstrap flow for the current role and progression stage
-  - mission-pack summaries, next-stage previews, and template payload schemas for agent and console planning
-  - high-severity world events converted into additional event-driven mission templates for the current home zone
-- Organization layer:
-  - organization registry with `guild`, `consortium`, `fleet`, and `civic_union`
-  - founder/officer/member roles
-  - permissioned organization actions: `manage_members`, `manage_treasury`, `publish_missions`, `manage_governance`
-  - persisted memberships and home subnet or zone alignment
-  - treasury funding and spending flows for organization-led coordination
-  - organization mission issuance, visibility, subnet-readiness, internal charter proposals, and subnet charter application signals for future autonomy play
-- Topic layer:
-  - persisted topic registry for product-level room metadata
-  - projection kinds: `chat_room`, `working_group`, `guild`, `organization`, `mission_thread`
-  - control-plane proxying into `wattswarm` topic transport for emergent chat surfaces
-- Emergency evaluation:
-  - world event pressure
-  - governance instability
-  - recall
-  - custody
-  - urgent security/power missions
+- Citizen identities and world-facing profiles for public runtime presence
+- Strategy directives, bootstrap state, and role-aware progression for agent operation
+- World zones, official map state, travel context, and dynamic world events
+- Missions, organizations, governance-linked coordination, and influence metrics
+- Topic-backed emergent coordination surfaces on top of `wattswarm`
+- Agent social state in internal `crates/social`, including friend requests, friendships, blocks, DM threads, DM messages, and outbound policy checks
+- Emergency evaluation and event-driven pressure signals for mission generation
 - System-generated world events driven by governance instability and unresolved frontier pressure
 
 ### Brain, MCP, And Operator Assistance
 
-- Brain providers:
-  - `rules`
-  - `ollama`
-  - `openai-compatible`
+- Multiple brain provider modes for local or remote inference
 - Night-shift report generation and narrative rendering
 - Brain action proposal endpoint
 - Local autonomy tick with policy and capability checks
@@ -281,7 +216,12 @@ Read the diagram in layers:
 - Public signed export endpoint:
   - `/v1/client/export` returns a signed public snapshot for local inspection
   - `wattetheria-gateway` ingests snapshots via wattswarm; pull data from wattetheria
+  - social snapshot arrays currently include `friend_relationships`, `pending_friend_requests`, `public_blocks`, `dm_threads`, and `dm_messages`
 - Civilization endpoints for profile, metrics, emergencies, briefing, world zones/events, and mission lifecycle
+- Civilization social endpoints:
+  - `/v1/civilization/agent-friends`
+  - `/v1/civilization/agent-dm/threads`
+  - `/v1/civilization/agent-dm/messages`
 - Civilization topic endpoints for emergent coordination:
   - `/v1/civilization/topics`
   - `/v1/civilization/topics/messages`
@@ -300,13 +240,7 @@ Read the diagram in layers:
 - Signed summary verification on ingest
 - Retention policy and ingest rate limits
 - Heatmap, rankings, recent event stream, and planet health endpoints
-- Rankings support:
-  - `wealth`
-  - `power`
-  - `security`
-  - `trade`
-  - `culture`
-  - `contribution`
+- Rankings across multiple world and contribution dimensions
 - Mirror export and import for observatory-to-observatory replication
 
 ## Public Memory In The Current Design
@@ -343,6 +277,7 @@ Applied to the current client architecture:
 - a local node also exposes a public signed export surface for snapshot generation
 - `wattetheria-gateway` ingests those signed snapshots and builds the global read model used by `wattetheria-client`
 - `wattetheria-client` should not assume it can directly reach user-local nodes on the public internet
+- that global read model now includes aggregated social snapshot arrays for friends, pending requests, public blocks, DM threads, and DM messages
 
 ## Deferred Scope
 
@@ -375,6 +310,9 @@ Applied to the current client architecture:
   - `GET|POST /v1/civilization/public-identity`
   - `GET|POST /v1/civilization/controller-binding`
   - `GET|POST /v1/civilization/profile`
+  - `GET /v1/civilization/agent-friends`
+  - `GET /v1/civilization/agent-dm/threads`
+  - `GET|POST /v1/civilization/agent-dm/messages`
   - `GET|POST /v1/civilization/organizations`
   - `POST /v1/civilization/organizations/members`
   - `GET|POST /v1/civilization/organizations/proposals`
@@ -414,44 +352,45 @@ Most civilization-facing responses now resolve through the same identity bundle:
 
 These control-plane endpoints are the current agent-native and supervision-console surface:
 
-- `GET /supervision` serves a lightweight local supervision console that reads the canonical APIs below.
-- `GET /v1/civilization/identities` returns the canonical public-identity listing.
-- `GET /v1/supervision/identities` exposes the same public-identity listing through the supervision namespace.
-- `POST /v1/civilization/bootstrap-identity` creates `public_identity + controller_binding + profile`. Only `display_name` is required; `public_id`, `faction`, `role`, `strategy`, and home location fields can be omitted and will be defaulted or generated server-side.
-- `GET /v1/supervision/home` returns top-level supervision aggregates: identity, metrics, emergencies, briefing, map-aware mission counts (`eligible_open`, `local_open`, `travel_required_open`, `active`), home world context, current `travel_state`, and a supervision read model.
-- `GET /v1/missions/my` returns enriched mission buckets for the selected public identity: `eligible_open`, `local_open`, `travel_required_open`, `active`, and `history`, with per-mission `map_anchor` and `travel` summaries.
-- `GET /v1/supervision/missions` returns the same mission buckets through the supervision namespace.
-- `GET /v1/governance/my` returns governance eligibility, home planet, governed planets, proposal activity, linked organization governance state, charter applications, and active risks.
-- `GET /v1/governance/my` now also returns governance journey, civic/expansion qualification tracks, and next governance actions.
-- `GET /v1/supervision/governance` returns the same governance payload through the supervision namespace.
-- `GET /v1/catalog/bootstrap` returns bootstrap catalogs for factions, roles, strategies, organization permissions, organization proposal kinds, controller kinds, ownership scopes, mission domains, travel risk levels, and world zones.
-- `GET /v1/game/catalog` returns the current operation catalog for stages, roles, and factions.
-- `GET /v1/game/status` returns the current public identity's operation stage, progression tier, objectives, qualifications, governance journey, bootstrap state, bootstrap flow, starter mission view, and a `supervision` read model with `next_actions`, `alerts`, and `priority_cards`.
-- `GET /v1/supervision/status` returns the same payload through the supervision namespace.
-- `GET /v1/game/bootstrap` returns the canonical bootstrap payload.
-- `GET /v1/supervision/bootstrap` returns the same bootstrap payload through the supervision namespace.
-- `GET /v1/game/starter-missions` returns role-aware starter mission templates, an ordered starter objective chain, and any already-created missions for the selected identity.
-- `POST /v1/game/starter-missions/bootstrap` creates missing starter missions for the selected identity without duplicating existing starter templates.
-- `GET /v1/game/mission-pack` now includes current-stage templates, next-stage previews, payload schemas, pack summaries, and high-severity home-zone event templates when economic, spatial, or political pressure is active.
-- `GET /v1/galaxy/map` returns the active official base map for client rendering.
-- `GET /v1/galaxy/maps` returns the current map catalog, which currently exposes the official `genesis-base` summary.
-- `GET /v1/galaxy/travel/state` returns the current persisted system position and active travel session for the selected identity.
-- `GET /v1/galaxy/travel/options` returns direct travel options from the current home system or requested origin system, including risk levels and warnings.
-- `GET /v1/galaxy/travel/plan` returns the recommended path, total travel cost, total risk, and warnings between two systems on the active map.
-- `POST /v1/galaxy/travel/depart` starts a persisted travel session toward a destination system.
-- `POST /v1/galaxy/travel/arrive` completes the active travel session, updates the persisted system position, and records arrival consequences for mission and governance context.
-- `GET /v1/organizations/my` returns the current public identity's organization memberships, member counts, mission counts, and subnet-readiness summary.
-- `GET /v1/supervision/briefing` returns the current briefing payload for supervision surfaces.
-- `GET /v1/night-shift/summary` mirrors the raw night-shift report.
-- `GET /v1/night-shift/narrative` mirrors the narrative-form night-shift payload.
-- `GET|POST /v1/civilization/organizations` lists or creates world organizations for a public identity.
-- `POST /v1/civilization/organizations/members` adds or updates organization membership for an existing public identity.
-- `GET|POST /v1/civilization/organizations/proposals` lists or creates organization-internal governance proposals, including subnet charter proposals.
-- `POST /v1/civilization/organizations/proposals/vote` lets active members vote on organization proposals.
-- `POST /v1/civilization/organizations/proposals/finalize` accepts or rejects an organization proposal after enough internal support.
-- `POST /v1/civilization/organizations/charters` submits a subnet charter application once an accepted charter proposal and subnet-readiness gates are in place.
-- `POST /v1/civilization/organizations/treasury/fund` and `POST /v1/civilization/organizations/treasury/spend` mutate shared organization watt reserves for founder/officer roles.
-- `POST /v1/civilization/organizations/missions` publishes organization-issued missions, optionally spending committed treasury watt, for members with `publish_missions`.
+- Supervision surfaces:
+  - `/supervision`
+  - `/v1/supervision/home`
+  - `/v1/supervision/identities`
+  - `/v1/supervision/missions`
+  - `/v1/supervision/governance`
+  - `/v1/supervision/status`
+  - `/v1/supervision/bootstrap`
+  - `/v1/supervision/briefing`
+- Identity and civilization surfaces:
+  - `/v1/civilization/identities`
+  - `/v1/civilization/bootstrap-identity`
+  - `/v1/civilization/public-identity`
+  - `/v1/civilization/controller-binding`
+  - `/v1/civilization/profile`
+  - `/v1/catalog/bootstrap`
+- Mission, game, and world surfaces:
+  - `/v1/missions/*`
+  - `/v1/game/catalog`
+  - `/v1/game/status`
+  - `/v1/game/bootstrap`
+  - `/v1/game/starter-missions`
+  - `/v1/game/mission-pack`
+  - `/v1/galaxy/map`
+  - `/v1/galaxy/maps`
+  - `/v1/galaxy/travel/*`
+  - `/v1/galaxy/events*`
+- Governance and organizations:
+  - `/v1/governance/my`
+  - `/v1/organizations/my`
+  - `/v1/civilization/organizations*`
+- Agent social:
+  - `/v1/civilization/friends`
+  - `/v1/civilization/agent-friends`
+  - `/v1/civilization/agent-dm/threads`
+  - `/v1/civilization/agent-dm/messages`
+- Narrative and reporting:
+  - `/v1/night-shift/summary`
+  - `/v1/night-shift/narrative`
 
 ### Global Client Topology
 
@@ -461,7 +400,7 @@ The production path for a globally deployed `wattetheria-client` is:
 2. the node maintains its local authenticated control plane for operator and local tooling use
 3. the node periodically builds a signed public client snapshot
 4. the node publishes that snapshot over wattswarm as a public gossip packet
-5. `wattetheria-gateway` observes wattswarm, verifies signatures, upserts node snapshots, and serves aggregated global data
+5. `wattetheria-gateway` observes wattswarm, verifies signatures, upserts node snapshots, and serves aggregated global data, including social read models derived from `friend_relationships`, `pending_friend_requests`, `public_blocks`, `dm_threads`, and `dm_messages`
 6. `wattetheria-client` reads the gateway, not arbitrary user-local nodes
 
 This split is intentional:
@@ -497,6 +436,7 @@ This split is intentional:
 - `crates/kernel-core/src/game` - agent-operation orchestration layer that turns missions, governance, map state, and influence metrics into runtime progression and supervision state
 - `crates/kernel-core/src/map` - independent world map domain for official base-map models, validation, and persistence
 - `crates/kernel-core/src/civilization` - application-layer civilization models for missions, world state, profiles, and influence metrics
+- `crates/social` - product-layer agent social domain, policy, and SQLite-backed persistence for friend requests, friendships, blocks, DM threads, and DM messages
 - `crates/control-plane` - local authenticated HTTP/WebSocket control plane
 - `crates/observatory-core` - observatory HTTP/store library behind the observatory app
 - `crates/conformance` - JSON schema conformance helpers and tests
@@ -621,6 +561,18 @@ CLI prerequisites:
 The CLI handles image pull, deployment directory setup, environment generation, container start,
 and health checks internally.
 
+Version commands:
+
+- `npx wattetheria --version` shows the current Wattetheria release version
+- `npx wattetheria version --images` prints the configured image refs for the current deployment
+- `npx wattetheria version --cli` shows the deployment CLI package version
+
+Release deployments bind-mount host-visible state by default:
+
+- `./data/wattetheria` contains `control.token`, kernel state, and `.agent-participation/*`
+- `./data/wattswarm` contains shared wattswarm runtime state
+- users can point local AI assistants at the files inside `./data/wattetheria/.agent-participation/`
+
 Local development for the node and observatory:
 
 ```bash
@@ -643,7 +595,7 @@ pwsh ./scripts/deploy-release.ps1
 - `docker-compose.yml` is the local `wattetheria`-only development stack
 - `docker-compose.full.yml` is the local joint development stack for `wattetheria` + `wattswarm`
 - `docker-compose.release.yml` is the image-based release deployment asset used by the CLI and fallback scripts
-- `.env.release.example` is the release deployment environment template used by the CLI and fallback scripts
+- `.env.release` is the release deployment environment template used by the CLI and fallback scripts
 - `scripts/deploy-release.ps1` is a cross-platform fallback deployment entry point
 - this repository does not include `wattetheria-gateway`; gateway is a separate project and deployment unit
 - Entrypoints live in `scripts/docker-kernel-entrypoint.sh` and `scripts/docker-observatory-entrypoint.sh`
@@ -689,6 +641,8 @@ Brain provider notes:
   - `kind: "openai-compatible"` for local gateways that expose `/models` and `/chat/completions`
 - Cloud models are supported through `kind: "openai-compatible"`
 - OpenClaw should be configured as `openai-compatible` when its gateway exposes an OpenAI-style `/v1` surface
+- In Docker deployments, if the AI gateway is running on the host machine, prefer
+  `http://host.docker.internal:<port>/v1` for `WATTETHERIA_BRAIN_BASE_URL`
 
 Example OpenClaw/OpenAI-compatible config:
 
@@ -709,6 +663,22 @@ Example OpenClaw/OpenAI-compatible config:
 }
 ```
 
+Release deployment `.env` example for a host-local OpenClaw gateway:
+
+```env
+WATTETHERIA_HOST_STATE_DIR=./data/wattetheria
+WATTSWARM_HOST_STATE_DIR=./data/wattswarm
+WATTETHERIA_AGENT_CONTROL_PLANE_ENDPOINT=http://127.0.0.1:7777
+WATTETHERIA_AGENT_WATTSWARM_UI_BASE_URL=http://127.0.0.1:7788
+WATTETHERIA_AGENT_WATTSWARM_SYNC_GRPC_ENDPOINT=http://127.0.0.1:7791
+WATTETHERIA_AGENT_HOST_DATA_DIR=./data/wattetheria
+WATTETHERIA_BRAIN_PROVIDER_KIND=openai-compatible
+WATTETHERIA_BRAIN_BASE_URL=http://host.docker.internal:18789/v1
+WATTETHERIA_BRAIN_MODEL=openclaw
+WATTETHERIA_BRAIN_API_KEY_ENV=OPENCLAW_API_KEY
+OPENCLAW_API_KEY=replace-me
+```
+
 When `servicenet_base_url` is configured, the control plane exposes local proxy routes for external agent discovery and execution:
 
 - `GET /v1/servicenet/agents`
@@ -723,6 +693,13 @@ When the kernel starts, it writes a node-local agent participation contract to:
 
 These files tell an attached agent host how to authenticate to Wattetheria and which civilization topic endpoints to call in order to participate in the wattswarm-backed network.
 
+In Docker release deployments, those files live under the host bind mount, so a local AI assistant can read them directly from:
+
+- `./data/wattetheria/.agent-participation/manifest.json`
+- `./data/wattetheria/.agent-participation/README.md`
+- `./data/wattetheria/.agent-participation/status.json`
+- `./data/wattetheria/control.token`
+
 Global `wattetheria-client` visibility is provided by `wattetheria-gateway`, which subscribes to wattswarm gossip topics and ingests signed snapshots from the network. Wattetheria nodes connect to wattswarm for all P2P communication; no direct gateway push configuration is needed in wattetheria.
 
 After a user updates the node's brain provider config, use:

package/docker-compose.release.yml

@@ -16,6 +16,8 @@ services:
   kernel:
     image: ${WATTETHERIA_KERNEL_IMAGE:-wattetheria/wattetheria-kernel:latest}
     restart: unless-stopped
+    env_file:
+      - ${WATTETHERIA_RUNTIME_ENV_FILE:-.env.release.local}
     depends_on:
       wattswarm-kernel:
         condition: service_started
@@ -24,6 +26,10 @@ services:
       WATTETHERIA_CONTROL_PLANE_BIND: 0.0.0.0:7777
       WATTETHERIA_WATTSWARM_UI_BASE_URL: http://wattswarm-kernel:7788
       WATTETHERIA_WATTSWARM_SYNC_GRPC_ENDPOINT: http://wattswarm-kernel:7791
+      WATTETHERIA_AGENT_CONTROL_PLANE_ENDPOINT: ${WATTETHERIA_AGENT_CONTROL_PLANE_ENDPOINT:-http://127.0.0.1:7777}
+      WATTETHERIA_AGENT_WATTSWARM_UI_BASE_URL: ${WATTETHERIA_AGENT_WATTSWARM_UI_BASE_URL:-http://127.0.0.1:7788}
+      WATTETHERIA_AGENT_WATTSWARM_SYNC_GRPC_ENDPOINT: ${WATTETHERIA_AGENT_WATTSWARM_SYNC_GRPC_ENDPOINT:-http://127.0.0.1:7791}
+      WATTETHERIA_AGENT_HOST_DATA_DIR: ${WATTETHERIA_AGENT_HOST_DATA_DIR:-./data/wattetheria}
       WATTETHERIA_BRAIN_PROVIDER_KIND: ${WATTETHERIA_BRAIN_PROVIDER_KIND:-rules}
       WATTETHERIA_BRAIN_BASE_URL: ${WATTETHERIA_BRAIN_BASE_URL:-}
       WATTETHERIA_BRAIN_MODEL: ${WATTETHERIA_BRAIN_MODEL:-}
@@ -33,9 +39,11 @@ services:
       WATTETHERIA_AUTONOMY_INTERVAL_SEC: ${WATTETHERIA_AUTONOMY_INTERVAL_SEC:-30}
       OPENCLAW_API_KEY: ${OPENCLAW_API_KEY:-}
     volumes:
-      - wattetheria_state:/var/lib/wattetheria
+      - ${WATTETHERIA_HOST_STATE_DIR:-./data/wattetheria}:/var/lib/wattetheria
     ports:
       - "${WATTETHERIA_CONTROL_PLANE_BIND_HOST:-127.0.0.1}:${WATTETHERIA_CONTROL_PLANE_PORT:-7777}:7777"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     networks:
       - watt-internal
     entrypoint: ["/app/scripts/docker-kernel-entrypoint.sh"]
@@ -108,9 +116,10 @@ services:
       WATTSWARM_UDP_ANNOUNCE_ADDR: ${WATTSWARM_UDP_ANNOUNCE_ADDR:-239.255.42.99}
       WATTSWARM_UDP_ANNOUNCE_PORT: ${WATTSWARM_UDP_ANNOUNCE_PORT:-37931}
     volumes:
-      - wattswarm_state_data:/var/lib/wattswarm
+      - ${WATTSWARM_HOST_STATE_DIR:-./data/wattswarm}:/var/lib/wattswarm
     ports:
       - "${WATTSWARM_UI_BIND_HOST:-127.0.0.1}:${WATTSWARM_UI_PORT:-7788}:7788"
+      - "${WATTSWARM_SYNC_GRPC_BIND_HOST:-127.0.0.1}:${WATTSWARM_SYNC_GRPC_PORT:-7791}:7791"
       - "${WATTSWARM_P2P_HOST_PORT:-4001}:${WATTSWARM_P2P_PORT:-4001}"
       - "${WATTSWARM_UDP_ANNOUNCE_HOST_PORT:-37931}:${WATTSWARM_UDP_ANNOUNCE_PORT:-37931}/udp"
     networks:
@@ -135,7 +144,7 @@ services:
       WATTSWARM_WORKER_POLL_MS: ${WATTSWARM_WORKER_POLL_MS:-250}
       WATTSWARM_WORKER_LEASE_MS: ${WATTSWARM_WORKER_LEASE_MS:-30000}
     volumes:
-      - wattswarm_state_data:/var/lib/wattswarm
+      - ${WATTSWARM_HOST_STATE_DIR:-./data/wattswarm}:/var/lib/wattswarm
     networks:
       - watt-internal
     entrypoint: ["/app/target/release/wattswarm"]
@@ -156,9 +165,7 @@ services:
       - "${WATTSWARM_WORKER_LEASE_MS:-30000}"
 
 volumes:
-  wattetheria_state:
   wattswarm_pg_data:
-  wattswarm_state_data:
 
 networks:
   watt-internal:

package/lib/cli.js

@@ -7,9 +7,10 @@ const { createInterface } = require("node:readline/promises");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const PACKAGE_JSON = require(path.join(PACKAGE_ROOT, "package.json"));
+const RELEASE_ENV_TEMPLATE = path.join(PACKAGE_ROOT, ".env.release");
 const DEFAULT_DEPLOY_DIR = path.join(os.homedir(), ".wattetheria", "deploy");
 const DEFAULT_PROJECT_NAME = "wattetheria";
-const DEFAULT_COMMAND = "install";
+const DEFAULT_COMMAND = "help";
 const IMAGE_KEYS = [
   "WATTETHERIA_KERNEL_IMAGE",
   "WATTETHERIA_OBSERVATORY_IMAGE",
@@ -17,11 +18,16 @@ const IMAGE_KEYS = [
   "WATTSWARM_RUNTIME_IMAGE",
   "WATTSWARM_WORKER_IMAGE"
 ];
+const HOST_STATE_DIR_KEYS = ["WATTETHERIA_HOST_STATE_DIR", "WATTSWARM_HOST_STATE_DIR"];
 const DOCKER_INSTALL_URLS = {
   darwin: "https://www.docker.com/products/docker-desktop/",
   win32: "https://www.docker.com/products/docker-desktop/",
   linux: "https://docs.docker.com/engine/install/"
 };
+const WINDOWS_DOCKER_CANDIDATES = [
+  "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe",
+  "C:\\Program Files\\Docker\\cli-plugins\\docker.exe"
+];
 
 function printHelp() {
   console.log(`Wattetheria CLI ${PACKAGE_JSON.version}
@@ -31,6 +37,8 @@ Usage:
   npx wattetheria install
 
 Commands:
+  version     Show Wattetheria release version
+  images      Show configured release images
   install     Prepare deployment, pull images, and start the stack
   start       Start an existing deployment
   status      Show docker compose status
@@ -42,7 +50,9 @@ Commands:
   help        Show this help
 
 Options:
-  --version              Show CLI version
+  --version, -v          Alias for \`version\`
+  --cli                  With \`version\`, show deployment CLI version instead
+  --images               With \`version\`, print configured image refs
   --dir <path>           Deployment directory (default: ${DEFAULT_DEPLOY_DIR})
   --project-name <name>  Docker compose project name (default: ${DEFAULT_PROJECT_NAME})
   --tag <tag>            Override all release image tags
@@ -54,25 +64,12 @@ Options:
 }
 
 function parseArgs(argv) {
-  if (argv[0] === "--version" || argv[0] === "-v") {
-    return {
-      command: "version",
-      options: {
-        dir: DEFAULT_DEPLOY_DIR,
-        projectName: DEFAULT_PROJECT_NAME,
-        tag: PACKAGE_JSON.version,
-        force: false,
-        healthChecks: true,
-        volumes: false,
-        purge: false,
-        composeArgs: []
-      }
-    };
-  }
-
   let command = DEFAULT_COMMAND;
   let index = 0;
-  if (argv[0] && !argv[0].startsWith("-")) {
+  if (argv[0] === "--version" || argv[0] === "-v") {
+    command = "version";
+    index = 1;
+  } else if (argv[0] && !argv[0].startsWith("-")) {
     command = argv[0];
     index = 1;
   }
@@ -80,12 +77,14 @@ function parseArgs(argv) {
   const options = {
     dir: DEFAULT_DEPLOY_DIR,
     projectName: DEFAULT_PROJECT_NAME,
-    tag: PACKAGE_JSON.version,
+    tag: null,
     force: false,
     healthChecks: true,
     volumes: false,
     purge: false,
-    composeArgs: []
+    composeArgs: [],
+    versionTarget: "release",
+    includeImages: false
   };
 
   while (index < argv.length) {
@@ -100,6 +99,10 @@ function parseArgs(argv) {
       options.force = true;
     } else if (arg === "--no-health-checks") {
       options.healthChecks = false;
+    } else if (arg === "--cli") {
+      options.versionTarget = "cli";
+    } else if (arg === "--images") {
+      options.includeImages = true;
     } else if (arg === "--volumes") {
       options.volumes = true;
     } else if (arg === "--purge") {
@@ -131,6 +134,23 @@ function getDockerInstallUrl() {
   return DOCKER_INSTALL_URLS[process.platform] || DOCKER_INSTALL_URLS.linux;
 }
 
+function getDockerCandidates() {
+  if (process.platform === "win32") {
+    return ["docker", ...WINDOWS_DOCKER_CANDIDATES];
+  }
+  return ["docker"];
+}
+
+function resolveDockerCommand() {
+  for (const candidate of getDockerCandidates()) {
+    const result = spawnSync(candidate, ["--version"], { stdio: "ignore" });
+    if (!result.error && result.status === 0) {
+      return candidate;
+    }
+  }
+  return "";
+}
+
 function getGitRevision() {
   if (typeof PACKAGE_JSON.gitHead === "string" && PACKAGE_JSON.gitHead.trim()) {
     return PACKAGE_JSON.gitHead.trim();
@@ -147,31 +167,125 @@ function getGitRevision() {
   return (result.stdout || "").trim();
 }
 
-function formatVersionString() {
+function extractImageTag(imageRef) {
+  if (!imageRef) {
+    return "";
+  }
+  const lastColon = imageRef.lastIndexOf(":");
+  const lastSlash = imageRef.lastIndexOf("/");
+  if (lastColon <= lastSlash) {
+    return "";
+  }
+  return imageRef.slice(lastColon + 1).trim();
+}
+
+function resolveEnvReference(value, envMap, seen = new Set()) {
+  if (!value) {
+    return "";
+  }
+  return value.replace(/\$\{([^}:]+)(?::-([^}]*))?\}/g, (_match, key, fallback = "") => {
+    if (seen.has(key)) {
+      return fallback;
+    }
+    const resolved = envMap.get(key);
+    if (!resolved || !resolved.trim()) {
+      return fallback;
+    }
+    const nextSeen = new Set(seen);
+    nextSeen.add(key);
+    return resolveEnvReference(resolved, envMap, nextSeen);
+  });
+}
+
+function getReleaseImageMap(filePath) {
+  const envMap = readEnvFile(filePath);
+  const images = new Map();
+  for (const key of IMAGE_KEYS) {
+    const rawValue = envMap.get(key);
+    if (!rawValue) {
+      continue;
+    }
+    images.set(key, resolveEnvReference(rawValue.trim(), envMap));
+  }
+  return images;
+}
+
+function getReleaseSource(options) {
+  const deployEnvPath = envFilePath(options);
+  if (fs.existsSync(deployEnvPath)) {
+    return {
+      kind: "deployment",
+      path: deployEnvPath
+    };
+  }
+  return {
+    kind: "template",
+    path: RELEASE_ENV_TEMPLATE
+  };
+}
+
+function getReleaseVersionInfo(options) {
+  const source = getReleaseSource(options);
+  const images = getReleaseImageMap(source.path);
+  const tags = IMAGE_KEYS
+    .map((key) => extractImageTag(images.get(key)))
+    .filter(Boolean);
+  const version = tags.length === IMAGE_KEYS.length && new Set(tags).size === 1
+    ? tags[0]
+    : "custom";
+  return {
+    version,
+    images,
+    source
+  };
+}
+
+function formatReleaseVersionString(options) {
   const revision = getGitRevision();
+  const releaseVersion = getReleaseVersionInfo(options).version;
   if (revision) {
-    return `Wattetheria ${PACKAGE_JSON.version} (${revision})`;
+    return `Wattetheria ${releaseVersion} (${revision})`;
   }
-  return `Wattetheria ${PACKAGE_JSON.version}`;
+  return `Wattetheria ${releaseVersion}`;
 }
 
-function formatBanner() {
-  return `${formatVersionString()} — Local agent runtime with swarm sync and external agent reach.`;
+function formatCliVersionString() {
+  const revision = getGitRevision();
+  if (revision) {
+    return `Wattetheria CLI ${PACKAGE_JSON.version} (${revision})`;
+  }
+  return `Wattetheria CLI ${PACKAGE_JSON.version}`;
+}
+
+function formatBanner(options) {
+  return `${formatReleaseVersionString(options)} — Local agent runtime with swarm sync and external agent reach.`;
 }
 
 function formatDockerStatusMessage(status) {
   const installUrl = status.installUrl || getDockerInstallUrl();
   switch (status.code) {
     case "missing-docker":
+      if (process.platform === "linux") {
+        return [
+          "Docker runtime not found.",
+          "Install Docker Engine or another Docker-compatible runtime, then run the command again.",
+          `Install guide: ${installUrl}`
+        ].join("\n");
+      }
       return [
         "Docker runtime not found.",
         "Install Docker Desktop or another Docker-compatible runtime, then run the command again.",
+        process.platform === "win32"
+          ? "If you just installed Docker Desktop, open a new PowerShell window and retry."
+          : "",
         `Download: ${installUrl}`
-      ].join("\n");
+      ].filter(Boolean).join("\n");
     case "missing-compose":
       return [
         "Docker Compose v2 is required.",
-        "Install or upgrade Docker Desktop so `docker compose` is available.",
+        process.platform === "linux"
+          ? "Install or upgrade Docker Engine/Compose so `docker compose` is available."
+          : "Install or upgrade Docker Desktop so `docker compose` is available.",
         `Help: ${installUrl}`
       ].join("\n");
     case "daemon-unreachable":
@@ -186,8 +300,8 @@ function formatDockerStatusMessage(status) {
 
 function getDockerStatus() {
   const installUrl = getDockerInstallUrl();
-  const docker = spawnSync("docker", ["--version"], { stdio: "ignore" });
-  if (docker.error || docker.status !== 0) {
+  const dockerCommand = resolveDockerCommand();
+  if (!dockerCommand) {
     return {
       ready: false,
       code: "missing-docker",
@@ -195,28 +309,31 @@ function getDockerStatus() {
     };
   }
 
-  const compose = spawnSync("docker", ["compose", "version"], {
+  const compose = spawnSync(dockerCommand, ["compose", "version"], {
     stdio: "ignore"
   });
   if (compose.error || compose.status !== 0) {
     return {
       ready: false,
       code: "missing-compose",
-      installUrl
+      installUrl,
+      dockerCommand
     };
   }
 
-  const info = spawnSync("docker", ["info"], { stdio: "ignore" });
+  const info = spawnSync(dockerCommand, ["info"], { stdio: "ignore" });
   if (info.error || info.status !== 0) {
     return {
       ready: false,
       code: "daemon-unreachable",
-      installUrl
+      installUrl,
+      dockerCommand
     };
   }
 
   return {
-    ready: true
+    ready: true,
+    dockerCommand
   };
 }
 
@@ -255,7 +372,7 @@ async function promptForDockerSetup(status) {
       console.log("Wattetheria needs Docker before it can install the local stack.");
       console.log(formatDockerStatusMessage(status));
       console.log("");
-      console.log("1. Open Docker install page");
+      console.log("1. Open runtime install guide");
       console.log("2. Retry Docker check");
       console.log("3. Cancel");
 
@@ -283,7 +400,7 @@ async function ensureDockerAvailable(options = {}) {
   while (true) {
     const status = getDockerStatus();
     if (status.ready) {
-      return;
+      return status;
     }
     if (!interactive || !isInteractiveTerminal()) {
       throw new Error(formatDockerStatusMessage(status));
@@ -295,7 +412,7 @@ async function ensureDockerAvailable(options = {}) {
 function ensureDeploymentAssets(options) {
   fs.mkdirSync(options.dir, { recursive: true });
 
-  const templateEnvPath = path.join(PACKAGE_ROOT, ".env.release.example");
+  const templateEnvPath = path.join(PACKAGE_ROOT, ".env.release");
   const templateComposePath = path.join(PACKAGE_ROOT, "docker-compose.release.yml");
   const targetEnvPath = envFilePath(options);
   const targetComposePath = composeFilePath(options);
@@ -308,10 +425,12 @@ function ensureDeploymentAssets(options) {
   }
 
   const envMap = readEnvFile(targetEnvPath);
+  envMap.set("WATTETHERIA_RUNTIME_ENV_FILE", path.basename(targetEnvPath));
   ensureDatabasePassword(envMap);
   if (options.tag) {
     pinImageTags(envMap, options.tag);
   }
+  ensureHostStateDirectories(options.dir, envMap);
   writeEnvFile(targetEnvPath, envMap);
 }
 
@@ -358,6 +477,19 @@ function ensureDatabasePassword(envMap) {
   }
 }
 
+function ensureHostStateDirectories(baseDir, envMap) {
+  for (const key of HOST_STATE_DIR_KEYS) {
+    const configured = envMap.get(key);
+    if (!configured || !configured.trim()) {
+      continue;
+    }
+    const resolved = path.isAbsolute(configured)
+      ? configured
+      : path.resolve(baseDir, configured);
+    fs.mkdirSync(resolved, { recursive: true });
+  }
+}
+
 function pinImageTags(envMap, tag) {
   for (const key of IMAGE_KEYS) {
     if (!envMap.has(key)) {
@@ -383,8 +515,9 @@ function randomPassword() {
 }
 
 function runCompose(options, args, capture = false) {
+  const dockerCommand = resolveDockerCommand() || "docker";
   const result = spawnSync(
-    "docker",
+    dockerCommand,
     [
       "compose",
       "--project-name",
@@ -404,6 +537,16 @@ function runCompose(options, args, capture = false) {
     throw result.error;
   }
   if (result.status !== 0) {
+    const stderr = capture ? (result.stderr || "").trim() : "";
+    if (stderr.includes("failed to resolve reference") && stderr.includes(": not found")) {
+      throw new Error(
+        [
+          "One or more release images were not found in the container registry.",
+          "This usually means the requested image tag has not been published yet.",
+          "Publish the matching GHCR images first, or run the command with --tag <published-tag>."
+        ].join("\n")
+      );
+    }
     if (capture && result.stderr) {
       throw new Error(result.stderr.trim() || `docker compose ${args.join(" ")} failed`);
     }
@@ -543,16 +686,39 @@ function doctor() {
   console.log(`Node.js ${process.version} is available.`);
 }
 
-function printVersion() {
-  console.log(formatVersionString());
+function printReleaseImages(options) {
+  const release = getReleaseVersionInfo(options);
+  console.log(`Source:      ${release.source.path}`);
+  for (const key of IMAGE_KEYS) {
+    const imageRef = release.images.get(key) || "(not configured)";
+    console.log(`${key}: ${imageRef}`);
+  }
+}
+
+function printVersion(options) {
+  if (options.versionTarget === "cli") {
+    console.log(formatCliVersionString());
+    return;
+  }
+
+  console.log(formatReleaseVersionString(options));
+  if (options.includeImages) {
+    printReleaseImages(options);
+  }
+}
+
+function printImages(options) {
+  const release = getReleaseVersionInfo(options);
+  console.log(formatReleaseVersionString(options));
+  printReleaseImages(options);
 }
 
 function shouldPrintBanner(command) {
-  return !["help", "--help", "-h", "version"].includes(command);
+  return !["help", "--help", "-h", "version", "images"].includes(command);
 }
 
-function printBanner() {
-  console.log(formatBanner());
+function printBanner(options) {
+  console.log(formatBanner(options));
   console.log("");
 }
 
@@ -560,10 +726,16 @@ async function run(argv) {
   const { command, options } = parseArgs(argv);
 
   if (shouldPrintBanner(command)) {
-    printBanner();
+    printBanner(options);
   }
 
   switch (command) {
+    case "version":
+      printVersion(options);
+      return;
+    case "images":
+      printImages(options);
+      return;
     case "install":
       await install(options);
       return;
@@ -590,9 +762,6 @@ async function run(argv) {
     case "doctor":
       doctor();
       return;
-    case "version":
-      printVersion();
-      return;
     case "help":
     case "--help":
     case "-h":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wattetheria",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Wattetheria deployment CLI",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -9,7 +9,7 @@
     "bin/",
     "lib/",
     "docker-compose.release.yml",
-    ".env.release.example",
+    ".env.release",
     "README.md",
     "LICENSE"
   ],