From 9e75cfffd6f59f81390fc0a5322aeb8640b31660 Mon Sep 17 00:00:00 2001
From: dullfig <dan.u@grmcompany.com>
Date: Fri, 2 Jan 2026 16:02:48 -0800
Subject: [PATCH] added message pump overview and yaml configuration

---
 README.md             |   3 ++
 docs/configuration.md | 118 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 docs/configuration.md

diff --git a/README.md b/README.md
index b99a2b4..07d4628 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,6 @@
 # AgentServer — The Living Substrate (v1.3)
+***"It just works..."***
+
 **January 01, 2026**  
 **Architecture: Autonomous Grammar-Driven, Turing-Complete Multi-Agent Organism**
 
@@ -29,6 +31,7 @@ AgentServer is a production-ready substrate for the `xml-pipeline` nervous syste
 
 ### 4. Isolated Structural Control
 - **Out-of-Band (OOB) Port:** Structural commands (registration, wiring, shutdown) use a dedicated port and Ed25519 signatures, ensuring "Life/Death" commands cannot be delayed by agent traffic.
+- **[Read Further: YAML Configuration System](docs/configuration.md)**
 
 ## Technical Stack
 - **Parsing:** Lark (EBNF Grammar) + `lxml` (Validation/C14N).
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..5007b8b
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,118 @@
+# Configuration — organism.yaml
+
+The entire organism is declared in a single YAML file (default: `config/organism.yaml`).  
+All listeners, agents, and federation gateways are instantiated from this file at startup.  
+Changes require a restart (hot-reload planned for future).
+
+## Example Full Configuration
+
+```yaml
+organism:
+  name: "ResearchSwarm-01"
+  identity: "config/identity/private.ed25519"   # Ed25519 private key for signing
+  port: 8765
+  tls:
+    cert: "certs/fullchain.pem"
+    key: "certs/privkey.pem"
+
+meta:
+  enabled: true
+  allow_list_capabilities: true      # Public catalog of capability names
+  allow_schema_requests: "admin"     # "admin" | "authenticated" | "none"
+  allow_example_requests: "admin"
+  allow_prompt_requests: "admin"
+  allow_remote: false                # Federation peers can query meta
+
+listeners:
+  - name: calculator.add
+    payload_class: examples.calculator.AddPayload
+    handler: examples.calculator.add_handler
+    description: "Integer addition"
+
+  - name: calculator.subtract
+    payload_class: examples.calculator.SubtractPayload
+    handler: examples.calculator.subtract_handler
+
+  - name: summarizer
+    payload_class: agents.summarizer.SummarizePayload
+    handler: agents.summarizer.summarize_handler
+    description: "Text summarization via local LLM"
+
+agents:
+  - name: researcher
+    system_prompt: "prompts/researcher_system.txt"
+    tools:
+      - calculator.add
+      - calculator.subtract
+      - summarizer
+      - name: web_search                # Remote tool via gateway below
+        remote: true
+
+gateways:
+  - name: web_search
+    remote_url: "wss://trusted-search-node.example.org"
+    trusted_identity: "pubkeys/search_node.ed25519.pub"
+    description: "Federated web search capability"
+```
+
+## Sections Explained
+
+### `organism`
+Core server settings.
+
+- `name`: Human-readable identifier (used in logs, discovery).
+- `identity`: Path to Ed25519 private key (for envelope signing, federation auth).
+- `port` / `tls`: Single-port WSS configuration.
+
+### `meta`
+Controls the privileged introspection facility (`https://xml-platform.org/meta/v1`).
+
+- `allow_list_capabilities`: Publicly visible catalog (safe).
+- `allow_*_requests`: Restrict schema/example/prompt emission to admin or authenticated sessions.
+- `allow_remote`: Whether federation peers can query your meta namespace.
+
+### `listeners`
+All bounded capabilities. Each entry triggers autonomous registration:
+
+- `name`: Logical capability name (used in discovery, YAML tools lists). Dots allowed for hierarchy.
+- `payload_class`: Full import path to the `@xmlify` dataclass (defines contract).
+- `handler`: Full import path to the handler callable (`dict → bytes`).
+- `description`: Optional human-readable text (included in `list-capabilities`).
+
+At startup:
+1. Import payload_class and handler.
+2. Instantiate `Listener(payload_class=..., handler=..., name=...)`.
+3. `bus.register(listener)` → XSD synthesis, Lark grammar generation, prompt caching.
+
+Filesystem artifacts:
+- XSDs cached as `schemas/<name_with_underscores>/v1.xsd` (dots → underscores for Linux safety).
+
+### `agents`
+LLM-based reasoning agents.
+
+- `name`: Agent identifier.
+- `system_prompt`: Path to static prompt file.
+- `tools`: List of local capability names or remote references.
+  - Local: direct name match (`calculator.add`).
+  - Remote: `name:` + `remote: true` → routed via matching gateway.
+
+Live capability prompts are auto-injected into the agent's system prompt at runtime (no stale copies).
+
+### `gateways`
+Federation peers.
+
+- `name`: Local alias for the remote organism.
+- `remote_url`: WSS endpoint.
+- `trusted_identity`: Path to remote's Ed25519 public key.
+- `description`: Optional.
+
+Remote tools referenced in `agents.tools` are routed through the gateway with matching `name`.
+
+## Future Extensions (planned)
+
+- Hot-reload of configuration.
+- Per-agent privilege scoping.
+- Capability versioning in YAML (`version: v2`).
+
+This YAML is the **single source of truth** for organism composition.  
+Edit → restart → new bounded minds appear, fully self-describing and attack-resistant.