DOCS: Systematic overhaul of Literate source (Granularity & Technical Reasoning)

literate/perceive.org

@@ -4,29 +4,41 @@
 #+STARTUP: content
 
 * Stage 1: Perceive (perceive.lisp)
-** Architectural Intent: Sensory Ingestion
-The Perceive stage is the "sensory cortex" of the OpenCortex. It takes raw stimuli from the outside world (keyboard events, chat messages, heartbeats, or system interrupts) and normalizes them into internal **Signals**.
 
-** Async Sensor Routing
-To prevent blocking the main pipeline, certain sensors (like user commands or chat messages) are processed asynchronously in their own threads.
+** Architectural Intent: Sensory Ingestion
+The Perceive stage is the "sensory cortex" of the OpenCortex. Its primary responsibility is to take raw, unstructured stimuli from the outside world—whether from a TCP socket, a system interrupt, or a background heartbeat—and normalize them into high-fidelity internal **Signals**.
+
+Normalization is critical because it shields the subsequent reasoning and actuation stages from the messiness of different transport protocols. Whether a message arrives via a TUI, a Signal bot, or an internal timer, the core "Brain" perceives a consistent Lisp property list.
+
+** Pipeline Initialization
+Ensuring we are in the correct namespace for sensory processing.
 
 #+begin_src lisp :tangle ../src/perceive.lisp
 (in-package :opencortex)
+#+end_src
 
+** Sensory Concurrency (Async Sensors)
+To maintain the agent's responsiveness, we distinguish between "Fast" and "Slow" sensors. Sensors that require extensive processing or external API calls are routed to asynchronous threads to prevent blocking the main metabolic pipeline.
+
+#+begin_src lisp :tangle ../src/perceive.lisp
 (defvar *async-sensors* '(:chat-message :delegation :user-command)
   "List of sensors that should be processed asynchronously to avoid blocking gateways.")
 #+end_src
 
-** Foveal Focus State
-The system tracks the user's current point of interaction to provide context to the reasoning engine.
+** Foveal Focus (User Context)
+The system tracks the user's current point of interaction (the "foveal focus"). This provides immediate situational awareness to the reasoning engine, allowing it to prioritize the data the human is currently looking at.
 
 #+begin_src lisp :tangle ../src/perceive.lisp
 (defvar *foveal-focus-id* nil
   "The Org ID of the node the user is currently interacting with.")
 #+end_src
 
-** Stimulus Injection
-The entry point for raw messages. It determines if the signal should be processed synchronously or asynchronously.
+* Primary Ingress
+
+** Stimulus Injection (inject-stimulus)
+The ~inject-stimulus~ function is the universal gateway into the OpenCortex mind. It performs two critical tasks:
+1. *Envelope Wrapping:* Ensures that every raw message is wrapped in a ~:META~ envelope, preserving the source and session information.
+2. *Dispatching:* Determines whether to run the metabolism synchronously or in a new thread.
 
 #+begin_src lisp :tangle ../src/perceive.lisp
 (defun inject-stimulus (raw-message &key stream (depth 0))
@@ -53,8 +65,13 @@ The entry point for raw messages. It determines if the signal should be processe
           (skip-event () (harness-log "SYSTEM RECOVERY: Stimulus dropped.~%"))))))
 #+end_src
 
-** The Perceive Gate
-The initial stage of the metabolic loop. It logs the signal, performs selective memory snapshots, and updates the Memory graph based on incoming AST updates.
+* The Perceive Stage
+
+** Perception Gate (perceive-gate)
+The first official stage of the metabolic loop. It performs "Pre-Cognitive" work:
+1. *Logging:* Recording the arrival of the signal.
+2. *State Sync:* If the signal contains an AST update (e.g., from Emacs), it immediately updates the in-memory graph.
+3. *Merkle Checkpointing:* Before modifying memory, it creates a snapshot to allow for emergency rollbacks.
 
 #+begin_src lisp :tangle ../src/perceive.lisp
 (defun perceive-gate (signal)