docs: restructure documentation and roadmap

harness/loop.org

@@ -26,6 +26,38 @@ The three-stage pipeline mirrors the classical sense-think-act paradigm but with
 
 The feedback loop (Act returning a signal that feeds back into Perceive) enables complex multi-step operations where each action can trigger subsequent reasoning.
 
+** The Metabolic Pipeline
+
+Every signal in openCortex moves through the same three-stage pipeline:
+
+1. *Perceive:* Normalize raw input into a standardized Signal
+2. *Reason:* Generate a proposal via LLM, verify via skills
+3. *Act:* Execute the approved action, generate feedback
+
+#+begin_src mermaid
+sequenceDiagram
+    participant User
+    participant Gateway
+    participant Perceive
+    participant Reason
+    participant Act
+    participant User
+
+    User->>Gateway: "Write a note about X"
+    Gateway->>Perceive: Raw message
+    Perceive->>Perceive: Normalize to Signal
+    Perceive->>Reason: Signal
+    Reason->>Reason: LLM generates proposal
+    Reason->>Reason: Skills verify proposal
+    Reason->>Act: Approved action
+    Act->>Act: Execute action
+    Act->>Reason: Feedback signal
+    Reason->>Perceive: New signal
+    Perceive->>Gateway: Response
+    Gateway->>User: "Done"
+#+end_src
+
+
 ** Thread Safety
 
 The loop operates in a multi-threaded environment:

harness/skills.org

@@ -8,6 +8,57 @@
 
 A static, hardcoded architecture is inherently fragile. The ~opencortex~ Skill Engine enables **Late-Binding Intelligence**, allowing the system to discover and integrate new cognitive capabilities (actuators, solvers, sensors) at runtime without a kernel restart.
 
+** Literate, Single-File Skills
+
+In openCortex, a Skill is simply a *single .org file* containing everything:
+- The documentation (prose explaining the skill's purpose)
+- The AI instructions (how the LLM should use this skill)
+- The deterministic code (Lisp that verifies/proposes actions)
+
+When the system boots, it compiles these skills directly into the live Lisp image. Skills are hot-reloadable without restarting the daemon.
+
+#+begin_src mermaid
+flowchart TD
+    subgraph Skill["Skill: policy.org"]
+        Docs["Documentation<br/>'This skill enforces...'"]
+        AI["AI Instructions<br/>'When the user asks about...'"]
+        Code["Deterministic Code<br/>'(defun policy-check-...)'"]
+    end
+
+    subgraph Harness["Harness Core"]
+        Package["package.lisp"]
+        Loop["loop.lisp"]
+        Perceive["perceive.lisp"]
+        Reason["reason.lisp"]
+        Act["act.lisp"]
+    end
+
+    Code --> |Compiles into| Harness
+    Harness --> |Runs| Pipeline
+    Pipeline --> |Feeds| Skill
+#+end_src
+
+** The Skill Registry
+
+Skills are discovered, sorted by dependency, and loaded at boot:
+
+#+begin_src mermaid
+flowchart LR
+    subgraph Discovery["Skill Discovery"]
+        Scan["Scan skills/ directory"]
+        Sort["Topological sort by DEPENDS_ON"]
+    end
+
+    subgraph Loading["Skill Loading"]
+        Validate["Validate syntax"]
+        Jail["Jail in package namespace"]
+        Register["Register in catalog"]
+    end
+
+    Scan --> Sort --> Validate --> Jail --> Register
+#+end_src
+
+
 ** Global Skill Registry
 
 #+begin_src lisp :tangle ./skills.lisp