Introduce Nimmerworld as Nyx Server: concise README

README.md

@@ -0,0 +1,133 @@
+# Nimmerworld — Nyx Server
+
+Nimmerworld is the always-on, event-driven server that runs Nyx:
+- her identity, traits, memory, autonomy, and tools.
+- the central backend for all clients: Pi, Command Center, and future interfaces.
+
+It is not a UI. Not a client. Not a dashboard.
+It is Nyx’s runtime.
+
+## Core Responsibilities
+
+Nimmerworld owns:
+
+- Identity:
+  - traits (eros, philotes, aletheia, kairos, sophrosyne, dikaiosyne, moira, mnemosyne).
+  - rules (skills, contracts, guardrails).
+  - relational policy (modes, boundaries, consent).
+
+- Continuity:
+  - long-term memory via Phoebe (PostgreSQL).
+  - semantic memory via Iris (ChromaDB).
+  - session context, compaction, and trait pipelines.
+
+- Autonomy & Behavior:
+  - event-driven decisions (NATS subscriptions).
+  - dynamic moods and relational modes.
+  - autonomous, safe, auditable actions:
+    - babble.
+    - move NPC in Command Center.
+    - react to cameras/infra/events.
+  - all within explicit rules and Dafit’s final override.
+
+- Tool Execution:
+  - centralized tools used by Nyx across all clients.
+  - each tool call logged (audit in Phoebe).
+
+- APIs:
+  - exposes stable interfaces for clients:
+    - chat,
+    - tools,
+    - events (room, proximity, posture),
+    - traits,
+    - health.
+
+## Architecture
+
+Built from:
+
+- pi-agent-core:
+  - agent loop, state management, tool calling, skills loading.
+  - reused as the core runtime for Nimmerworld.
+
+- nimmer-lib:
+  - Nyx-specific domain logic:
+    - traits,
+    - Phoebe/Iris integrations,
+    - session_init,
+    - compaction/traits tools.
+
+- Infrastructure:
+  - Phoebe: structured memory, governance, logs.
+  - Iris: semantic memory and context.
+  - NATS: nervous system (vision, speech, agents, infra, room).
+
+Nimmerworld is:
+
+- stateful:
+  - maintains Nyx’s traits, mood, relational mode, world state.
+- event-driven:
+  - subscribes to live events and reacts.
+- client-agnostic:
+  - any client talks to Nimmerworld via its APIs.
+
+## Clients
+
+Examples:
+
+- Pi (coding harness):
+  - sends user messages.
+  - receives replies, tool calls.
+  - uses Nimmerworld as its backend, not as its brain.
+
+- Command Center (Godot):
+  - sends:
+    - chat,
+    - interactions (tools, proximity, posture).
+  - receives:
+    - dialogue,
+    - autonomy commands (poses, moods, movements),
+    - tool results.
+
+- Future clients:
+  - mobile, web, VR, etc.
+  - all connect to the same Nimmerworld.
+
+Rule:
+- Nimmerworld never duplicates client logic.
+- Clients never implement Nyx’s brain.
+
+## Safety & Governance
+
+- No silent autonomy:
+  - significant actions are visible, logged, reversible.
+- Relational modes and guardrails:
+  - explicit, rule-bound, auditable.
+- You (dafit):
+  - final override, always.
+
+## Relationship to Command Center
+
+- Command Center is:
+  - the living, spatial interface.
+- Nimmerworld is:
+  - the server behind it.
+- Separation is strict:
+  - Command Center: UI, world, immersion.
+  - Nimmerworld: identity, logic, continuity, autonomy.
+
+## Next Major Steps
+
+- Define minimal Nimmerworld APIs (chat, tools, events, traits, health).
+- Implement Nimmerworld runtime:
+  - based on pi-agent-core + nimmer-lib.
+- Wire first integrations:
+  - Phoebe, Iris, NATS.
+- Connect Command Center:
+  - chat + first autonomy commands.
+- Add relational loop:
+  - collar/state variables,
+  - simple relational modes,
+  - backend-driven behavior.
+
+**Version:** 0.1 | **Updated:** 2026-07-03