feat: add DeepSeek and NVIDIA NIM providers

- Add deepseek and nvidia entries to gateway-provider config

- Add DEEPSEEK_API_KEY and NVIDIA_API_KEY to .env.example

- Add deepseek and nvidia to doctor's LLM provider check

- Fix remaining harness-log → log-message reference

org/core-communication.org

@@ -0,0 +1,242 @@
+#+TITLE: Communication Protocol (communication.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:protocol:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-communication.lisp
+
+* Overview: Architectural Intent
+
+The Communication Protocol defines how Passepartout speaks to the outside world. It sits between the metabolic loop and the network, providing framed, length-prefixed message transport over TCP.
+
+Every message is an S-expression (plist) prefixed with a 6-character hex length:
+
+  00002C(:TYPE :EVENT :PAYLOAD (:ACTION :handshake :VERSION "0.2.0"))
+
+This is a deliberate rejection of JSON, Protocol Buffers, or any other serialization format. The message format is Lisp-native because:
+
+1. The agent generates and consumes these messages inside the cognitive loop — no serialization layer needed
+2. The format is human-readable and trivially debuggable with a text editor
+3. The length prefix prevents framing attacks (no "read until newline" ambiguity)
+
+** Why Length-Prefixed Framing?
+
+A naive TCP protocol that reads until newline fails when:
+- A message contains a newline character (which Lisp plists can)
+- A message is split across TCP packets (read returns partial data)
+- A malicious client sends an infinite stream without newlines
+
+The length prefix solves all three problems. The reader reads exactly 6 characters (the hex length), then reads exactly that many additional characters. No ambiguous termination, no partial message handling, no newline worries.
+
+The 6-character hex length supports messages up to ~16MB (0xFFFFFF bytes). This is sufficient for any single message the agent would produce. Larger payloads should be split across multiple messages.
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** Actuator Registry
+
+The global registry mapping target keywords (~:cli~, ~:telegram~, ~:signal~, etc.) to their physical actuator functions. Extensible at runtime — skills can register new actuators via ~actuator-register~.
+
+#+begin_src lisp
+(defvar *actuator-registry* (make-hash-table :test 'equalp)
+  "Global registry mapping target keywords to their physical actuator functions.")
+
+(defun actuator-register (name fn) 
+  "Registers an actuator function. Actuators receive: (ACTION CONTEXT)."
+  (let ((key (if (keywordp name) name (intern (string-upcase (string name)) :keyword))))
+    (setf (gethash key *actuator-registry*) fn)))
+#+end_src
+
+** Message Framing
+
+Three functions handle the full message lifecycle: sanitize (strip non-serializable state), frame (serialize + prefix), and read (parse from stream).
+
+*** Sanitize Protocol Message
+
+Strips transient runtime state (~:reply-stream~, ~:socket~, ~:stream~) from a message plist before sending it over the network. These are Lisp stream objects that cannot be serialized and have no meaning to the remote end.
+
+#+begin_src lisp
+(defun protocol-message-sanitize (msg)
+  "Recursively strips non-serializable objects from a protocol plist."
+  (if (and msg (listp msg))
+      (let ((clean nil))
+        (loop for (k v) on msg by #'cddr
+              do (unless (member k '(:reply-stream :socket :stream))
+                   (push k clean)
+                   (push (if (listp v) (protocol-message-sanitize v) v) clean)))
+        (nreverse clean))
+      msg))
+#+end_src
+
+*** Frame Message
+
+Serializes a plist to a length-prefixed string: 6-character hex length followed by the ~prin1~ representation.
+
+#+begin_src lisp
+(defun frame-message (msg)
+  "Serializes a message plist and prefixes it with a 6-character hex length."
+  (let* ((sanitized (protocol-message-sanitize msg))
+         (payload (let ((*print-pretty* nil) (*read-eval* nil)) (format nil "~s" sanitized)))
+         (len (length payload)))
+    (format nil "~6,'0x~a" len payload)))
+#+end_src
+
+*** Read Framed Message
+
+Reads a complete framed message from a TCP stream. Handles leading whitespace between messages, partial reads, and malformed length headers gracefully. Returns the parsed S-expression, or ~:eof~ if the stream is closed, or ~:error~ if the message is malformed.
+
+#+begin_src lisp
+(defun read-framed-message (stream)
+  "Reads a hex-length prefixed S-expression from the stream securely."
+  (let ((length-buffer (make-string 6)))
+    (handler-case
+        (progn
+          (loop for char = (peek-char nil stream nil :eof)
+                while (and (not (eq char :eof)) (member char '(#\Space #\Newline #\Tab #\Return)))
+                do (read-char stream))
+          (let ((count (read-sequence length-buffer stream)))
+            (if (< count 6)
+                :eof
+                (let ((len (ignore-errors (parse-integer length-buffer :radix 16))))
+                  (if (not len)
+                      :error
+                      (let ((msg-buffer (make-string len)))
+                        (read-sequence msg-buffer stream)
+                        (let ((*read-eval* nil))
+                          (handler-case (read-from-string msg-buffer)
+                            (error () :error)))))))))
+      (error () :error))))
+#+end_src
+
+** Server Listener (daemon-start)
+
+The TCP server that accepts connections from CLI and TUI clients. Each connection gets a dedicated thread (~client-handle-connection~).
+
+The daemon sends a handshake message on connection, then enters a read loop, injecting each received message into the metabolic loop via ~inject-stimulus~. The ~:health-check~ message type is handled inline (not sent to the cognitive loop) so that health checks work even when the agent is busy.
+
+#+begin_src lisp
+(defvar *daemon-socket* nil)
+
+(defun client-handle-connection (socket)
+  "Handles a single TUI/CLI client connection in a dedicated thread."
+  (let ((stream (usocket:socket-stream socket)))
+    (handler-case
+        (progn
+          (format stream "~a" (frame-message (make-hello-message "0.2.0")))
+          (finish-output stream)
+          (loop
+            (let ((msg (read-framed-message stream)))
+              (cond
+                ((eq msg :eof) (return))
+                ((eq msg :error) (return))
+                ((eq (getf msg :type) :health-check)
+                 (let ((health-msg (list :type :health-response 
+                                         :status (or (and (boundp 'passepartout::*system-health*) 
+                                                         (symbol-value 'passepartout::*system-health*))
+                                                     :unknown)
+                                         :checked-p (or (and (boundp 'passepartout::*health-check-ran*)
+                                                             (symbol-value 'passepartout::*health-check-ran*))
+                                                     nil))))
+                   (format stream "~a" (frame-message health-msg))
+                   (finish-output stream)))
+                (t (inject-stimulus msg :stream stream))))))
+      (error (c) (harness-log "CLIENT ERROR: ~a" c)))
+    (ignore-errors (usocket:socket-close socket))))
+
+(defun start-daemon (&key (port 9105))
+  "Starts the network listener for TUI/CLI clients."
+  (setf *daemon-socket* (usocket:socket-listen "127.0.0.1" port :reuse-address t))
+  (harness-log "DAEMON: Listening on localhost:~a" port)
+  (bt:make-thread
+   (lambda ()
+     (loop
+       (let ((client-socket (usocket:socket-accept *daemon-socket*)))
+         (when client-socket
+           (bt:make-thread (lambda () (client-handle-connection client-socket))
+                          :name "passepartout-client-handler")))))
+   :name "passepartout-server-listener"))
+#+end_src
+
+** Handshake Logic
+
+The first message sent to every new connection. The client can use this to verify the protocol version and the daemon's capabilities.
+
+#+begin_src lisp
+(defun make-hello-message (version)
+  "Constructs the standard HELLO handshake message."
+  (list :TYPE :EVENT 
+        :PAYLOAD (list :ACTION :handshake 
+                       :VERSION version 
+                       :CAPABILITIES '(:AUTH :ORG-AST))))
+#+end_src
+
+** Structural Validation
+
+Validates that an incoming message has the minimum required structure: a plist with a valid ~:type~ field. Used by the protocol validator skill to reject malformed messages before they enter the cognitive loop.
+
+#+begin_src lisp :tangle ../lisp/core-communication.lisp
+(in-package :passepartout)
+
+(defun protocol-schema-validate (msg)
+  "Strict structural validation for incoming protocol messages."
+  (unless (listp msg) (error "Message must be a plist"))
+  (let ((type (proto-get msg :type)))
+    (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG :STATUS))
+      (error "Invalid message type '~a'" type))
+    t))
+#+end_src
+
+** Protocol Smoke Test (manual for REPL evaluation)
+
+Use this function to manually verify that the daemon is alive and the framing protocol works end-to-end. It connects to a running daemon, reads the HELLO handshake, sends a "hi" message, and reads the response.
+
+#+begin_src lisp :tangle no
+(defun test-daemon-protocol ()
+  (handler-case
+      (let* ((socket (usocket:socket-connect "127.0.0.1" 9105))
+             (stream (usocket:socket-stream socket)))
+        (format t "Connected.~%")
+        (let* ((len-buf (make-string 6))
+               (count (read-sequence len-buf stream)))
+          (when (= count 6)
+            (let* ((len (parse-integer len-buf :radix 16))
+                   (msg-buf (make-string len)))
+              (read-sequence msg-buf stream)
+              (format t "HELLO: ~a~%" msg-buf))))
+        (let* ((msg '(:TYPE :EVENT :META (:SOURCE :tui) :PAYLOAD (:SENSOR :user-input :TEXT "hi")))
+               (framed (frame-message msg)))
+          (format stream "~a" framed)
+          (finish-output stream)
+          (let* ((len-buf (make-string 6))
+                 (count (read-sequence len-buf stream)))
+            (when (= count 6)
+              (let* ((len (parse-integer len-buf :radix 16))
+                     (msg-buf (make-string len)))
+                (read-sequence msg-buf stream)
+                (format t "Response: ~a~%" msg-buf)))))
+        (usocket:socket-close socket))
+    (error (c) (format t "Error: ~a~%" c))))
+#+end_src
+
+* Test Suite
+Verifies that the framing protocol correctly serializes and deserializes messages.
+#+begin_src lisp :tangle ../lisp/core-communication.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-communication-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:communication-protocol-suite))
+(in-package :passepartout-communication-tests)
+
+(def-suite communication-protocol-suite :description "Communication Protocol Suite")
+(in-suite communication-protocol-suite)
+
+(test test-framing
+  (let* ((msg '(:type :EVENT :payload (:action :handshake)))
+         (framed (frame-message msg)))
+    (is (string= "00002C" (string-upcase (subseq framed 0 6))))))
+#+end_src

org/core-context.org

@@ -0,0 +1,267 @@
+#+TITLE: Context API (context.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:context:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-context.lisp
+
+* Overview: Architectural Intent
+
+The Context API implements the Foveal-Peripheral awareness model. When the agent thinks, it doesn't dump everything it knows into the LLM's context window — that would saturate the token budget immediately. Instead, it builds a skeletal outline of the entire Memex and only shows full detail for the current focus.
+
+This mirrors human attention: you are aware of your entire apartment (peripheral vision), but you only see the book in front of you in detail (foveal vision).
+
+** The Foveal-Peripheral Model
+
+Three factors determine how much detail an object gets:
+
+1. **Depth** — objects within 2 levels of the root get full outline (title + ID). Deeper objects are summarized or omitted.
+2. **Foveal focus** — the object the user is currently interacting with gets full content rendered.
+3. **Semantic similarity** — objects whose vector embedding is similar to the current foveal focus get promoted from peripheral to foveal detail.
+
+** Why Not Just Dump Everything?
+
+A naive implementation that serializes every ~org-object~ to text would produce hundreds of thousands of tokens for a typical knowledge base. The LLM would spend its attention budget on noise, not signal. The Foveal-Peripheral model preserves the signal (the current task and related information) while reducing noise (everything else).
+
+The semantic threshold is configurable via ~CONTEXT_SEMANTIC_THRESHOLD~ env var (default 0.75). Lower values include more peripherally related content; higher values restrict to tightly related content.
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** Memory Query (context-query)
+
+Filters the Memory store by tag, TODO state, or object type. This is the primary retrieval function used by skills to find relevant information.
+
+#+begin_src lisp
+(defun context-query (&key tag todo-state type)
+  "Filters the Memory based on tags, todo states, or types."
+  (let ((results nil))
+    (maphash (lambda (id obj)
+               (declare (ignore id))
+               (let* ((attrs (org-object-attributes obj)) (state (getf attrs :TODO-STATE)) (match t))
+                 (when (and type (not (eq (org-object-type obj) type))) (setf match nil))
+                 (when tag (unless (search tag (format nil "~a" (getf attrs :TAGS)) :test #'string-equal) (setf match nil)))
+                 (when (and todo-state (not (equal state todo-state))) (setf match nil))
+                 (when match (push obj results))))
+             *memory*)
+    results))
+#+end_src
+
+** Active Projects (context-active-projects)
+
+Returns headlines tagged as ~project~ that are not yet DONE. Used by the global awareness function to build the task overview.
+
+#+begin_src lisp
+(defun context-active-projects ()
+  "Returns headlines tagged as 'project' that are not yet marked DONE."
+  (remove-if (lambda (obj) (equal (getf (org-object-attributes obj) :TODO-STATE) "DONE"))
+             (context-query :tag "project" :type :HEADLINE)))
+#+end_src
+
+** Completed Tasks (context-recent-tasks)
+
+Retrieves recently finished tasks from the store. Used by the Scribe and Gardener for journal summarization.
+
+#+begin_src lisp
+(defun context-recent-tasks () 
+  "Retrieves recently finished tasks from the store."
+  (context-query :todo-state "DONE" :type :HEADLINE))
+#+end_src
+
+** Capability Discovery (context-skill-list)
+
+Provides a sorted overview of currently loaded system capabilities. Each entry includes the skill name, priority, and dependencies.
+
+#+begin_src lisp
+(defun context-skill-list ()
+  "Provides a sorted overview of currently loaded system capabilities."
+  (let ((results nil))
+    (maphash (lambda (name skill)
+               (declare (ignore name))
+               (push (list :name (skill-name skill) :priority (skill-priority skill) :dependencies (skill-dependencies skill)) results))
+             *skills-registry*)
+    (sort results #'> :key (lambda (x) (getf x :priority)))))
+#+end_src
+
+** Skill Source Inspection (context-skill-source)
+
+Reads the raw literate source of a specific skill for inspection. Used when the agent needs to understand or modify its own code.
+
+#+begin_src lisp
+(defun context-skill-source (skill-name)
+  "Reads the raw literate source of a specific skill for inspection."
+  (let* ((filename (format nil "~a.org" skill-name))
+         (data-dir (uiop:ensure-directory-pathname (or (uiop:getenv "PASSEPARTOUT_DATA_DIR") (namestring (merge-pathnames ".local/share/passepartout/" (user-homedir-pathname))))))
+         (skills-dir (merge-pathnames "skills/" data-dir))
+         (full-path (merge-pathnames filename skills-dir)))
+    (if (uiop:file-exists-p full-path) (uiop:read-file-string full-path) nil)))
+#+end_src
+
+** Harness Logs (context-logs)
+
+Retrieves the most recent lines from the harness's internal log buffer. The log limit is configurable via ~CONTEXT_LOG_LIMIT~ env var (default 20).
+
+#+begin_src lisp
+(defun context-logs (&optional limit)
+  "Retrieves the most recent lines from the harness's internal log."
+  (let ((log-limit (or limit (ignore-errors (parse-integer (uiop:getenv "CONTEXT_LOG_LIMIT"))) 20)))
+    (bt:with-lock-held (*logs-lock*)
+      (let ((count (min log-limit (length *system-logs*)))) 
+        (subseq *system-logs* 0 count)))))
+#+end_src
+
+** AST to Org Rendering (context-object-render)
+
+Recursively renders an ~org-object~ and its children to an Org-mode string, applying the Foveal-Peripheral model:
+
+- Objects within depth 2 are always included (outline)
+- The foveal object (the one the user is looking at) is always included with full content
+- Objects with semantic similarity above the threshold are included with full content
+- All other objects are omitted silently
+
+This function is the heart of the context assembly. Its performance directly affects the agent's response time.
+
+#+begin_src lisp
+(defun context-object-render (obj &key (depth 1) (foveal-id nil) semantic-threshold (foveal-vector nil))
+  "Recursively renders an org-object and its children to an Org string using a Foveal-Peripheral Hybrid model."
+  (let* ((id (org-object-id obj))
+         (is-foveal (equal id foveal-id))
+         (title (or (getf (org-object-attributes obj) :TITLE) "Untitled"))
+         (content (org-object-content obj))
+         (children (org-object-children obj))
+         (stars (make-string depth :initial-element #\*))
+         (obj-vector (org-object-vector obj))
+         (threshold (or semantic-threshold (ignore-errors (read-from-string (uiop:getenv "CONTEXT_SEMANTIC_THRESHOLD"))) 0.75))
+         (similarity (if (and foveal-vector obj-vector (not is-foveal))
+                         (cosine-similarity foveal-vector obj-vector)
+                         0.0))
+         (is-semantically-relevant (>= similarity threshold))
+         (should-render (or (<= depth 2) is-foveal is-semantically-relevant))
+         (output ""))
+    
+    (when should-render
+      (setf output (format nil "~a ~a~%:PROPERTIES:~%:ID: ~a~%" stars title id))
+      (when is-semantically-relevant
+        (setf output (concatenate 'string output (format nil ":SEMANTIC_SCORE: ~,2f~%" similarity))))
+      (setf output (concatenate 'string output (format nil ":END:~%")))
+      
+      (when (and content (or is-foveal is-semantically-relevant))
+        (setf output (concatenate 'string output content (string #\Newline))))
+      
+      (dolist (child-id children)
+        (let ((child-obj (lookup-object child-id)))
+          (when child-obj
+            (let ((next-foveal (if is-foveal child-id foveal-id)))
+              (setf output (concatenate 'string output 
+                                        (context-object-render child-obj 
+                                                               :depth (1+ depth) 
+                                                               :foveal-id next-foveal
+                                                               :semantic-threshold threshold
+                                                               :foveal-vector foveal-vector))))))))
+    output))
+#+end_src
+
+** Path Resolution (context-path-resolve)
+
+Expands environment variables in a path string and strips quotes. Used to resolve configurable paths from ~.env~.
+
+#+begin_src lisp
+(defun context-path-resolve (path-string)
+  "Expands environment variables and strips literal quotes from a path string."
+  (let ((path (if (stringp path-string) 
+                  (string-trim '(#\" #\' #\Space) path-string)
+                  path-string)))
+    (if (and (stringp path) (search "$" path))
+        (let ((result path))
+          (ppcre:do-register-groups (var-name) ("\\$([A-Za-z0-9_]+)" path)
+            (let ((var-val (uiop:getenv var-name)))
+              (when var-val
+                (setf result (ppcre:regex-replace (format nil "\\$~a" var-name) result var-val)))))
+          result)
+        path)))
+#+end_src
+
+** Privacy Filter for Context Assembly
+
+Checks if an org-object has tags matching the Bouncer's ~bouncer-privacy-tags~. Objects with matching tags are excluded from the LLM's context window. This prevents private content tagged with ~@personal~ (or any user-configured privacy tag) from being included in prompts sent to external LLM providers.
+
+#+begin_src lisp
+(defun context-privacy-filtered-p (obj)
+  "Returns T if an org-object's :TAGS attribute matches bouncer-privacy-tags."
+  (let* ((attrs (org-object-attributes obj))
+         (tags (getf attrs :TAGS))
+         (privacy-tags (and (find-package :passepartout.security-dispatcher)
+                            (symbol-value
+                             (find-symbol "BOUNCER-PRIVACY-TAGS"
+                                          :passepartout.security-dispatcher)))))
+    (when (and tags privacy-tags)
+      (let ((tag-list (if (listp tags) tags (list tags))))
+        (some (lambda (tag)
+                (some (lambda (private)
+                        (string-equal (string-trim '(#\:) tag)
+                                      (string-trim '(#\:) private)))
+                      privacy-tags))
+              tag-list)))))
+#+end_src
+
+** Global Awareness (context-awareness-assemble)
+
+Produces the high-level skeletal outline of the current Memory that is included in every LLM call. This is the "peripheral vision" of the agent — it knows what projects exist, their titles and IDs, but not their full content.
+
+Privacy-filtered projects (those with tags matching ~bouncer-privacy-tags~) are excluded from the output.
+
+#+begin_src lisp
+(defun context-awareness-assemble (&optional signal)
+  "Produces a high-level skeletal outline of the current Memory for the LLM.
+Privacy-filtered objects (matching bouncer-privacy-tags) are excluded."
+  (let* ((foveal-id (or (getf signal :foveal-focus) 
+                        (ignore-errors (getf (getf signal :payload) :target-id))))
+         (all-projects (context-active-projects))
+         (projects (remove-if #'context-privacy-filtered-p all-projects))
+         (output (format nil "GLOBAL MEMEX AWARENESS (Peripheral Vision):~%")))
+    (if projects
+        (dolist (project projects)
+          (setf output (concatenate 'string output
+                                    (context-object-render project :foveal-id foveal-id))))
+        (setf output (concatenate 'string output "No active projects found.~%")))
+    output))
+#+end_src
+
+* Test Suite
+Verifies that the Foveal-Peripheral rendering correctly distinguishes between foveal (detailed) and peripheral (outline) content, and that the awareness budget includes all active projects.
+#+begin_src lisp :tangle ../lisp/core-context.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-peripheral-vision-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:vision-suite))
+(in-package :passepartout-peripheral-vision-tests)
+
+(def-suite vision-suite :description "Verification of Foveal-Peripheral context model.")
+(in-suite vision-suite)
+
+(test test-foveal-rendering
+  (clrhash passepartout::*memory*)
+  (let* ((ast '(:type :HEADLINE :properties (:ID "proj-root" :TITLE "Project" :TAGS ("project"))
+                :contents ((:type :HEADLINE :properties (:ID "node-foveal" :TITLE "Foveal Node")
+                             :raw-content "FOVEAL CONTENT" :contents nil)
+                            (:type :HEADLINE :properties (:ID "node-peripheral" :TITLE "Peripheral Node")
+                             :raw-content "PERIPHERAL CONTENT" :contents nil)))))
+    (ingest-ast ast)
+    (let ((output (context-awareness-assemble (list :foveal-focus "node-foveal"))))
+      (is (search "FOVEAL CONTENT" output))
+      (is (search "* Peripheral Node" output))
+      (is (not (search "PERIPHERAL CONTENT" output))))))
+
+(test test-awareness-budget
+  (clrhash passepartout::*memory*)
+  (ingest-ast '(:type :HEADLINE :properties (:ID "p1" :TITLE "Project 1" :TAGS ("project")) :contents nil))
+  (ingest-ast '(:type :HEADLINE :properties (:ID "p2" :TITLE "Project 2" :TAGS ("project")) :contents nil))
+  (let ((output (context-awareness-assemble)))
+    (is (search "Project 1" output))
+    (is (search "Project 2" output))))
+#+end_src

org/core-defpackage.org

@@ -0,0 +1,290 @@
+#+TITLE: Core: Package Definition (core-defpackage.org)
+#+AUTHOR: Agent
+#+FILETAGS: :passepartout:core:defpackage:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-defpackage.lisp
+
+* Overview: Architectural Intent
+
+~package.lisp~ defines two things: the public API of the ~passepartout~ package (the export list), and the implementation of low-level utility functions and global state that don't belong in a specific pipeline stage or skill.
+
+The export list is the contract between the harness and all skills. Every function exported here is accessible to every skill via ~use-package~. Adding a symbol here is an API commitment; removing one is a breaking change.
+
+The implementation section includes:
+- ~plist-get~ — robust plist accessor used everywhere in the pipeline
+- Logging state (~*log-buffer*~, ~*log-lock*~) — bounded ring buffer for LLM context
+- Skill registry (~*skill-registry*~, ~defskill~) — all loaded skills live here
+- Cognitive tool registry (~*cognitive-tool-registry*~, ~def-cognitive-tool~, ~cognitive-tool-prompt~)
+- Telemetry tracking (~*telemetry-table*~, ~telemetry-track~) — performance metrics per skill
+- Debugger hook — replaces raw SBCL debugger with a friendly error message
+
+* Implementation
+
+** Package Definition and Export List
+The package definition. All public symbols are exported here.
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defpackage :passepartout
+  (:use :cl)
+  (:export
+   #:frame-message
+   #:read-framed-message
+   #:PROTO-GET
+   #:LIST-OBJECTS-WITH-ATTRIBUTE
+   #:COSINE-SIMILARITY
+   #:VAULT-MASK-STRING
+   #:*VAULT-MEMORY*
+   #:parse-message
+   #:make-hello-message
+   #:validate-communication-protocol-schema
+   #:start-daemon
+   #:stop-daemon
+   #:log-message
+   #:main
+   #:doctor-run-all
+   #:doctor-main
+   #:doctor-check-dependencies
+   #:doctor-check-env
+   #:register-provider
+   #:system-ready-p
+   #:run-setup-wizard
+   #:skill-gateway-register
+   #:skill-gateway-link
+   #:gateway-manager-main
+   #:ingest-ast
+   #:lookup-object
+   #:list-objects-by-type
+   #:org-id-new
+   #:*memory*
+   #:*history-store*
+   #:org-object
+   #:make-org-object
+   #:org-object-id
+   #:org-object-type
+   #:org-object-attributes
+   #:org-object-parent-id
+   #:org-object-children
+   #:org-object-version
+   #:org-object-last-sync
+   #:org-object-vector
+   #:org-object-content
+   #:org-object-hash
+   #:snapshot-memory
+   #:rollback-memory
+   #:context-query-store
+   #:context-get-active-projects
+   #:context-get-recent-completed-tasks
+   #:context-list-all-skills
+   #:context-get-skill-source
+   #:context-get-system-logs
+   #:context-resolve-path
+   #:context-get-skill-telemetry
+   #:telemetry-track
+   #:context-assemble-global-awareness
+   #:loop-process
+   #:loop-process
+   #:perceive-gate
+   #:probabilistic-gate
+   #:consensus-gate
+   #:act-gate
+   #:reason-gate
+   #:dispatch-gate
+   #:inject-stimulus
+   #:initialize-actuators
+   #:dispatch-action
+   #:register-actuator
+   #:load-skill-from-org
+   #:skill-initialize-all
+   #:load-skill-with-timeout
+   #:topological-sort-skills
+   #:validate-lisp-syntax
+   #:defskill
+   #:*skill-registry*
+   #:skill
+   #:skill-name
+   #:skill-priority
+   #:skill-dependencies
+   #:skill-trigger-fn
+   #:skill-probabilistic-prompt
+   #:skill-deterministic-fn
+   #:def-cognitive-tool
+   #:*cognitive-tool-registry*
+   #:verify-git-clean-p
+   #:engineering-standards-verify-lisp
+   #:engineering-standards-format-lisp
+   #:literate-check-block-balance
+   #:check-tangle-sync
+   #:*tangle-targets*
+   #:utils-org-read-file
+   #:utils-org-write-file
+   #:utils-org-add-headline
+   #:utils-org-set-property
+   #:utils-org-set-todo
+   #:utils-org-find-headline-by-id
+   #:utils-org-find-headline-by-title
+   #:utils-org-generate-id
+   #:utils-org-id-format
+   #:utils-org-ast-to-org
+   #:utils-org-modify
+   #:utils-lisp-validate
+   #:utils-lisp-check-structural
+   #:utils-lisp-check-syntactic
+   #:utils-lisp-check-semantic
+   #:utils-lisp-eval
+   #:utils-lisp-format
+   #:utils-lisp-list-definitions
+   #:utils-lisp-structural-extract
+   #:utils-lisp-structural-wrap
+   #:utils-lisp-structural-inject
+   #:utils-lisp-structural-slurp
+   #:utils-lisp-register
+   #:get-oc-config-dir
+   #:prompt-for
+   #:save-secret
+   #:get-tool-permission
+   #:set-tool-permission
+   #:check-tool-permission-gate
+   #:cognitive-tool
+   #:cognitive-tool-name
+   #:cognitive-tool-description
+   #:cognitive-tool-parameters
+   #:cognitive-tool-guard
+   #:cognitive-tool-body
+   #:*emacs-clients*
+   #:*clients-lock*
+   #:register-emacs-client
+   #:unregister-emacs-client
+   #:ask-probabilistic
+   #:register-probabilistic-backend
+   #:distill-prompt
+   #:*probabilistic-backends*
+   #:*provider-cascade*
+   #:vault-get-secret
+   #:vault-set-secret
+   #:memory-objects-by-attribute
+   #:deterministic-verify
+   #:find-headline-missing-id))
+#+end_src
+
+** Package Implementation
+The package implementation section defines the low-level utilities and global state that are shared across all harness components and skills.
+
+*** Robust plist access (plist-get)
+Retrieves a value from a plist, checking both upper and lowercase keyword variants. This is needed because different components use different keyword conventions.
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(in-package :passepartout)
+
+(defun plist-get (plist key)
+  "Robust plist accessor — checks both :KEY and :key variants."
+  (let* ((s (string key))
+         (up (intern (string-upcase s) :keyword))
+         (dn (intern (string-downcase s) :keyword)))
+    (or (getf plist up) (getf plist dn))))
+#+end_src
+
+*** Logging state
+The harness maintains a bounded ring buffer of log messages for inclusion in LLM context. Access is thread-safe via a lock.
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defvar *log-buffer* nil)
+(defvar *log-lock* (bordeaux-threads:make-lock "log-messages-lock"))
+(defvar *log-limit* 100)
+#+end_src
+
+*** Skill registry
+The global registry of all loaded skills. This is the authoritative list that the deterministic engine iterates.
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defvar *skill-registry* (make-hash-table :test 'equal)
+  "Global registry of all loaded skills.")
+#+end_src
+
+*** Skill telemetry
+Tracks execution metrics per skill (count, duration, failures) for diagnostics and performance analysis.
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defvar *telemetry-table* (make-hash-table :test 'equal))
+(defvar *telemetry-lock* (bordeaux-threads:make-lock "harness-telemetry-lock"))
+
+(defun telemetry-track (skill-name duration status)
+  "Updates performance metrics for a skill. STATUS is :success or :rejected."
+  (when skill-name
+    (bordeaux-threads:with-lock-held (*telemetry-lock*)
+      (let ((entry (or (gethash skill-name *telemetry-table*) (list :executions 0 :total-time 0 :failures 0))))
+        (incf (getf entry :executions))
+        (incf (getf entry :total-time) duration)
+        (when (eq status :rejected) (incf (getf entry :failures)))
+        (setf (gethash skill-name *telemetry-table*) entry)))))
+#+end_src
+
+*** Cognitive tool registry
+Tools that the LLM can invoke are registered here. Each tool has a name, description, parameters, optional guard, and implementation body. The ~def-cognitive-tool~ macro handles registration. ~cognitive-tool-prompt~ serialises the registry into the LLM's system prompt.
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defvar *cognitive-tool-registry* (make-hash-table :test 'equal))
+#+end_src
+
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defstruct cognitive-tool
+  name
+  description
+  parameters
+  guard
+  body)
+#+end_src
+
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defmacro def-cognitive-tool (name description parameters &key guard body)
+  "Registers a cognitive tool. PARAMETERS is a list of plists, one per parameter."
+  `(setf (gethash (string-downcase (string ',name)) *cognitive-tool-registry*)
+         (make-cognitive-tool :name (string-downcase (string ',name))
+                              :description ,description
+                              :parameters ',parameters
+                              :guard ,guard
+                              :body ,body)))
+#+end_src
+
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defun cognitive-tool-prompt ()
+  "Serialises all registered tools into a prompt string for the LLM."
+  (let ((descriptions nil))
+    (maphash (lambda (k tool)
+               (declare (ignore k))
+               (push (format nil "- ~a: ~a~%  Parameters: ~a~%"
+                             (cognitive-tool-name tool)
+                             (cognitive-tool-description tool)
+                             (cognitive-tool-parameters tool))
+                     descriptions))
+              *cognitive-tool-registry*)
+    (if descriptions
+        (format nil "Available tools:~%~a" (apply #'concatenate 'string (sort descriptions #'string<)))
+        "No tools registered.")))
+#+end_src
+
+*** Centralized logging (log-message)
+Thread-safe logging function that writes to both the ring buffer (for LLM context) and stdout (for the user). Bounded by ~*log-limit*~.
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(defun log-message (msg &rest args)
+  "Centralized, thread-safe logging for the harness."
+  (let ((formatted-msg (apply #'format nil msg args)))
+    (bordeaux-threads:with-lock-held (*log-lock*)
+      (push formatted-msg *log-buffer*)
+      (when (> (length *log-buffer*) *log-limit*)
+        (setq *log-buffer* (subseq *log-buffer* 0 *log-limit*))))
+    (format t "~a~%" formatted-msg)
+    (finish-output)))
+#+end_src
+
+*** Debugger hook
+Friendly error handler that replaces the raw SBCL debugger with a diagnostic message. This prevents the agent from entering the debugger on unhandled conditions.
+#+begin_src lisp :tangle ../lisp/core-defpackage.lisp
+(setf *debugger-hook* (lambda (condition hook)
+  "Friendly error handler - shows diagnostic message instead of raw debugger."
+  (declare (ignore hook))
+  (format t "~%")
+  (format t "┌─────────────────────────────────────────────┐~%")
+  (format t "│  ERROR: ~A~%" (type-of condition))
+  (format t "│~%")
+  (format t "│  Run: passepartout doctor~%")
+  (format t "│  For system diagnostics~%")
+  (format t "└─────────────────────────────────────────────┘~%")
+  (format t "~%")
+  (format t "Details: ~A~%" condition)
+  (finish-output)
+  (uiop:quit 1)))
+#+end_src

org/core-loop-act.org

@@ -0,0 +1,241 @@
+#+TITLE: Stage 3: Act (act.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:act:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-loop-act.lisp
+
+* Overview: Architectural Intent
+
+The Act stage is where cognition meets reality. After the Probabilistic engine proposes an action and the Deterministic engine verifies it, Act executes it through the appropriate actuator.
+
+An actuator is a function that takes (action context) and performs a physical operation: send a message to the TUI, execute a shell command, call a Telegram API, write to a file. Actuators are registered in a global hash table (~*actuator-registry*~) and dispatched by name.
+
+The key architectural choice: **actuators are not privileged**. The same dispatch mechanism that routes to :shell or :file also routes to :telegram or :signal. There is no special handling for dangerous actuators — safety is enforced at the Reason stage by the deterministic engine, not by Act. This means:
+
+1. Adding a new actuator requires no changes to the core — just register it
+2. Safety is centralized in the deterministic gates, not scattered across actuator implementations
+3. Every actuator benefits from the same security checks (the Bouncer, the Policy)
+
+** Why Dispatch-Action Verifies Again?
+
+The Reason stage already ran every proposed action through the deterministic engine. So why does ~loop-gate-act~ call ~deterministic-verify~ again?
+
+Because a skill's deterministic gate runs during Reason, but between Reason and Act, the action might have been transformed by the pipeline (metadata added, format normalized). The last-mile verification catches any transformation that might have introduced an unsafe property. It's the same philosophy as "trust but verify" — the second check is cheap and catches a class of bugs that would otherwise be silent data corruption.
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** Actuator Configuration
+
+~*actuator-default*~ determines where actions go when no explicit target is specified. Defaults to ~:cli~.
+
+~*actuator-silent*~ lists actuator targets that don't generate tool-output feedback. For example, sending a message to the CLI or Emacs doesn't need to produce a tool-output event — the user can see the message directly. This prevents redundant feedback loops.
+
+#+begin_src lisp
+(defvar *actuator-default* :cli
+  "The actuator used when no explicit target is specified.")
+
+(defvar *actuator-silent* '(:cli :system-message :emacs)
+  "List of actuators that don't generate tool-output feedback.")
+
+(defun actuator-initialize ()
+  "Register core actuators and load configuration."
+  (let ((def (uiop:getenv "DEFAULT_ACTUATOR"))
+        (silent (uiop:getenv "SILENT_ACTUATORS")))
+    (when def
+      (setf *actuator-default* (intern (string-upcase def) :keyword)))
+    (when silent
+      (setf *actuator-silent*
+            (mapcar (lambda (s) (intern (string-upcase (string-trim '(#\Space) s)) :keyword))
+                    (uiop:split-string silent :separator '(#\,))))))
+
+  (register-actuator :system #'action-system-execute)
+  (register-actuator :tool #'action-tool-execute)
+
+  (register-actuator :tui (lambda (action context)
+                            (declare (ignore context))
+                            (let* ((meta (getf action :meta))
+                                   (stream (getf meta :reply-stream)))
+                              (when (and stream (open-stream-p stream))
+                                (format stream "~a" (frame-message action))
+                                (finish-output stream))))))
+#+end_src
+
+** Action Dispatch (action-dispatch)
+
+Routes an approved action to its registered actuator. The target is resolved in priority order:
+
+1. The explicit ~:target~ field on the action
+2. The source of the original signal (reply to the sender)
+3. The default actuator (~:cli~)
+
+Heartbeats are silently dropped here — they should never generate an actuation.
+
+#+begin_src lisp
+(defun action-dispatch (action context)
+  "Route an approved action to its registered actuator."
+  (let ((payload (proto-get action :payload)))
+    (when (eq (proto-get payload :sensor) :heartbeat)
+      (return-from action-dispatch nil))
+
+    (when (and action (listp action))
+      (let* ((meta (proto-get context :meta))
+             (source (proto-get meta :source))
+             (raw-target (or (proto-get action :target) source *actuator-default*))
+             (target (intern (string-upcase (string raw-target)) :keyword))
+             (actuator-fn (gethash target *actuator-registry*)))
+        (when (and meta (null (getf action :meta)))
+          (setf (getf action :meta) meta))
+        (if actuator-fn
+            (funcall actuator-fn action context)
+            (harness-log "ACT ERROR: No actuator registered for '~s'" target))))))
+#+end_src
+
+** System Actuator (action-system-execute)
+
+Handles internal harness commands: ~:eval~ (execute arbitrary Lisp) and ~:message~ (log to the harness log). This is how the deterministic engine communicates results back to the user.
+
+#+begin_src lisp
+(defun action-system-execute (action context)
+  "Execute internal harness commands."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (cmd (getf payload :action)))
+    (case cmd
+      (:eval
+       (eval (read-from-string (getf payload :code))))
+      (:message
+       (harness-log "ACT [System]: ~a" (getf payload :text)))
+      (t
+       (harness-log "ACT ERROR [System]: Unknown command '~s'" cmd)))))
+#+end_src
+
+** Tool Actuator (action-tool-execute)
+
+Executes a registered cognitive tool. Cognitive tools are registered via ~def-cognitive-tool~ in the package.lisp and are the primary way the LLM interacts with the outside world.
+
+The function handles:
+- Tool dispatch by name (case-insensitive lookup)
+- Argument normalization (if the arguments are nested in a list, they're flattened)
+- Result formatting (structured results are sent back to the source)
+- Error handling (tool errors produce ~:tool-error~ events, not crashes)
+
+The tool's return value is packed into a ~:tool-output~ event and fed back into the pipeline, where it becomes the next perception. This is how the agent "sees" the result of its actions.
+
+#+begin_src lisp
+(defun action-tool-execute (action context)
+  "Execute a registered cognitive tool."
+  (let* ((payload (getf action :payload))
+         (tool-name (getf payload :tool))
+         (tool-args (getf payload :args))
+         (depth (getf context :depth 0))
+         (meta (getf context :meta))
+         (source (getf meta :source))
+         (tool (gethash (string-downcase (string tool-name)) *cognitive-tools*)))
+    (if tool
+        (handler-case
+            (let* ((clean-args (if (and (listp tool-args) (listp (car tool-args))) (car tool-args) tool-args))
+                   (result (funcall (cognitive-tool-body tool) clean-args)))
+              (when source
+                (action-dispatch (list :TYPE :REQUEST :TARGET source 
+                                       :PAYLOAD (list :ACTION :MESSAGE :TEXT (tool-result-format tool-name result)))
+                                context))
+              (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
+                    :PAYLOAD (list :SENSOR :tool-output :RESULT result :TOOL tool-name)))
+          (error (c)
+            (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
+                  :PAYLOAD (list :SENSOR :tool-error :TOOL tool-name :MESSAGE (format nil "~a" c)))))
+        (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
+              :PAYLOAD (list :SENSOR :tool-error :MESSAGE (format nil "Tool '~a' not found" tool-name))))))
+#+end_src
+
+** Tool Result Formatting (tool-result-format)
+
+Converts a tool's return value into a human-readable string for display to the user. Handles structured results (plists with ~:status~, ~:content~, ~:message~) and plain values.
+
+#+begin_src lisp
+(defun tool-result-format (tool-name result)
+  "Format a tool result for display."
+  (if (listp result)
+      (let ((status (getf result :status))
+            (content (getf result :content))
+            (msg (getf result :message)))
+        (cond
+          ((and (eq status :success) content) (format nil "~a" content))
+          ((and (eq status :error) msg) (format nil "ERROR [~a]: ~a" tool-name msg))
+          (t (format nil "TOOL [~a] RESULT: ~s" tool-name result))))
+      (format nil "TOOL [~a] RESULT: ~a" tool-name result)))
+#+end_src
+
+** Act Gate (Stage 3)
+
+The final stage of the metabolic pipeline. It receives a signal that has been reasoned (has an ~:approved-action~) and dispatches it.
+
+The gate runs a last-mile deterministic check on the approved action before execution. This catches any issues introduced during pipeline processing (e.g., metadata added by Perceive that changes the action's format).
+
+After dispatch, the gate captures any feedback produced by the actuation (tool output, error events) and returns it to the loop for the next cognitive cycle.
+
+#+begin_src lisp
+(defun loop-gate-act (signal)
+  "Final stage of the metabolic pipeline: Actuation."
+  (let* ((approved (getf signal :approved-action))
+         (type (getf signal :type))
+         (meta (getf signal :meta))
+         (source (getf meta :source))
+         (feedback nil))
+    (when approved
+      (let* ((original-type (getf approved :type))
+             (verified (deterministic-verify approved signal)))
+        (if (and (listp verified) (member (getf verified :type) '(:LOG :EVENT)) (not (member original-type '(:LOG :EVENT))))
+            (progn
+              (harness-log "ACT BLOCKED: Action failed last-mile deterministic check.")
+              (setf (getf signal :approved-action) nil)
+              (setf feedback verified))
+            (progn
+              (setf (getf signal :approved-action) verified)
+              (setf approved verified)))))
+
+    (case type
+      (:REQUEST (action-dispatch signal signal))
+      (:LOG (action-dispatch signal signal))
+      (:EVENT
+       (if approved
+           (let* ((target (getf approved :target))
+                  (result (action-dispatch approved signal)))
+             (cond
+               ((and (listp result) (member (getf result :type) '(:EVENT :LOG)))
+                (setf feedback result))
+               ((and result (not (member target *actuator-silent*)))
+                (setf feedback (list :type :EVENT :depth (1+ (getf signal :depth 0)) :meta meta
+                                    :payload (list :sensor :tool-output :result result :tool approved))))))
+           (when source (action-dispatch signal signal)))))
+    (setf (getf signal :status) :acted)
+    feedback))
+#+end_src
+
+* Test Suite
+Verifies that the act gate correctly processes an approved action and sets the signal status to ~:acted~.
+#+begin_src lisp :tangle ../lisp/core-loop-act.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-pipeline-act-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:pipeline-act-suite))
+
+(in-package :passepartout-pipeline-act-tests)
+
+(def-suite pipeline-act-suite :description "Test suite for Act pipeline")
+(in-suite pipeline-act-suite)
+
+(test test-loop-gate-act-basic
+  (clrhash passepartout::*skills-registry*)
+  (let* ((signal (list :type :EVENT :status nil :depth 0 :approved-action '(:target :cli :payload (:text "Hello"))))
+         (result (loop-gate-act signal)))
+    (is (eq :acted (getf signal :status)))
+    (is (null result))))
+#+end_src

org/core-loop-perceive.org

@@ -0,0 +1,169 @@
+#+TITLE: Stage 1: Perceive (perceive.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:perceive:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-loop-perceive.lisp
+
+* Overview: Architectural Intent
+
+The Perceive stage is the sensory cortex of Passepartout. It receives raw stimuli from diverse sources — terminal input, Emacs buffers, Telegram messages, Signal chats, heartbeat clocks, shell command outputs — and normalizes them into a single Signal format that the rest of the pipeline can process.
+
+Each source has its own format and protocol. The CLI sends raw text. Emacs sends AST diffs. Telegram sends JSON. Without normalization, every downstream component (Reason, Act) would need to understand every input format. With normalization:
+
+1. The gateway layer (CLI, Emacs, Telegram, Signal) just sends raw messages
+2. Perceive transforms them into Signals regardless of origin
+3. Reason and Act work with a single, consistent plist format
+4. Adding a new gateway requires gateway code only — no changes to core
+
+This is the "thin harness, fat skills" principle applied to input processing. The harness does the minimal normalization needed to produce a uniform Signal; the actual interpretation is left to skills.
+
+** Why the Async/Sync Split?
+
+Perceive handles two kinds of stimuli:
+- **Synchronous** (user input, chat messages) — these must be processed in order, one at a time, because each depends on the state left by the previous one
+- **Asynchronous** (heartbeats, background sensor readings, delegation results) — these can be processed in parallel because they don't depend on user intent
+
+The `*loop-async-sensors*` list defines which sensor types are processed in dedicated threads. Everything else goes through the main synchronous pipeline.
+
+The depth limit prevents runaway recursive loops. A signal that generates another signal that generates another signal can infinite-loop. If depth exceeds a threshold (10), the signal is silently dropped rather than processed. This is the metabolic loop's circuit breaker.
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** Interrupt Flag
+
+A global interrupt flag that can be set by any signal. When set, the metabolic loop should stop processing and clean up. This is used for graceful shutdown: a SIGINT or /exit command sets the flag, and the loop exits at the next cycle boundary.
+
+#+begin_src lisp
+(defvar *loop-interrupt* nil)
+#+end_src
+
+** Sensor Configuration
+
+~*loop-async-sensors*~ lists the sensor types that should be processed in their own threads. Currently, ~:chat-message~, ~:delegation~, and ~:user-command~ are async because they don't block the main reasoning loop — the agent can process a Telegram message while waiting for the user's next input.
+
+~*loop-focus-id*~ tracks what the user is currently looking at in Emacs. When the user moves their cursor to a different Org headline, the buffer-update signal updates this ID. The Reason stage uses it to build the foveal-peripheral context model: the current headline gets full detail, everything else gets a skeletal outline.
+
+#+begin_src lisp
+(defvar *loop-async-sensors* '(:chat-message :delegation :user-command)
+  "Sensors that are processed in dedicated threads.")
+
+(defvar *loop-focus-id* nil
+  "The Org ID of the node the user is currently interacting with.")
+#+end_src
+
+** Stimulus Injection (stimulus-inject)
+
+This is the entry point that gateways call to send a message into the cognitive pipeline. It sets metadata (source, session ID, reply stream), decides whether the stimulus should be processed synchronously or on a background thread, and wraps the whole thing in error recovery so that no single bad stimulus can crash the system.
+
+The error recovery uses Common Lisp's restart system. If any error occurs during processing, a `skip-event` restart is available. The handler displays the error, then invokes `skip-event` which drops the stimulus and continues. This is the "fail open" safety model — better to drop one message than to crash the entire agent.
+
+#+begin_src lisp
+(defun stimulus-inject (raw-message &key stream (depth 0))
+  "Inject a raw message into the signal processing pipeline."
+  (let* ((payload (getf raw-message :payload))
+         (sensor (getf payload :sensor))
+         (meta (getf raw-message :meta))
+         (async-p (or (getf payload :async-p)
+                     (member sensor *loop-async-sensors*))))
+
+    (unless meta
+      (setf meta (list :SOURCE :SYSTEM :SESSION-ID "internal")))
+
+    (when stream
+      (setf (getf meta :reply-stream) stream))
+
+    (setf (getf raw-message :meta) meta)
+    (setf (getf raw-message :depth) depth)
+
+    (if async-p
+        (bt:make-thread
+         (lambda ()
+           (restart-case (process-signal raw-message)
+             (skip-event () nil)))
+         :name "passepartout-async-task")
+        
+        (restart-case
+            (handler-bind ((error (lambda (c)
+                                    (harness-log "SYSTEM ERROR: ~a" c)
+                                    (invoke-restart 'skip-event))))
+              (process-signal raw-message))
+          (skip-event ()
+            (harness-log "SYSTEM RECOVERY: Stimulus dropped."))))))
+#+end_src
+
+** Perceive Gate (loop-gate-perceive)
+
+The perceive gate is the first stage of the metabolic pipeline. It receives a normalized signal and routes it based on the event type:
+
+- ~:EVENT~ with ~:buffer-update~ — an Emacs buffer changed (new Org headline created, text edited). The change is ingested into memory so the agent has the latest state.
+- ~:EVENT~ with ~:point-update~ — the user moved their cursor to a different headline. The foveal focus is updated, and the node at the cursor is ingested at higher priority.
+- ~:EVENT~ with ~:interrupt~ — the user requested an interrupt. The interrupt flag is set.
+- ~:RESPONSE~ — an action completed. The gate logs the result status.
+
+All signals get tagged with their processing stage (`:status :perceived`) and the current foveal focus before being passed to the Reason stage.
+
+#+begin_src lisp
+(defun loop-gate-perceive (signal)
+  "Stage 1 of the metabolic pipeline: Normalize sensory input."
+  (let* ((payload (getf signal :payload))
+         (type (getf signal :type))
+         (meta (getf signal :meta))
+         (sensor (getf payload :sensor)))
+
+    (harness-log "GATE [Perceive]: ~a (~a) [Source: ~s]"
+                 type (or sensor "no-sensor") (getf meta :source))
+
+    (cond ((eq type :EVENT)
+           (case sensor
+             (:buffer-update
+              (let ((ast (getf payload :ast)))
+                (when ast
+                  (snapshot-memory)
+                  (ingest-ast ast))))
+             (:point-update
+              (let ((element (getf payload :element)))
+                (when element
+                  (snapshot-memory)
+                  (setf *loop-focus-id* (getf element :id))
+                  (ingest-ast element))))
+             (:interrupt
+              (setf *loop-interrupt* t))))
+          ((eq type :RESPONSE)
+           (harness-log "GATE [Perceive]: Act Result -> ~a" (getf payload :status))))
+
+    (setf (getf signal :status) :perceived)
+    (setf (getf signal :foveal-focus) *loop-focus-id*)
+    signal))
+#+end_src
+
+* Test Suite
+Verifies that the perceive gate correctly ingests AST nodes into memory and that the depth limiter prevents runaway recursive signals.
+#+begin_src lisp :tangle ../lisp/core-loop-perceive.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-pipeline-perceive-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:pipeline-perceive-suite))
+
+(in-package :passepartout-pipeline-perceive-tests)
+
+(def-suite pipeline-perceive-suite :description "Test suite for Perceive pipeline")
+(in-suite pipeline-perceive-suite)
+
+(test test-loop-gate-perceive
+  (clrhash passepartout::*memory*)
+  (let* ((signal (list :type :EVENT :payload (list :sensor :buffer-update :ast (list :type :HEADLINE :properties (list :ID "test-node" :TITLE "Test") :contents nil))))
+         (result (loop-gate-perceive signal)))
+    (is (eq :perceived (getf result :status)))
+    (is (not (null (gethash "test-node" passepartout::*memory*))))))
+
+(test test-depth-limiting
+  (let ((runaway-signal (list :type :EVENT :depth 11 :payload (list :sensor :heartbeat))))
+    (is (null (process-signal runaway-signal)))))
+#+end_src

org/core-loop-reason.org

@@ -0,0 +1,318 @@
+#+TITLE: Stage 2: Reason (reason.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:reason:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-loop-reason.lisp
+
+* Overview: Architectural Intent
+
+The Reason stage is the cognitive heart of Passepartout. It takes a normalized signal from Perceive and produces an approved action for Act. This is where the two engines — probabilistic (LLM) and deterministic (Lisp logic) — collaborate.
+
+The design is shaped by one non-negotiable constraint: **the LLM must never touch the actuators directly.** Every action the LLM proposes must pass through a deterministic verification gate that has the final say. This is what separates Passepartout from every other AI agent: the creative brain suggests, but the logical brain decides.
+
+** The Probabilistic-Deterministic Split
+
+An LLM is a statistical engine. Given enough context, it is remarkably good at translation, generation, and pattern matching. But it cannot be trusted with authority because hallucination is a *fundamental property* of probabilistic inference — the model generates the most likely continuation, not the correct one.
+
+The deterministic engine addresses this by being what the probabilistic engine is not: mathematically rigorous, formally verifiable, and incapable of hallucination by design. It operates on explicit symbolic representations — lists, property lists, knowledge graphs — not on floating-point activations. When it evaluates a path confinement check, it returns true or false, not a probability distribution.
+
+The division of labor is architectural:
+- The LLM handles the fuzzy interface between human language and structured representation
+- The deterministic engine receives those structured representations and evaluates them against formal invariants
+- The LLM never reads a file, never executes a command, never modifies memory — it generates proposals
+
+This separation is the source of Passepartout's safety guarantee. Other agents add "guardrails" as an afterthought — a layer of filtering around a dangerous core. Passepartout makes the division explicit.
+
+** Why Plists for Communication?
+
+Every message in the Reason pipeline is a property list (plist):
+
+  (TYPE :REQUEST TARGET :CLI PAYLOAD (ACTION :MESSAGE TEXT "Hello"))
+
+A plist is simultaneously:
+- Human-readable text
+- Machine-parseable data structure
+- Executable Lisp code
+
+This is not a cosmetic choice. It means the reasoning pipeline can generate, modify, and execute its own communication protocol without external parsing libraries. There is no JSON encoder, no schema validator, no serialization layer between the two engines. They speak the same language because they *are* the same language.
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** Probabilistic Engine State
+
+The probabilistic engine maintains four pieces of global state that control how LLM requests are dispatched:
+
+~*backend-registry*~ is a hash table mapping provider keywords (like ~:ollama~ or ~:openrouter~) to the actual function that calls that provider's API. ~*provider-cascade*~ is the ordered list of providers to try — if the first one fails, the cascade falls through to the next. ~*model-selector*~ is an optional function that examines the context and picks a model per request (useful for routing simple questions to a small fast model and complex reasoning to a large expensive one). ~*consensus-enabled*~ toggles multi-provider agreement, where multiple LLMs run the same prompt and the system waits for consensus.
+
+These variables are configurable at runtime. The cascade can be changed without restart: (setf *provider-cascade* (quote (:ollama :openrouter))).
+
+#+begin_src lisp
+(defvar *backend-registry* (make-hash-table :test 'equal))
+#+end_src
+
+#+begin_src lisp
+(defvar *provider-cascade* nil)
+#+end_src
+
+#+begin_src lisp
+(defvar *model-selector* nil)
+#+end_src
+
+#+begin_src lisp
+(defvar *consensus-enabled* nil)
+#+end_src
+
+** Backend Registration (backend-register)
+
+Each LLM provider registers itself by calling this function. The backend function receives a prompt string, a system prompt string, and optional keyword arguments for model selection. It must return either a plist with ~:status :success~ and ~:content~, or ~:status :error~ with a message.
+
+Registration is typically done at boot time by the unified-llm-backend skill, but can also be done dynamically:
+  (backend-register :my-custom-provider #'my-fn)
+
+#+begin_src lisp
+(defun backend-register (name fn)
+  (setf (gethash name *backend-registry*) fn))
+#+end_src
+
+** Cascade Dispatch (backend-cascade-call)
+
+Given a prompt, this function iterates through the provider cascade and calls each backend in order until one succeeds. A provider "succeeds" when it returns ~:status :success~ with content, or when it returns a plain string (the LLM's raw output).
+
+The function has a fallback for every failure mode:
+- If a backend returns ~:status :error~, the cascade moves to the next provider
+- If a backend throws an exception, it is caught and logged, and the cascade moves on
+- If ALL backends are exhausted, a structured LOG message is returned saying "Neural Cascade Failure"
+
+This is deliberately resilient. The system should never crash because an LLM provider is down. It should log the failure, try the next provider, and if all fail, return a diagnostic message that the deterministic engine can present to the user.
+
+#+begin_src lisp
+(defun backend-cascade-call (prompt &key
+                                (system-prompt "You are the Probabilistic engine.")
+                                (cascade nil)
+                                (context nil))
+  (let ((backends (or cascade *provider-cascade*)))
+    (or (dolist (backend backends)
+          (let ((backend-fn (gethash backend *backend-registry*)))
+            (when backend-fn
+              (harness-log "PROBABILISTIC: Attempting backend ~a..." backend)
+              (let* ((model (when *model-selector*
+                              (funcall *model-selector* backend context)))
+                     (result (if model
+                                 (funcall backend-fn prompt system-prompt :model model)
+                                 (funcall backend-fn prompt system-prompt))))
+                (cond ((and (listp result) (eq (getf result :status) :success))
+                       (return (getf result :content)))
+                      ((stringp result)
+                       (return result))
+                      (t
+                       (harness-log "PROBABILISTIC: Backend ~a failed: ~a"
+                                   backend (getf result :message))))))))
+        (list :type :LOG
+              :payload (list :text "Neural Cascade Failure: All providers exhausted.")))))
+#+end_src
+
+** Cognitive Proposal Generation (think)
+
+The ~think~ function is where the creative brain does its work. It assembles the full context for the LLM: the system identity, the available tools, the current global context from memory, the recent system logs, and any rejection trace from a previous failed proposal. It also collects augment strings from any skill that has registered a ~system-prompt-augment~ function.
+
+A note on the augment system: skills can contribute context-specific mandates to the LLM prompt. For example, the REPL skill injects the "prototype in the REPL first" mandate when the context suggests the agent is editing Lisp code. This keeps domain-specific instructions out of the harness while still ensuring they appear in the prompt when relevant.
+
+The LLM's response is expected to be a plist. If it is, it gets parsed and normalized. If it's a string that starts with ~(~ or ~[~, it's read as Lisp data. If it's neither, it falls back to a REQUEST with a MESSAGE action — the raw text.
+
+** Pre-processing: strip markdown from LLM output
+
+LLMs often wrap structured output in markdown code fences:
+
+  ```lisp
+  (:TYPE :REQUEST ...)
+  ```
+
+This function strips the fences so the reader can parse the plist.
+
+#+begin_src lisp
+(defun markdown-strip (text)
+  (if (and text (stringp text))
+      (let ((cleaned text))
+        (setf cleaned (cl-ppcre:regex-replace-all "^```[a-z]*\\n" cleaned ""))
+        (setf cleaned (cl-ppcre:regex-replace-all "\\n```$" cleaned ""))
+        (setf cleaned (cl-ppcre:regex-replace-all "```" cleaned ""))
+        (string-trim '(#\Space #\Newline #\Tab) cleaned))
+      text))
+#+end_src
+
+** Normalize plist keywords
+
+Lisp keywords are case-sensitive. The LLM might produce ~:payload~ or ~:PAYLOAD~ or ~:Payload~ depending on the model. This function normalizes all keyword keys to uppercase to ensure the deterministic engine receives consistent input.
+
+#+begin_src lisp
+(defun plist-keywords-normalize (plist)
+  (when (listp plist)
+    (loop for (k v) on plist by #'cddr
+          collect (if (and (symbolp k) (not (keywordp k)))
+                       (intern (string k) :keyword)
+                       k)
+          collect v)))
+#+end_src
+
+** Think: assemble context and call the LLM
+
+This is the main entry point for the probabilistic engine. Every cognitive cycle goes through here.
+
+The function handles several cases:
+- If a triggered skill provides a probabilistic prompt generator, that replaces the raw user input
+- If the previous proposal was rejected, the rejection trace is injected into the LLM's context so it can self-correct
+- Skills can augment the system prompt with domain-specific mandates via the ~system-prompt-augment~ mechanism
+
+The system prompt assembly order — identity, tools, context, logs, mandates — is intentional: the most dynamic content (mandates from skills) comes last so it has the most influence on the LLM's output.
+
+#+begin_src lisp
+(defun think (context)
+  (let* ((active-skill (find-triggered-skill context))
+         (tool-belt (generate-tool-belt-prompt))
+         (global-context (context-assemble-global-awareness))
+         (system-logs (context-get-system-logs))
+         (assistant-name (or (uiop:getenv "MEMEX_ASSISTANT") "Agent"))
+         (rejection-trace (proto-get (proto-get context :payload) :rejection-trace))
+         (prompt-generator (when active-skill (skill-probabilistic-prompt active-skill)))
+         (raw-prompt (if prompt-generator
+                         (funcall prompt-generator context)
+                         (let ((p (proto-get (proto-get context :payload) :text)))
+                           (if (and p (stringp p)) p "Maintain metabolic stasis."))))
+         (reflection-feedback (if rejection-trace
+                                  (format nil "~%~%PREVIOUS PROPOSAL REJECTED: ~a" rejection-trace)
+                                  ""))
+         (skill-augments (let ((augments ""))
+                           (maphash (lambda (name skill)
+                                      (declare (ignore name))
+                                      (let ((aug-fn (skill-system-prompt-augment skill)))
+                                        (when aug-fn
+                                          (let ((aug-text (ignore-errors (funcall aug-fn context))))
+                                            (when (and aug-text (stringp aug-text) (> (length aug-text) 0))
+                                              (setf augments (concatenate 'string augments aug-text (string #\Newline))))))))
+                                    *skills-registry*)
+                           (when (> (length augments) 0) augments)))
+         (system-prompt (format nil "IDENTITY: ~a~a~%~%TOOLS:~%~a~%~%CONTEXT:~%~a~%~%LOGS:~%~a~%~a" 
+                                assistant-name reflection-feedback tool-belt global-context system-logs
+                                (or skill-augments ""))))
+    (let* ((thought (backend-cascade-call raw-prompt :system-prompt system-prompt :context context))
+           (cleaned (markdown-strip thought)))
+       (if (and cleaned (stringp cleaned) (> (length cleaned) 0) (or (char= (char cleaned 0) #\() (char= (char cleaned 0) #\[)))
+           (handler-case
+               (let ((parsed (read-from-string cleaned)))
+                 (if (listp parsed)
+                     (plist-keywords-normalize parsed)
+                     (list :TYPE :REQUEST :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned :EXPLANATION "Generated by the Probabilistic engine."))))
+             (error () (list :TYPE :REQUEST :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned :EXPLANATION "Generated by the Probabilistic engine."))))
+            (list :TYPE :REQUEST :PAYLOAD (list :ACTION :MESSAGE :TEXT (if (stringp cleaned) cleaned "No response") :EXPLANATION "Generated by the Probabilistic engine."))))))
+#+end_src
+
+** Deterministic Engine (cognitive-verify)
+
+The deterministic engine is the strict guard. It receives a proposed action from the probabilistic engine and runs it through every registered deterministic gate, sorted by priority.
+
+Skills register deterministic gates via ~defskill~ with the ~:deterministic~ keyword. Each gate is a function that receives (action context) and returns either:
+- A modified action (the gate approves or adjusts the proposal)
+- A LOG or EVENT plist (the gate rejects the proposal with a reason)
+
+Gates run in priority order, highest first. If any gate returns a LOG or EVENT, the proposal is rejected immediately and the rejection reason flows back to the probabilistic engine via the rejection trace. If all gates pass, the proposal is approved.
+
+This architecture makes safety compositional: each skill adds one constraint. The bouncer checks secrets. The policy checks explanations. The shell actuator checks destructive commands. No single skill needs to understand the full security model.
+
+#+begin_src lisp
+(defun cognitive-verify (proposed-action context)
+  (let ((current-action proposed-action)
+        (skills nil))
+    (maphash (lambda (name skill)
+               (declare (ignore name))
+               (when (skill-deterministic-fn skill)
+                 (push skill skills)))
+             *skills-registry*)
+    (setf skills (sort skills #'> :key #'skill-priority))
+    (dolist (skill skills)
+      (let ((trigger (skill-trigger-fn skill))
+            (gate (skill-deterministic-fn skill)))
+        (when (or (null trigger) (ignore-errors (funcall trigger context)))
+          (let ((next-action (funcall gate current-action context)))
+            (when (and (listp next-action)
+                       (member (proto-get next-action :type) '(:LOG :EVENT)))
+              (harness-log "DETERMINISTIC: Intercepted by skill '~a'" (skill-name skill))
+              (return-from cognitive-verify next-action))
+             (when next-action (setf current-action next-action))))))
+    current-action))
+#+end_src
+
+** Reason Gate (Stage 2)
+
+The reason gate is the pipeline stage that orchestrates Think + Determine. It receives a signal, checks if it requires reasoning (only ~:user-input~ and ~:chat-message~ events do), and runs through the cognitive + verification loop.
+
+The loop has retry logic: up to 3 attempts. If the deterministic engine rejects a proposal, the rejection reason is fed back into the next think call so the LLM can self-correct. This loop — propose, reject, correct, re-propose — is the core mechanism by which the agent improves its own output without human intervention.
+
+The retry limit prevents infinite loops. If the LLM cannot produce a passable proposal within 3 attempts, the last rejection reason is attached to the signal and the acted pipeline sees a failed reasoning cycle.
+
+#+begin_src lisp
+(defun loop-gate-reason (signal)
+  (let* ((type (proto-get signal :type))
+         (payload (proto-get signal :payload))
+         (sensor (proto-get payload :sensor)))
+    (unless (and (eq type :EVENT) (member sensor '(:user-input :chat-message)))
+      (return-from loop-gate-reason signal))
+    (let ((retries 3)
+          (current-signal (copy-tree signal))
+          (last-rejection nil))
+      (loop
+        (when (<= retries 0)
+          (setf (getf signal :approved-action) last-rejection)
+          (setf (getf signal :status) :reasoned)
+          (return signal))
+        (when last-rejection
+          (setf (getf (getf current-signal :payload) :rejection-trace) last-rejection))
+        (let ((candidate (think current-signal)))
+          (if (and candidate (listp candidate))
+              (let ((verified (cognitive-verify candidate current-signal)))
+                (if (member (getf verified :type) '(:LOG :EVENT))
+                    (progn (decf retries) (setf last-rejection verified))
+                    (progn
+                      (setf (getf signal :approved-action) verified)
+                      (setf (getf signal :status) :reasoned)
+                      (return signal))))
+              (progn
+                (setf (getf signal :approved-action) nil)
+                (setf (getf signal :status) :reasoned)
+                (return signal))))))))
+#+end_src
+
+* Test Suite
+Verifies that the deterministic engine correctly rejects unsafe actions (like ~rm -rf /~) while allowing safe ones.
+#+begin_src lisp :tangle ../lisp/core-loop-reason.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-pipeline-reason-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:pipeline-reason-suite))
+
+(in-package :passepartout-pipeline-reason-tests)
+
+(def-suite pipeline-reason-suite :description "Test suite for Reason pipeline")
+(in-suite pipeline-reason-suite)
+
+(test test-decide-gate-safety
+  (clrhash passepartout::*skills-registry*)
+  (passepartout::defskill :mock-safety
+    :priority 50
+    :trigger (lambda (ctx) (declare (ignore ctx)) t)
+    :deterministic (lambda (action ctx)
+                    (declare (ignore ctx))
+                    (if (search "rm -rf" (format nil "~s" action))
+                        (list :type :LOG :payload (list :text "Rejected"))
+                        action)))
+  (let* ((candidate '(:type :REQUEST :payload (:action :shell :cmd "rm -rf /")))
+         (signal '(:type :EVENT :payload (:sensor :user-input)))
+         (result (cognitive-verify candidate signal)))
+    (is (eq :LOG (getf result :type)))))
+#+end_src

org/core-loop.org

@@ -0,0 +1,278 @@
+#+TITLE: The Metabolic Loop (loop.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:loop:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-loop.lisp
+
+* Overview: Architectural Intent
+
+The Metabolic Loop is the cranial nerve reflex of Passepartout. While skills provide specialized intelligence, the loop provides the fundamental rhythm of existence: the continuous processing of signals from perception through cognition to action.
+
+Every signal flows through three stages:
+1. **Perceive** — normalize raw input into a standard Signal format
+2. **Reason** — think (LLM) then verify (deterministic gates)
+3. **Act** — dispatch the approved action to the appropriate actuator
+
+If a stage produces a new signal (e.g., the Act stage produces a tool-output event), that signal feeds back into Perceive and the loop continues. This is how the agent has multi-step conversations: each LLM response produces an action, which produces a tool output, which feeds back as a new perception, which triggers the next reasoning cycle.
+
+** Why Separate Stages?
+
+A single function that called the LLM, checked safety, and executed the result would be simpler to write. But it would be impossible to:
+- Test each stage independently (a bug in the LLM call would block safety testing)
+- Insert new stages between P and R or R and A (adding consensus means adding a gate in the middle)
+- Recover from failures mid-pipeline (an LLM timeout shouldn't prevent safety checks on the next cycle)
+
+The stage separation is the functional equivalent of the "thin harness" principle: each stage is a pure function that transforms a signal. The loop is the composition of these functions.
+
+** Why the Depth Limit?
+
+A signal that generates another signal that generates another signal can infinite-loop. The depth limit (max 10) prevents this. If depth exceeds 10, the signal is silently dropped. This is the metabolic loop's circuit breaker.
+
+The three-tier error recovery model:
+1. **Transient errors** (tool failures, network timeouts) — recoverable, generate a :loop-error signal at higher depth for retry
+2. **Critical errors** (undefined functions, malformed data) — require memory rollback to the last snapshot
+3. **Recursive loops** (signals generating more signals indefinitely) — depth limit enforcement
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** Global Interrupt State
+
+Thread-safe interrupt flag. The ~*loop-interrupt-lock*~ mutex protects access so that the signal handler and the main loop don't race on shutdown.
+
+#+begin_src lisp
+(defvar *interrupt-flag* nil
+  "Atomic flag set by signal handlers to trigger graceful shutdown.")
+
+(defvar *loop-interrupt-lock* (bt:make-lock "harness-interrupt-lock")
+  "Mutex protecting *interrupt-flag* access.")
+
+(defvar *heartbeat-thread* nil
+  "Handle to the heartbeat thread.")
+#+end_src
+
+** Core Engine (loop-process)
+
+The entry point to the metabolic pipeline. Each cycle runs Perceive → Reason → Act. If Act produces feedback (a new signal), the loop continues with that signal at the same depth.
+
+The function handles four failure modes:
+- **Depth exceeded**: signal dropped, nil returned
+- **Interrupt flag**: graceful shutdown, nil returned
+- **Handler error**: caught by handler-case, logged, and depending on the sensor type and depth:
+  - Normal errors at low depth → memory rollback + retry as :loop-error
+  - :loop-error and :tool-error at any depth → dropped (avoids infinite retry loops)
+  - High-depth errors (depth > 2) → dropped (avoids cascading failures)
+- **Unhandled error**: the handler-case catches everything, preventing any single bad signal from crashing the agent
+
+#+begin_src lisp
+(defun loop-process (signal)
+  "The entry point to the Metabolic Pipeline: Perceive -> Reason -> Act."
+  (let ((current-signal signal))
+    (loop while current-signal do
+      (let ((depth (getf current-signal :depth 0))
+            (meta (getf current-signal :meta)))
+        (when (> depth 10)
+          (harness-log "METABOLISM ERROR: Max recursion depth reached.")
+          (return nil))
+
+        (when (bt:with-lock-held (*loop-interrupt-lock*) *interrupt-flag*)
+          (harness-log "METABOLISM: Interrupted by shutdown signal.")
+          (return nil))
+
+        (handler-case
+            (progn
+              (setf current-signal (perceive-gate current-signal))
+              (setf current-signal (reason-gate current-signal))
+              (let ((feedback (act-gate current-signal)))
+                (if feedback
+                    (progn
+                      (unless (getf feedback :meta) (setf (getf feedback :meta) meta))
+                      (setf current-signal feedback))
+                    (setf current-signal nil))))
+          (error (c)
+            (let ((sensor (ignore-errors (getf (getf current-signal :payload) :sensor))))
+              (harness-log "METABOLISM CRASH [~a]: ~a" (or sensor :unknown) c)
+              (unless (member sensor '(:loop-error :tool-error :syntax-error))
+                (harness-log "CRITICAL ERROR: Initiating Micro-Rollback.")
+                (rollback-memory 0))
+              (if (or (> depth 2) (member sensor '(:loop-error :tool-error)))
+                  (setf current-signal nil)
+                  (setf current-signal
+                        (list :type :EVENT :depth (1+ depth) :meta meta
+                              :payload (list :sensor :loop-error :message (format nil "~a" c) :depth depth)))))))))))
+#+end_src
+
+** Heartbeat Mechanism
+
+The heartbeat is a background thread that fires every N seconds (configurable via ~HEARTBEAT_INTERVAL~ env var, default 60). On each tick, it:
+
+1. Increments the save counter and saves memory to disk when the counter exceeds the auto-save interval (default 300s)
+2. Injects a ~:heartbeat~ signal into the pipeline
+
+The heartbeat signal is how background skills (Gardener, Scribe) get triggered without user input. These skills have triggers that match ~:sensor :heartbeat~ and run maintenance tasks during idle cycles.
+
+#+begin_src lisp
+(defvar *memory-auto-save-interval* 300)
+(defvar *heartbeat-save-counter* 0)
+
+(defun heartbeat-start ()
+  "Starts the background heartbeat thread."
+  (let ((interval (or (ignore-errors (parse-integer (uiop:getenv "HEARTBEAT_INTERVAL"))) 60))
+        (auto-save (or (ignore-errors (parse-integer (uiop:getenv "MEMORY_AUTO_SAVE_INTERVAL"))) *memory-auto-save-interval*)))
+    (setf *memory-auto-save-interval* auto-save)
+    (setf *heartbeat-save-counter* 0)
+
+    (setf *heartbeat-thread*
+          (bt:make-thread
+           (lambda ()
+             (loop
+               (sleep interval)
+               (incf *heartbeat-save-counter*)
+               (when (>= *heartbeat-save-counter* (/ *memory-auto-save-interval* interval))
+                 (setf *heartbeat-save-counter* 0)
+                 (save-memory-to-disk))
+               (inject-stimulus
+                 (list :type :EVENT :payload (list :sensor :heartbeat :unix-time (get-universal-time))))))
+           :name "passepartout-heartbeat"))))
+#+end_src
+
+** Shutdown Save Flag
+
+Controls whether memory is saved on shutdown. Useful for testing when you want a clean state on next boot.
+
+#+begin_src lisp
+(defvar *shutdown-save-enabled* t)
+#+end_src
+
+** System Health Status
+
+Used by the health check protocol and the daemon's status endpoint. Set by ~diagnostics-startup-run~ during boot.
+
+- ~:healthy~ — all checks passed
+- ~:degraded~ — checks found issues but the daemon can still run
+- ~:unhealthy~ — checks failed, the daemon may not function correctly
+- ~:unknown~ — health check hasn't run yet
+
+#+begin_src lisp
+(defvar *system-health* :unknown
+  "Current system health status: :healthy, :degraded, :unhealthy, or :unknown.")
+
+(defvar *health-check-ran* nil
+  "Flag indicating if initial health check has completed.")
+#+end_src
+
+** Proactive Doctor
+
+Runs the doctor diagnostics automatically at startup. If the doctor finds issues (missing dependencies, misconfigured providers), it prints a diagnostic message but does NOT block the daemon from starting. The user can see the issues and run ~passepartout doctor --fix~ to repair.
+
+This is the "fail open" principle applied to boot: the system should start even with problems, not refuse to start until everything is perfect.
+
+#+begin_src lisp
+(defun diagnostics-startup-run ()
+  "Runs the doctor diagnostics on startup. Returns health status."
+  (format t "~%")
+  (format t "==================================================~%")
+  (format t " DOCTOR: Running Startup Health Check~%")
+  (format t "==================================================~%")
+  (handler-case
+      (progn
+        (when (fboundp 'doctor-run-all)
+          (let ((result (doctor-run-all :auto-install nil)))
+            (setf *health-check-ran* t)
+            (if result
+                (progn
+                  (setf *system-health* :healthy)
+                  (format t "DAEMON: Health check passed. Starting services.~%"))
+                (progn
+                  (setf *system-health* :degraded)
+                  (format t "DAEMON: Health check found issues.~%")
+                  (format t "         Run 'passepartout doctor --fix' to repair.~%")))))
+        (setf *health-check-ran* t))
+    (error (c)
+      (format t "DOCTOR ERROR: ~a~%" c)
+      (setf *system-health* :unhealthy)
+      (setf *health-check-ran* t)))
+  (format t "==================================================~%~%"))
+#+end_src
+
+** Main Entry Point (main)
+
+The top-level entry point. Called by ~passepartout daemon~ and ~passepartout tui~.
+
+Boot sequence:
+1. Load environment variables from ~.config/passepartout/.env~
+2. Load persisted memory state from disk
+3. Register core actuators (:system, :tool, :tui)
+4. Initialize all skills (tangging .lisp or loading from XDG)
+5. Run the proactive health check
+6. Start the heartbeat thread (background maintenance)
+7. Start the TCP daemon (listens for CLI/TUI connections)
+8. Install the SIGINT handler (graceful shutdown on Ctrl+C)
+9. Enter the idle sleep loop (wakes on interrupt)
+
+#+begin_src lisp
+(defun main ()
+  "Entry point for Passepartout. Initializes the system and enters idle loop."
+  (let* ((home (uiop:getenv "HOME"))
+         (env-file (uiop:merge-pathnames* ".config/passepartout/.env" (uiop:ensure-directory-pathname home))))
+    (when (uiop:file-exists-p env-file)
+      (cl-dotenv:load-env env-file)))
+
+  (load-memory-from-disk)
+  (initialize-actuators)
+  (initialize-all-skills)
+  
+  ;; Run proactive doctor before starting services
+  (diagnostics-startup-run)
+  
+  (heartbeat-start)
+  (start-daemon)
+
+  #+sbcl
+  (sb-sys:enable-interrupt sb-unix:sigint
+                            (lambda (sig code scp)
+                              (declare (ignore sig code scp))
+                              (harness-log "SHUTDOWN: SIGINT received. Saving memory...")
+                              (when *shutdown-save-enabled* (save-memory-to-disk))
+                              (uiop:quit 0)))
+
+  (let ((sleep-interval (or (ignore-errors (parse-integer (uiop:getenv "DAEMON_SLEEP_INTERVAL"))) 3600)))
+    (loop
+      (when (bt:with-lock-held (*loop-interrupt-lock*) *interrupt-flag*)
+        (harness-log "SHUTDOWN: Interrupt flag set. Saving memory...")
+        (when *shutdown-save-enabled* (save-memory-to-disk))
+        (return))
+      (sleep sleep-interval))))
+#+end_src
+
+* Test Suite
+Verifies that the immune system (error handling) correctly catches and reports errors from the cognitive pipeline.
+#+begin_src lisp :tangle ../lisp/core-loop.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-immune-system-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:immune-suite))
+
+(in-package :passepartout-immune-system-tests)
+
+(def-suite immune-suite :description "Verification of the Immune System (Core Error Hooks)")
+(in-suite immune-suite)
+
+(test loop-error-injection
+  "Verify that a crash in think/decide triggers a :loop-error stimulus."
+  (clrhash passepartout::*skills-registry*)
+  (passepartout:defskill :evil-skill
+    :priority 100
+    :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :user-input))
+    :probabilistic (lambda (ctx) (declare (ignore ctx)) (error "CRITICAL BRAIN FAILURE"))
+    :deterministic nil)
+  (passepartout:loop-process '(:type :EVENT :payload (:sensor :user-input)))
+  (let ((logs (passepartout:context-get-system-logs 20)))
+    (is (not (null (find-if (lambda (line) (search "CRITICAL BRAIN FAILURE" line)) logs))))))
+#+end_src

org/core-manifest.org

@@ -0,0 +1,72 @@
+#+TITLE: System Manifest (manifest.org)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:manifest:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../passepartout.asd
+
+* Overview: Architectural Intent
+
+The Manifest is the ASDF system definition for Passepartout. It defines what files belong to the harness, which external libraries are required, and how the test infrastructure is organized.
+
+The ~passepartout.asd~ file tangled from this manifest is what ~ql:quickload :passepartout~ reads to load the system. The files are loaded in the order listed here — dependencies first, then each pipeline stage in order.
+
+* Implementation
+
+** Main System
+
+The core system. The combined ~:depends-on~ list pulls in every external library the agent needs: networking (usocket, dexador, hunchentoot), concurrency (bordeaux-threads), utilities (uiop, cl-ppcre, cl-json, str), security (ironclad), and configuration (cl-dotenv, uuid).
+
+Components are loaded in sequence (~:serial t~): package first (defines the public API), then skills (does the defskill macro), then communication (defines the protocol), then memory (defines org-object), then context (defines peripheral vision), then each pipeline stage in order (perceive, reason, act), then doctor (diagnostics), then loop (orchestration).
+
+#+begin_src lisp
+(defsystem :passepartout
+  :name "Passepartout"
+  :author "Amr Gharbeia"
+  :version "0.3.0"
+  :license "AGPLv3"
+  :description "The Probabilistic-Deterministic Lisp Machine"
+  :depends-on (:usocket :bordeaux-threads :dexador :uiop :cl-dotenv :cl-ppcre :hunchentoot :ironclad :str :cl-json :uuid)
+  :serial t
+  :components ((:file "lisp/core-defpackage")
+               (:file "lisp/core-skills")
+               (:file "lisp/core-communication")
+               (:file "lisp/core-memory")
+               (:file "lisp/core-context")
+               (:file "lisp/core-loop-perceive")
+               (:file "lisp/core-loop-reason")
+               (:file "lisp/core-loop-act")
+               (:file "lisp/core-loop")))
+#+end_src
+
+** Test System
+
+The test system loads on top of ~opencortex~ and adds FiveAM (the test framework). Each test file is tangled from a ~:tangle ../tests/...~ block in the parent org file.
+
+Note: not every harness or skill file has a corresponding test file. Tests exist only for the parts of the system where deterministic verification is most critical — the pipeline stages, the loader, the memory Merkle tree, and the peripheral vision model.
+
+#+begin_src lisp
+(defsystem :passepartout/tests
+  :depends-on (:passepartout :fiveam)
+  :components ((:file "tests/pipeline-act-tests")
+               (:file "tests/boot-sequence-tests")
+               (:file "tests/communication-tests")
+               (:file "tests/immune-system-tests")
+               (:file "tests/memory-tests")
+               (:file "tests/pipeline-perceive-tests")
+               (:file "tests/pipeline-reason-tests")
+               (:file "tests/peripheral-vision-tests")
+               (:file "tests/tui-tests")
+               (:file "tests/utils-org-tests")
+               (:file "tests/utils-lisp-tests")
+               (:file "tests/llm-gateway-tests")))
+#+end_src
+
+** TUI System
+
+The TUI is a standalone system that depends on Croatoan (ncurses bindings) in addition to the core opencortex system. It's loaded separately because Croatoan requires a terminal and is not needed for daemon-mode operation.
+
+#+begin_src lisp
+(defsystem :passepartout/tui
+  :depends-on (:passepartout :croatoan :usocket :bordeaux-threads)
+  :components ((:file "lisp/gateway-tui")))
+#+end_src

org/core-memory.org

@@ -0,0 +1,340 @@
+#+TITLE: The System Memory (memory.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:memory:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-memory.lisp
+
+* Overview: Architectural Intent
+
+The Memory module is the cognitive bedrock of Passepartout. It is not a database; it is the agent's live, active brain state. Every perception, every action, every decision is recorded here.
+
+Traditional architectures rely on external databases (SQLite, vector DBs, JSON files) which introduce I/O latency, structural impedance, and serialization overhead. Passepartout chooses a different path: the **Single Address Space**. By treating the entire knowledge base as a graph of Lisp pointers in RAM, we achieve microsecond recollection and total structural transparency.
+
+The memory system has three layers:
+1. **Active memory** (~*memory-store*~) — a hash table mapping IDs to ~memory-object~ instances. This is what the agent queries during reasoning.
+2. **Immutable history** (~*memory-history*~) — an append-only hash table keyed by SHA-256 Merkle hash. Every version of every object that has ever existed is preserved here.
+3. **Snapshot stack** (~*memory-snapshots*~) — point-in-time copies of active memory for rollback recovery. Up to 20 snapshots are retained.
+
+** Why Merkle Hashes?
+
+Every ~memory-object~ carries a ~hash~ field computed from its ID, type, attributes, content, and children. This hash is deterministic: the same data always produces the same hash.
+
+The hash serves three purposes:
+1. **Integrity verification** — detect corruption or tampering
+2. **Deduplication** — if an object already exists in history, we reuse the existing entry
+3. **Change detection** — compare hashes to find what changed between snapshots
+
+** Why Snapshots Instead of Git?
+
+Git tracks changes to files. Passepartout tracks changes to live memory state. The snapshot system captures the entire active memory at a point in time, enabling full rollback to any previous state. This is necessary because:
+
+1. The agent modifies memory continuously (learning, noting, deciding) — there's no discrete "commit" boundary
+2. Memory corruption from a bad LLM output can affect multiple objects — snapshot rollback restores all of them atomically
+3. Git can't snapshot the running Lisp image's hash tables
+
+The tradeoff is memory usage: each snapshot is a deep copy of every object in active memory. 20 snapshots means 20x the active memory size. For a typical knowledge base of 10,000 objects, this is manageable (~100MB for 20 snapshots).
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** The Object Store
+
+~*memory-store*~ holds the agent's current state. ~*memory-history*~ holds every past version, keyed by Merkle hash.
+
+#+begin_src lisp
+(defvar *memory-store* (make-hash-table :test 'equal))
+(defvar *memory-history* (make-hash-table :test 'equal)
+  "Immutable Merkle-Tree versioning store mapping hashes to objects.")
+#+end_src
+
+** Object Lookup (memory-object-get)
+
+Retrieve a single object by its ID from active memory. Returns nil if the ID doesn't exist.
+
+#+begin_src lisp
+(defun memory-object-get (id)
+  "Retrieves an memory-object by ID from *memory-store*."
+  (gethash id *memory-store*))
+#+end_src
+
+** Object Search by Attribute (memory-objects-by-attribute)
+
+Scan the entire active memory for objects whose attributes plist contains a specific key-value pair. For example, finding all objects with ~:TODO "APPROVED"~ (used by the Bouncer to find approved flight plans).
+
+This is a full scan — O(n) over all objects. For the typical knowledge base size (< 10,000 objects), this is microsecond-fast. For larger datasets, a proper index would be needed.
+
+#+begin_src lisp
+(defun memory-objects-by-attribute (attr value)
+  "Returns all memory-objects whose :ATTRIBUTES plist has ATTR = VALUE."
+  (let ((results nil))
+    (maphash (lambda (id obj)
+               (declare (ignore id))
+               (when (equal (getf (memory-object-attributes obj) attr) value)
+                 (push obj results)))
+             *memory-store*)
+    (nreverse results)))
+#+end_src
+
+** ID Generation (memory-id-generate)
+
+Generates a unique identifier string for a new Org node. Uses the universal time encoded in base-36 for compactness and monotonic ordering (later IDs sort after earlier ones).
+
+#+begin_src lisp
+(defun memory-id-generate ()
+  "Generates a timestamp-based unique ID."
+  (format nil "id-~36r" (get-universal-time)))
+#+end_src
+
+** The Data Structure (memory-object)
+
+The universal data unit. Every stored entity — a note, a task, a project, a person, a decision — is an ~memory-object~. The struct has:
+
+- ~id~ — unique identifier (string)
+- ~type~ — keyword (e.g., ~:HEADLINE~, ~:PROPERTY_DRAWER~)
+- ~attributes~ — property list (e.g., ~(:TITLE "My Note" :TAGS ("project") :TODO "NEXT")~)
+- ~content~ — raw text content
+- ~vector~ — optional embedding vector for semantic search
+- ~parent-id~ — ID of the parent object (for tree structure)
+- ~children~ — list of child IDs
+- ~version~ — Unix timestamp of last modification
+- ~last-sync~ — Unix timestamp of last sync to disk
+- ~hash~ — SHA-256 Merkle hash for integrity verification
+
+#+begin_src lisp
+(defstruct memory-object
+  id type attributes content vector parent-id children version last-sync hash)
+#+end_src
+
+** Serialization Support
+
+Required by the Lisp runtime for saving/loading objects across image restarts via ~make-load-form-saving-slots~.
+
+#+begin_src lisp
+(defmethod make-load-form ((obj memory-object) &optional env)
+  (make-load-form-saving-slots obj :environment env))
+#+end_src
+
+** Deep Copy
+
+Creates an independent copy of an ~memory-object~, including fresh lists for attributes and children. Used by the snapshot system to capture a consistent memory state.
+
+Without deep copy, a snapshot would share structure with the live memory — mutating the live memory would also mutate the snapshot, defeating the purpose of having a recovery point.
+
+#+begin_src lisp
+(defun deep-copy-memory-object (obj)
+  "Creates a full copy of an memory-object, including fresh lists for attributes and children."
+  (make-memory-object :id (memory-object-id obj)
+                  :type (memory-object-type obj)
+                  :attributes (copy-list (memory-object-attributes obj))
+                  :content (memory-object-content obj)
+                  :vector (memory-object-vector obj)
+                  :parent-id (memory-object-parent-id obj)
+                  :children (copy-list (memory-object-children obj))
+                  :version (memory-object-version obj)
+                  :last-sync (memory-object-last-sync obj)
+                  :hash (memory-object-hash obj)))
+#+end_src
+
+** Merkle Tree Integrity (memory-merkle-hash)
+
+Computes a deterministic SHA-256 hash from an object's identity and contents. The hash covers:
+- The object's ID and type
+- All attributes (sorted by key name for determinism)
+- The raw content text
+- The hashes of all children (making the hash a true Merkle tree — changing a descendant changes this hash)
+
+This is NOT a cryptographic signature — it's an integrity check. If any part of an object or its descendants changes, the hash changes.
+
+#+begin_src lisp
+(defun memory-merkle-hash (id type attributes content child-hashes)
+  (let* ((alist (loop for (k v) on attributes by #'cddr collect (cons k v)))
+         (sorted-alist (sort alist #'string< :key (lambda (x) (format nil "~a" (car x)))))
+         (attr-string (format nil "~s" sorted-alist))
+         (children-string (format nil "~{~a~}" child-hashes))
+         (data-string (format nil "ID:~a|TYPE:~s|ATTRS:~a|CONTENT:~a|CHILDREN:~a"
+                               id type attr-string (or content "") children-string))
+         (digester (ironclad:make-digest :sha256)))
+    (ironclad:update-digest digester (ironclad:ascii-string-to-byte-array data-string))
+    (ironclad:byte-array-to-hex-string (ironclad:produce-digest digester))))
+#+end_src
+
+** AST Ingestion (memory-ingest)
+
+The primary entry point for adding data to memory. Given an Org-mode AST (a tree of plists representing headlines and their contents), it recursively:
+
+1. Generates or assigns an ID to each node
+2. Computes the Merkle hash of each node
+3. Checks if the hash already exists in ~*memory-history*~ (deduplication)
+4. Stores the node in ~*memory-store*~ and ~*memory-history*~
+5. Links children to parents
+
+Returns the ID of the root node.
+
+#+begin_src lisp
+(defun ingest-ast (ast &optional parent-id)
+  (let* ((type (getf ast :type))
+         (props (getf ast :properties))
+         (id (or (getf props :ID) (format nil "temp-~a" (get-universal-time))))
+         (contents (getf ast :contents))
+         (raw-content (when (eq type :HEADLINE)
+                        (format nil "~a~%~a" (getf props :TITLE) (or (getf ast :raw-content) ""))))
+         (child-ids nil) (child-hashes nil))
+    (dolist (child contents)
+      (when (listp child)
+        (let ((child-id (ingest-ast child id)))
+          (push child-id child-ids)
+          (let ((child-obj (gethash child-id *memory-store*)))
+            (when child-obj (push (memory-object-hash child-obj) child-hashes))))))
+    (setf child-ids (nreverse child-ids))
+    (setf child-hashes (nreverse child-hashes))
+    (let* ((hash (memory-merkle-hash id type props raw-content child-hashes))
+           (existing-obj (gethash hash *memory-history*))
+           (obj (or existing-obj
+                    (make-memory-object 
+                     :id id :type type :attributes props :content raw-content
+                     :parent-id parent-id :children child-ids
+                     :version (get-universal-time) :last-sync (get-universal-time)
+                     :hash hash))))
+      (unless existing-obj (setf (gethash hash *memory-history*) obj))
+      (setf (gethash id *memory-store*) obj)
+      id)))
+#+end_src
+
+** Snapshot History (~*memory-snapshots*~)
+
+A stack of CoW (copy-on-write) snapshots for rollback. When a critical error occurs, the system can roll back to any of the last 20 snapshots. Newer snapshots are prepended (index 0 = most recent).
+
+#+begin_src lisp
+(defvar *memory-snapshots* nil)
+#+end_src
+
+** Hash Table Copy Utility
+
+Creates a fully independent copy of a hash table. Used by the rollback system to restore saved memory state from a snapshot.
+
+#+begin_src lisp
+(defun memory-hash-table-copy (hash-table)
+  "Creates an independent copy of a hash table."
+  (let ((new-table (make-hash-table :test (hash-table-test hash-table) 
+                                     :size (hash-table-size hash-table))))
+    (maphash (lambda (k v) (setf (gethash k new-table) v)) hash-table)
+    new-table))
+#+end_src
+
+** Memory Snapshot (memory-snapshot)
+
+Captures a point-in-time copy of ~*memory-store*~. Each object is deep-copied so the snapshot is independent of ongoing mutations. The snapshot is prepended to the snapshot stack, and the stack is trimmed to 20 entries.
+
+Called automatically before significant memory mutations (buffer updates from Emacs, AST ingestion). Also callable manually.
+
+#+begin_src lisp
+(defun snapshot-memory ()
+  "Creates a CoW snapshot of *memory-store* for rollback recovery."
+  (let ((snapshot (make-hash-table :test 'equal :size (hash-table-size *memory-store*))))
+    (maphash (lambda (k v) (setf (gethash k snapshot) (deep-copy-memory-object v))) *memory-store*)
+    (push (list :timestamp (get-universal-time) :data snapshot) *memory-snapshots*)
+    (when (> (length *memory-snapshots*) 20)
+      (setf *memory-snapshots* (subseq *memory-snapshots* 0 20)))
+    (harness-log "MEMORY - CoW Memory snapshot created.")))
+#+end_src
+
+** Memory Rollback (memory-rollback)
+
+Restores ~*memory-store*~ to a previous snapshot. By default restores the most recent snapshot (index 0). Can specify a specific index to roll back further.
+
+This is the immune system's last resort. When the metabolic loop catches an unhandled error, it calls ~(rollback-memory 0)~ to undo any memory mutations caused by the bad signal.
+
+#+begin_src lisp
+(defun rollback-memory (&optional (index 0))
+  "Restores *memory-store* from a snapshot. INDEX 0 = most recent."
+  (let ((snapshot (nth index *memory-snapshots*)))
+    (if snapshot
+        (progn (setf *memory-store* (memory-hash-table-copy (getf snapshot :data)))
+               (harness-log "MEMORY - Memory rolled back to snapshot ~a" index))
+        (harness-log "MEMORY ERROR - Snapshot ~a not found." index))))
+#+end_src
+
+** Persistence — Snapshot Path (~*memory-snapshot-path*~)
+
+Configurable path for serialized memory state. Falls back to ~memory.snap~ in the home directory. Can be overridden via ~MEMORY_SNAPSHOT_PATH~ env var.
+
+#+begin_src lisp
+(defvar *memory-snapshot-path* nil)
+
+(defun memory-snapshot-path-ensure ()
+  "Returns the path to the memory snapshot file, resolving env or default."
+  (or *memory-snapshot-path*
+      (let ((env-path (uiop:getenv "MEMORY_SNAPSHOT_PATH")))
+        (setf *memory-snapshot-path*
+              (or env-path (namestring (uiop:merge-pathnames* "memory.snap" (user-homedir-pathname))))))))
+#+end_src
+
+** Save to Disk (memory-save)
+
+Serialises both ~*memory-store*~ and ~*memory-history*~ to a Lisp-readable file. The format is a plist with ~:memory~ and ~:history-store~ keys, each containing an alist of (key . object) pairs.
+
+The serialization uses ~prin1~, which produces human-readable Lisp output. The file can be read with ~read~ on restart.
+
+#+begin_src lisp
+(defun save-memory-to-disk ()
+  "Writes the entire memory and history store to disk as a plist."
+  (let ((path (memory-snapshot-path-ensure)))
+    (with-open-file (stream path :direction :output :if-exists :supersede :if-does-not-exist :create)
+      (let ((memory-alist nil) (history-alist nil))
+        (maphash (lambda (k v) (push (cons k v) memory-alist)) *memory-store*)
+        (maphash (lambda (k v) (push (cons k v) history-alist)) *memory-history*)
+        (prin1 (list :memory memory-alist :history-store history-alist) stream)))
+    (harness-log "MEMORY - Saved to ~a" path)))
+#+end_src
+
+** Load from Disk (memory-load)
+
+Restores memory state from a previously saved snapshot file. Called during boot (~main~ in ~loop.org~). If no snapshot file exists, the function returns silently and the agent starts with empty memory.
+
+#+begin_src lisp
+(defun load-memory-from-disk ()
+  "Reads memory state from disk and restores *memory-store* and *memory-history*."
+  (let ((path (memory-snapshot-path-ensure)))
+    (when (uiop:file-exists-p path)
+      (handler-case
+          (with-open-file (stream path :direction :input)
+            (let ((data (read stream nil)))
+              (when data
+                (let ((memory-alist (getf data :memory)) (history-alist (getf data :history-store)))
+                  (setf *memory-store* (make-hash-table :test 'equal :size (length memory-alist)))
+                  (dolist (kv memory-alist) (setf (gethash (car kv) *memory-store*) (cdr kv)))
+                  (setf *memory-history* (make-hash-table :test 'equal :size (length history-alist)))
+                  (dolist (kv history-alist) (setf (gethash (car kv) *memory-history*) (cdr kv)))
+                  (harness-log "MEMORY - Loaded from ~a (~a objects)" path (hash-table-size *memory-store*))))))
+          (error (c) (harness-log "MEMORY WARNING - Failed to load snapshot: ~a" c)))))
+  t)
+#+end_src
+
+* Test Suite
+Verifies that the Merkle hash is deterministic and consistent across independent AST ingestions.
+#+begin_src lisp :tangle ../lisp/core-memory.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-memory-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:memory-suite))
+
+(in-package :passepartout-memory-tests)
+
+(def-suite memory-suite :description "Tests for the Merkle-Tree Memory")
+(in-suite memory-suite)
+
+(test merkle-hash-consistency
+  (let* ((ast1 '(:type :HEADLINE :properties (:ID "test-1" :TITLE "Node 1") :contents nil)))
+    (clrhash passepartout::*memory-store*)
+    (let ((id1 (ingest-ast ast1)))
+      (let ((hash1 (memory-object-hash (memory-object-get id1))))
+        (clrhash passepartout::*memory-store*)
+        (let ((id2 (ingest-ast ast1)))
+          (is (equal hash1 (memory-object-hash (memory-object-get id2)))))))))
+#+end_src

org/core-skills.org

@@ -0,0 +1,440 @@
+#+TITLE: The Skill Engine (skills.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :org:skills:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle ../lisp/core-skills.lisp
+
+* Overview: Architectural Intent
+
+The Skill Engine is the dynamic loading and lifecycle manager for all Passepartout skills. It discovers skill files in the skills directory, resolves their dependency order, loads them into jailed packages, and exports their public symbols into the ~passepartout~ package.
+
+** Late-Binding Intelligence
+
+Hardcoding logic into a compiled binary creates a brittle kernel. Every time you add a capability, you must recompile, restart, and re-deploy. Skills solve this by being:
+
+1. **Discovered at boot** — the engine scans a directory for skill files and loads whatever it finds. No registration step needed.
+2. **Dependency-ordered** — skills declare dependencies via ~#+DEPENDS_ON:~ headers. The topological sort ensures they load in the right order.
+3. **Hot-reloadable** — a skill can be replaced at runtime without restarting the daemon. The new version is compiled into a fresh jail package and swapped in.
+4. **Self-documenting** — each skill is a single Org file containing prose, code, metadata, and tests. The "Why" and the "How" are unified.
+
+** The Jailed Package Model
+
+Every skill loads into its own package (e.g., ~PASSEPARTOUT.SKILLS.ORG-SKILL-BOUNCER~). This prevents name conflicts between skills — two skills can define a function called ~process~ without collision, because each lives in its own namespace.
+
+After loading, the engine exports the skill's public symbols into the ~passepartout~ package, making them available to other skills and the org. The export filter uses the skill's short name as a prefix — for example, the BOUNCER skill exports only symbols starting with ~BOUNCER-~.
+
+This is how the "thin org, fat skills" principle works in practice: the org provides the loading infrastructure; the skills provide all the intelligence.
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** Utility functions
+
+Helper functions used by the skill loader and other components.
+
+*** Cosine similarity
+
+Computes the cosine similarity between two numeric vectors. Used by the peripheral vision system for semantic relevance scoring — if the agent's current focus has a vector embedding, objects with similar embeddings get promoted to foveal detail.
+
+#+begin_src lisp
+(defun vector-cosine-similarity (v1 v2)
+  "Computes cosine similarity between two vectors."
+  (let* ((len1 (length v1)) (len2 (length v2)))
+    (if (or (zerop len1) (zerop len2))
+        0.0
+        (let* ((dot 0.0d0) (n1 0.0d0) (n2 0.0d0))
+          (dotimes (i (min len1 len2))
+            (let* ((x (coerce (elt v1 i) 'double-float)) (y (coerce (elt v2 i) 'double-float)))
+              (incf dot (* x y)) (incf n1 (* x x)) (incf n2 (* y y))))
+          (if (or (zerop n1) (zerop n2)) 0.0 (/ dot (sqrt (* n1 n2))))))))
+#+end_src
+
+*** Secret masking
+
+Simple mask function and the vault memory hash table. Used by the Bouncer skill and credentials vault to prevent secrets from appearing in logs.
+
+#+begin_src lisp
+(defun VAULT-MASK-STRING (s) (declare (ignore s)) "[MASKED]")
+(defvar *VAULT-MEMORY* (make-hash-table :test 'equal))
+#+end_src
+
+** Skill data structures
+
+The ~skill~ struct holds all metadata about a loaded skill: its name, priority, dependencies, trigger function, probabilistic prompt generator, deterministic gate, and system prompt augmentor. The ~skill-entry~ struct tracks the loading state of each discovered skill file.
+
+#+begin_src lisp
+(defstruct skill name priority dependencies trigger-fn probabilistic-prompt deterministic-fn system-prompt-augment)
+#+end_src
+
+#+begin_src lisp
+(defvar *skill-registry* (make-hash-table :test 'equal))
+#+end_src
+
+#+begin_src lisp
+(defvar *skill-catalog* (make-hash-table :test 'equal)
+  "Tracks all discovered skill files and their loading state.")
+#+end_src
+
+#+begin_src lisp
+(defstruct skill-entry filename (status :discovered) error-log (load-time 0))
+#+end_src
+
+** Skill discovery (skill-triggered-find)
+
+Iterates the registry and returns the highest-priority skill whose trigger function matches the current context. Only skills with a probabilistic prompt are considered (purely deterministic skills don't need LLM attention).
+
+This is how the system determines which skill "owns" the current user input. For example, if the REPL skill's trigger matches the input, the REPL skill provides the prompt template that shapes how the LLM responds.
+
+#+begin_src lisp
+(defun skill-triggered-find (context)
+  "Returns the highest priority skill whose trigger matches context."
+  (let ((triggered nil))
+    (maphash (lambda (name skill) 
+               (declare (ignore name)) 
+               (when (and (skill-probabilistic-prompt skill)
+                          (ignore-errors (funcall (skill-trigger-fn skill) context)))
+                 (push skill triggered))) 
+              *skill-registry*)
+    (first (sort triggered #'> :key #'skill-priority))))
+#+end_src
+
+** Skill registration macro (defskill)
+
+The primary API for skills. Each skill file calls this once to register itself. The macro creates a ~skill~ struct and stores it in ~*skill-registry*~ keyed by the skill's name.
+
+The ~:system-prompt-augment~ slot is optional. If provided, it's a function that receives the context and returns a string to append to the LLM's system prompt. This allows skills to inject domain-specific instructions into every reasoning cycle.
+
+#+begin_src lisp
+(defmacro defskill (name &key priority dependencies trigger probabilistic deterministic system-prompt-augment)
+  "Registers a new skill. NAME is a keyword. TRIGGER is a function (context) → bool."
+  `(setf (gethash (string-downcase (string ,name)) *skill-registry*)
+         (make-skill :name (string-downcase (string ,name)) 
+                    :priority (or ,priority 10) 
+                    :dependencies ',dependencies
+                    :trigger-fn ,trigger 
+                    :probabilistic-prompt ,probabilistic 
+                    :deterministic-fn ,deterministic
+                    :system-prompt-augment ,system-prompt-augment)))
+#+end_src
+
+** Dependency resolution (skill-dependencies-resolve)
+
+Recursively resolves all transitive dependencies for a given skill, returning an ordered list. Uses a standard graph traversal with a ~seen~ set to prevent infinite recursion from circular dependencies.
+
+#+begin_src lisp
+(defun skill-dependencies-resolve (skill-name)
+  "Resolves transitive dependencies. Returns list of skill names in dependency order."
+  (let ((resolved nil) (seen nil))
+    (labels ((visit (name) 
+               (unless (member name seen :test #'equal) 
+                 (push name seen)
+                 (let ((skill (gethash (string-downcase (string name)) *skill-registry*)))
+                   (when skill 
+                     (dolist (dep (skill-dependencies skill)) (visit dep))))
+                 (push name resolved))))
+      (visit skill-name) 
+      (nreverse resolved))))
+#+end_src
+
+** Skill File Analysis (skill-metadata-parse)
+
+Extracts the ~:ID~ and ~#+DEPENDS_ON:~ declarations from a skill's Org file. Used by the topological sorter to order skills correctly.
+
+#+begin_src lisp
+(defun skill-metadata-parse (filepath)
+  "Extracts ID and DEPENDS_ON tags from org file."
+  (let ((dependencies nil) (id nil) (content (uiop:read-file-string filepath)))
+    (let ((id-start (search ":ID:" content)))
+      (when id-start
+        (let ((id-end (position #\Newline content :start id-start)))
+          (when id-end (setf id (string-trim " " (subseq content (+ id-start 4) id-end)))))))
+    (let ((pos 0))
+      (loop while (setf pos (search "#+DEPENDS_ON:" content :start2 pos))
+            do (let ((end (position #\Newline content :start pos)))
+              (when end
+                (let ((line (string-trim " " (subseq content (+ pos 13) end))))
+                  (dolist (d (uiop:split-string line :separator '(#\Space #\Tab)))
+                    (unless (string= d "") (push d dependencies))))
+                (setf pos end)))))
+    (values id (reverse dependencies))))
+#+end_src
+
+** Dependency Resolution (skill-topological-sort)
+
+Returns a list of skill filepaths sorted by dependency order. Uses Kahn's algorithm: collect all files, build an adjacency graph from ~#+DEPENDS_ON:~ declarations, and topologically sort them. Skills with no dependencies are sorted alphabetically.
+
+Both ~.org~ and ~.lisp~ files are included. For each skill, the ~.org~ file supplies the dependency metadata; if a ~.lisp~ file exists, it's loaded instead of tangling from the ~.org~ at load time.
+
+#+begin_src lisp
+(defun skill-topological-sort (skills-dir)
+  "Returns a list of skill filepaths sorted by dependency."
+  (let* ((org-files (uiop:directory-files skills-dir "*.org"))
+         (lisp-files (uiop:directory-files skills-dir "*.lisp"))
+         (all-files (append org-files lisp-files))
+         (files (remove-if (lambda (f)
+                             (let ((n (pathname-name f)))
+                               (or (string= n "core-defpackage")
+                                   (string= n "core-skills")
+                                   (string= n "core-communication")
+                                   (string= n "core-memory")
+                                   (string= n "core-context")
+                                   (string= n "core-loop-perceive")
+                                   (string= n "core-loop-reason")
+                                   (string= n "core-loop-act")
+                                   (string= n "core-loop")
+                                   (string= n "core-manifest"))))
+                           all-files))
+        (adj (make-hash-table :test 'equal))
+        (name-to-file (make-hash-table :test 'equal))
+        (id-to-file (make-hash-table :test 'equal))
+        (result nil)
+        (visited (make-hash-table :test 'equal))
+        (stack (make-hash-table :test 'equal)))
+    (dolist (file files)
+      (let ((filename (pathname-name file)))
+        (if (uiop:string-suffix-p (namestring file) ".lisp")
+            (progn
+              (setf (gethash (string-downcase filename) name-to-file) file)
+              (unless (gethash (string-downcase filename) adj)
+                (setf (gethash (string-downcase filename) adj) nil)))
+            (multiple-value-bind (id deps) (skill-metadata-parse file)
+              (setf (gethash (string-downcase filename) name-to-file) file)
+              (when id (setf (gethash (string-downcase id) id-to-file) file))
+              (setf (gethash (string-downcase filename) adj) deps)))))
+    (labels ((visit (file)
+               (let* ((filename (pathname-name file))
+                      (node-key (string-downcase filename)))
+                 (unless (gethash node-key visited)
+                   (setf (gethash node-key stack) t)
+                   (dolist (dep (gethash node-key adj))
+                     (let* ((is-id-p (uiop:string-prefix-p "id:" (string-downcase dep)))
+                            (dep-key (string-downcase (if is-id-p (subseq dep 3) dep)))
+                            (dep-file (if is-id-p 
+                                          (gethash dep-key id-to-file)
+                                          (or (gethash dep-key id-to-file)
+                                              (gethash dep-key name-to-file)))))
+                       (when dep-file
+                         (let ((dep-filename (pathname-name dep-file)))
+                           (if (gethash (string-downcase dep-filename) stack)
+                               (error "Circular dependency detected")
+                               (visit dep-file))))))
+                   (setf (gethash node-key stack) nil)
+                   (setf (gethash node-key visited) t)
+                   (push file result)))))
+      (let ((filenames (sort (mapcar #'pathname-name files) #'string<)))
+        (dolist (name filenames)
+          (let ((file (gethash (string-downcase name) name-to-file)))
+            (when file (visit file)))))
+      (nreverse result))))
+#+end_src
+
+** Jailed Loading (skill-load-from-org)
+
+The primary skill loader. Given a path to an ~.org~ file:
+
+1. Reads the Org file and collects all ~#+begin_src lisp~ blocks (excluding test blocks and blocks with ~:tangle no~)
+2. Validates the Lisp syntax before loading
+3. Creates a jailed package named after the skill (e.g., ~PASSEPARTOUT.SKILLS.ORG-SKILL-BOUNCER~) with ~:use :passepartout~
+4. Evaluates the collected Lisp forms in that package
+5. Scans the package for symbols matching the skill's name prefix and exports them to the ~passepartout~ package
+
+The validation step is critical: invalid Lisp in an org block would crash the loader. The validator uses ~read~ with ~*read-eval*~ bound to nil to safely detect syntax errors without evaluating.
+
+#+begin_src lisp
+(defun lisp-syntax-validate (code-string)
+  "Checks if a string contains valid Common Lisp forms."
+  (handler-case
+      (let ((*read-eval* nil))
+        (with-input-from-string (s (format nil "(progn ~a)" code-string))
+          (loop for form = (read s nil :eof) until (eq form :eof)))
+        (values t nil))
+    (error (c) (values nil (format nil "~a" c)))))
+
+(defun skill-package-forms-strip (code-string)
+  "Removes in-package forms so symbols get defined in skill package."
+  (let ((lines (uiop:split-string code-string :separator '(#\Newline)))
+        (result ""))
+    (dolist (line lines)
+      (let ((trimmed (string-trim '(#\Space #\Tab) line)))
+        (unless (uiop:string-prefix-p "(in-package" trimmed)
+          (setf result (concatenate 'string result line (string #\Newline))))))
+    result))
+
+(defun tangle-target-extract (line)
+  "Extracts the value of the :tangle header."
+  (let ((pos (search ":tangle" line)))
+    (when pos
+      (let ((rest (string-tirm '(#\Space #\Tab) (subseq line (+ pos 7)))))
+        (let ((end (position #\Space rest)))
+          (if end (subseq rest 0 end) rest))))))
+
+(defun load-skill-from-org (filepath)
+  "Parses and evaluates Lisp blocks from an Org file."
+  (let* ((skill-base-name (pathname-name filepath))
+         (entry (or (gethash skill-base-name *skill-catalog*) (setf (gethash skill-base-name *skill-catalog*) (make-skill-entry :filename skill-base-name)))))
+    (setf (skill-entry-status entry) :loading)
+    (handler-case
+        (let* ((content (uiop:read-file-string filepath))
+               (lines (uiop:split-string content :separator '(#\Newline)))
+               (in-lisp-block nil) (collect-this-block nil) (lisp-code "")
+               (pkg-name (intern (string-upcase (format nil "PASSEPARTOUT.SKILLS.~a" skill-base-name)) :keyword)))
+          (dolist (line lines)
+            (let ((clean-line (string-trim '(#\Space #\Tab #\Return) line)))
+              (cond
+                ((uiop:string-prefix-p "#+begin_src lisp" clean-line)
+                 (setf in-lisp-block t)
+                 (let ((target (tangle-target-extract clean-line)))
+                   (setf collect-this-block (or (null target)
+                                                (and (not (search "no" target))
+                                                     (not (search "/tests" target)))))))
+                ((uiop:string-prefix-p "#+end_src" clean-line)
+                 (setf in-lisp-block nil) (setf collect-this-block nil))
+                ((and in-lisp-block collect-this-block)
+                 (unless (or (uiop:string-prefix-p ":PROPERTIES:" (string-upcase clean-line))
+                              (uiop:string-prefix-p ":END:" (string-upcase clean-line))
+                              (uiop:string-prefix-p ":ID:" (string-upcase clean-line)))
+                   (setf lisp-code (concatenate 'string lisp-code line (string #\Newline))))))))
+          (if (= (length lisp-code) 0)
+              (setf (skill-entry-status entry) :ready)
+              (progn
+                (multiple-value-bind (valid-p err) (lisp-syntax-validate lisp-code)
+                  (unless valid-p (error err)))
+                (unless (find-package pkg-name)
+                  (let ((new-pkg (make-package pkg-name :use '(:cl)))) (use-package :passepartout new-pkg)))
+                (let ((*read-eval* nil) (*package* (find-package pkg-name)))
+                  (log-message "LOADER: Evaluating code for '~a' in package ~a" skill-base-name (package-name *package*))
+                  (eval (read-from-string (format nil "(progn ~a)" lisp-code))))
+
+                (let* ((target-pkg (find-package :passepartout))
+                       (raw-name (string-upcase skill-base-name))
+                       (short-name (if (uiop:string-prefix-p "ORG-SKILL-" raw-name)
+                                       (subseq raw-name 10)
+                                       raw-name)))
+                  (log-message "LOADER: Scanning package ~a for symbols to export..." (package-name (find-package pkg-name)))
+                  (do-symbols (sym (find-package pkg-name))
+                    (when (eq (symbol-package sym) (find-package pkg-name))
+                      (let ((sn (symbol-name sym)))
+                        (when (or (uiop:string-prefix-p raw-name sn)
+                                  (uiop:string-prefix-p short-name sn)
+                                  (string-equal sn "DIAGNOSTICS-MAIN")
+                                  (string-equal sn "DIAGNOSTICS-RUN-ALL")
+                                  (string-equal sn "SETUP-WIZARD-RUN"))
+                          (log-message "LOADER: Exporting ~a to :PASSEPARTOUT" sn)
+                          (let ((existing (find-symbol sn target-pkg)))
+                            (when (and existing (not (eq existing sym)))
+                              (unintern existing target-pkg)))
+                          (import sym target-pkg)
+                          (export sym target-pkg))))))
+
+                (setf (skill-entry-status entry) :ready)))
+          t)
+      (error (c)
+        (log-message "LOADER ERROR in skill '~a': ~a" skill-base-name c)
+        (setf (skill-entry-status entry) :failed) nil))))
+#+end_src
+
+** Loading from Pre-Tangled Lisp (skill-load-from-lisp)
+
+Loads a pre-tangled ~.lisp~ file directly, without parsing the Org source. This is faster than ~load-skill-from-org~ because it skips the block extraction and syntax validation (the Lisp was already validated when tangled).
+
+The same jailed package and symbol export process applies.
+
+#+begin_src lisp
+(defun load-skill-from-lisp (filepath)
+  "Loads a .lisp skill file directly, filtering out in-package forms."
+  (let* ((skill-base-name (pathname-name filepath))
+         (entry (or (gethash skill-base-name *skill-catalog*) (setf (gethash skill-base-name *skill-catalog*) (make-skill-entry :filename skill-base-name)))))
+    (setf (skill-entry-status entry) :loading)
+    (handler-case
+        (let* ((content (skill-package-forms-strip (uiop:read-file-string filepath)))
+               (pkg-name (intern (string-upcase (format nil "PASSEPARTOUT.SKILLS.~a" skill-base-name)) :keyword)))
+          (multiple-value-bind (valid-p err) (lisp-syntax-validate content)
+            (unless valid-p (error err)))
+          (unless (find-package pkg-name)
+            (let ((new-pkg (make-package pkg-name :use '(:cl)))) (use-package :passepartout new-pkg)))
+          (let ((*read-eval* nil) (*package* (find-package pkg-name)))
+            (log-message "LOADER: Loading .lisp skill '~a' in package ~a" skill-base-name (package-name *package*))
+            (with-input-from-string (s content)
+              (loop for form = (read s nil :eof) until (eq form :eof)
+                    do (handler-case (eval form)
+                         (error (c) (log-message "LOADER WARNING in '~a': ~a" skill-base-name c))))))
+          (let* ((target-pkg (find-package :passepartout))
+                 (raw-name (string-upcase skill-base-name))
+                 (short-name (if (uiop:string-prefix-p "ORG-SKILL-" raw-name)
+                                 (subseq raw-name 10)
+                                 raw-name)))
+            (log-message "LOADER: Scanning package ~a for symbols to export..." (package-name (find-package pkg-name)))
+            (do-symbols (sym (find-package pkg-name))
+              (when (eq (symbol-package sym) (find-package pkg-name))
+                (let ((sn (symbol-name sym)))
+                  (when (or (uiop:string-prefix-p raw-name sn)
+                            (uiop:string-prefix-p short-name sn)
+                            (string-equal sn "DIAGNOSTICS-MAIN")
+                                  (string-equal sn "DIAGNOSTICS-RUN-ALL")
+                            (string-equal sn "SETUP-WIZARD-RUN"))
+                    (log-message "LOADER: Exporting ~a to :PASSEPARTOUT" sn)
+                    (let ((existing (find-symbol sn target-pkg)))
+                      (when (and existing (not (eq existing sym)))
+                        (unintern existing target-pkg)))
+                    (import sym target-pkg)
+                    (export sym target-pkg))))))
+          (setf (skill-entry-status entry) :ready))
+      (error (c)
+        (log-message "LOADER ERROR in skill '~a': ~a" skill-base-name c)
+        (setf (skill-entry-status entry) :failed) nil))))
+#+end_src
+
+** Initialize (skill-initialize-all)
+
+Boot-time entry point. Scans the skills directory, topologically sorts the files, and loads each one. Called from ~main~ in the metabolic loop and from the REPL for hot-reload.
+
+The skills directory is ~$OC_DATA_DIR/skills~ by default, which is populated by the ~configure~ script.
+
+#+begin_src lisp
+(defun skill-initialize-all ()
+  "Initializes all skills from the XDG skills directory."
+  (let* ((data-dir (uiop:ensure-directory-pathname (or (uiop:getenv "PASSEPARTOUT_DATA_DIR") (namestring (merge-pathnames ".local/share/passepartout/" (user-homedir-pathname))))))
+         (skills-dir (merge-pathnames "skills/" (uiop:ensure-directory-pathname data-dir))))
+    (unless (uiop:directory-exists-p skills-dir) (return-from skill-initialize-all nil))
+    (let ((sorted-files (skill-topological-sort skills-dir)))
+      (log-message "LOADER: Initializing ~a skills..." (length sorted-files))
+      (dolist (file sorted-files)
+        (if (uiop:string-suffix-p (namestring file) ".lisp")
+            (load-skill-from-lisp file)
+            (load-skill-from-org file)))
+      (log-message "LOADER: Boot Complete."))))
+#+end_src
+
+* Test Suite
+Verifies that the topological sorter correctly orders skills by their ~#+DEPENDS_ON:~ declarations.
+#+begin_src lisp :tangle ../tests/boot-sequence-tests.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-boot-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:boot-suite))
+
+(in-package :passepartout-boot-tests)
+
+(def-suite boot-suite :description "Verification of the Skill Engine loader")
+(in-suite boot-suite)
+
+(test test-topological-sort-basic
+  (let ((tmp-dir "/tmp/passepartout-boot-test/"))
+    (uiop:ensure-all-directories-exist (list tmp-dir))
+    (with-open-file (out (merge-pathnames "org-skill-a.org" tmp-dir) :direction :output :if-exists :supersede)
+      (format out "#+DEPENDS_ON: skill-b-id~%"))
+    (with-open-file (out (merge-pathnames "org-skill-b.org" tmp-dir) :direction :output :if-exists :supersede)
+      (format out ":PROPERTIES:~%:ID: skill-b-id~%:END:~%"))
+    (unwind-protect
+         (let ((sorted (passepartout::skill-topological-sort tmp-dir)))
+           (let ((pos-a (position "org-skill-a" sorted :key #'pathname-name :test #'string-equal))
+                 (pos-b (position "org-skill-b" sorted :key #'pathname-name :test #'string-equal)))
+             (is (< pos-b pos-a))))
+       (uiop:delete-directory-tree (uiop:ensure-directory-pathname tmp-dir) :validate t))))
+#+end_src

org/gateway-cli.org

@@ -0,0 +1,26 @@
+#+TITLE: SKILL: CLI Gateway (org-skill-cli-gateway.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:gateway:cli:
+#+PROPERTY: header-args:lisp :tangle ../lisp/gateway-cli.lisp
+
+* Overview
+The CLI Gateway is the simplest interface to Passepartout — raw stdin/stdout over TCP. It connects to the daemon's framed protocol and translates between terminal input/output and the plist-based communication format. No TUI, no ncurses, no dependencies beyond a TCP socket. Every other gateway (TUI, Emacs, Telegram) builds on this same protocol.
+
+* Implementation
+
+** CLI Command Handling
+#+begin_src lisp
+(defun gateway-cli-input (text)
+  "Processes raw text from the command line."
+  (inject-stimulus (list :type :EVENT 
+                         :payload (list :sensor :user-input :text text) 
+                         :meta (list :source :CLI))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-gateway-cli
+  :priority 100
+  :trigger (lambda (ctx) (eq (getf (getf ctx :meta) :source) :CLI))
+  :deterministic (lambda (action ctx) (declare (ignore ctx)) action))
+#+end_src

org/gateway-llm.org

@@ -0,0 +1,62 @@
+#+TITLE: SKILL: LLM Gateway (org-skill-llm-gateway.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:llm:gateway:
+#+PROPERTY: header-args:lisp :tangle ../lisp/gateway-llm.lisp
+
+* Overview
+The LLM Gateway dispatches inference requests to the registered probabilistic backends. It receives a prompt and system prompt, looks up the provider's registered function from ~*probabilistic-backends*~, calls it with the given model, and returns the result. This is the thin routing layer that sits between the reason pipeline and the provider-specific implementations in the unified-llm-backend skill.
+
+* Implementation
+
+** Request Execution (gateway-llm-request)
+#+begin_src lisp
+(defun gateway-llm-request (&key prompt system-prompt (provider :ollama) model)
+  "Central dispatcher for LLM requests."
+  (let ((backend (gethash provider *probabilistic-backends*)))
+    (if backend
+        (handler-case
+            (funcall backend prompt system-prompt :model model)
+          (error (c)
+            (list :status :error :message (format nil "~a Failure: ~a" provider c))))
+        (list :status :error :message (format nil "Provider ~a not registered" provider)))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-gateway-llm
+  :priority 100
+  :trigger (lambda (ctx) (getf ctx :user-input))
+  :deterministic (lambda (action ctx) (declare (ignore ctx)) action))
+#+end_src
+
+* Test Suite
+#+begin_src lisp :tangle ../lisp/gateway-llm.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-llm-gateway-tests
+  (:use :cl :passepartout)
+  (:export #:llm-gateway-suite))
+
+(in-package :passepartout-llm-gateway-tests)
+
+(fiveam:def-suite llm-gateway-suite :description "Tests for the LLM Gateway skill")
+(fiveam:in-suite llm-gateway-suite)
+
+(fiveam:test test-llm-gateway-timeout
+  "Tier 2 Chaos: Verify that LLM Gateway handles connection failures gracefully."
+  (let ((old-host (uiop:getenv "OLLAMA_HOST")))
+    (unwind-protect
+         (progn
+           (setf (uiop:getenv "OLLAMA_HOST") "localhost:1")
+           (let ((fn (or (find-symbol "EXECUTE-LLM-REQUEST" :passepartout.gateway-llm)
+                         (find-symbol "EXECUTE-LLM-REQUEST" :passepartout))))
+             (if fn
+                 (let ((result (funcall fn :prompt "hello" :provider :ollama)))
+                   (fiveam:is (eq (getf result :status) :error))
+                   (fiveam:is (uiop:string-prefix-p "Ollama Failure" (getf result :message))))
+                 (fiveam:fail "Could not find EXECUTE-LLM-REQUEST symbol"))))
+      (if old-host
+          (setf (uiop:getenv "OLLAMA_HOST") old-host)
+          (sb-posix:unsetenv "OLLAMA_HOST")))))
+#+end_src

org/gateway-manager.org

@@ -0,0 +1,298 @@
+#+TITLE: SKILL: Gateway Manager (org-skill-gateway-manager.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:gateway:manager:
+#+PROPERTY: header-args:lisp :tangle ../lisp/gateway-manager.lisp
+
+* Architectural Intent
+
+The Gateway Manager is the unified interface for all external messaging platforms. It handles Telegram, Signal, and any future gateway through a common pattern: a registry of poll/send function pairs, a configuration hash table for tokens and intervals, and a background thread per gateway that polls for new messages.
+
+Each gateway follows the same lifecycle:
+1. **Register** — the gateway's poll and send functions are registered in ~*gateway-registry*~
+2. **Link** — the user provides a token; it's stored in the vault and a polling thread is started
+3. **Poll** — the thread calls the poll function on an interval, injecting received messages into the pipeline
+4. **Unlink** — the thread is destroyed, the config is removed
+5. **Act** — when the agent needs to send a message, it dispatches to the gateway's send function via the generic actuator mechanism
+
+* Implementation
+
+** Platform state — configs
+Storage for active gateway connections: tokens, polling threads, and intervals.
+#+begin_src lisp
+(defvar *gateway-configs* (make-hash-table :test 'equal)
+  "Maps platform name → plist (:token :thread :interval :enabled)")
+#+end_src
+
+** Platform state — registry
+Registration of available gateway implementations: each platform registers its poll and send functions here.
+#+begin_src lisp
+(defvar *gateway-registry* (make-hash-table :test 'equal)
+  "Maps platform name → plist (:poll-fn :send-fn :default-interval)")
+#+end_src
+
+** Telegram Implementation
+#+begin_src lisp
+(defun telegram-get-token ()
+  (vault-get-secret :telegram))
+
+(defun telegram-poll ()
+  "Polls Telegram for new messages and injects them into the harness."
+  (let* ((token (telegram-get-token)))
+    (when token
+      (let* ((last-id (getf (gethash "telegram" *gateway-configs*) :last-update-id 0))
+             (url (format nil "https://api.telegram.org/bot~a/getUpdates?offset=~a"
+                          token (1+ last-id))))
+        (handler-case
+            (let* ((response (dex:get url))
+                   (json (cl-json:decode-json-from-string response))
+                   (updates (cdr (assoc :result json))))
+              (dolist (update updates)
+                (let* ((update-id (cdr (assoc :update--id update)))
+                       (message (cdr (assoc :message update)))
+                       (chat (cdr (assoc :chat message)))
+                       (chat-id (cdr (assoc :id chat)))
+                       (text (cdr (assoc :text message))))
+                  (setf (getf (gethash "telegram" *gateway-configs*) :last-update-id) update-id)
+                  (when (and text chat-id)
+                    (harness-log "TELEGRAM: Received message from ~a" chat-id)
+                    (inject-stimulus
+                     (list :type :EVENT
+                           :meta (list :source :telegram :chat-id (format nil "~a" chat-id))
+                           :payload (list :sensor :user-input :text text)))))))
+          (error (c) (harness-log "TELEGRAM POLL ERROR: ~a" c))))))
+
+(defun telegram-send (action context)
+  "Sends a message via Telegram."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (meta (getf action :meta))
+         (chat-id (or (getf meta :chat-id) (getf payload :chat-id) (getf action :chat-id)))
+         (text (or (getf payload :text) (getf action :text)))
+         (token (telegram-get-token)))
+    (when (and token chat-id text)
+      (harness-log "TELEGRAM: Sending message to ~a..." chat-id)
+      (handler-case
+          (let ((url (format nil "https://api.telegram.org/bot~a/sendMessage" token)))
+            (dex:post url
+                      :headers '(("Content-Type" . "application/json"))
+                      :content (cl-json:encode-json-to-string
+                                `((chat_id . ,chat-id) (text . ,text)))))
+        (error (c) (harness-log "TELEGRAM ERROR: ~a" c))))))
+#+end_src
+
+** Signal Implementation
+#+begin_src lisp
+(defun signal-get-account ()
+  (vault-get-secret :signal))
+
+(defun signal-poll ()
+  "Polls Signal for new messages and injects them into the harness."
+  (let ((account (signal-get-account)))
+    (when account
+      (handler-case
+          (let* ((output (uiop:run-program (list "signal-cli" "-u" account "receive" "--json")
+                                            :output :string :error-output :string :ignore-error-status t))
+                 (lines (cl-ppcre:split "\\n" output)))
+            (dolist (line lines)
+              (when (and line (> (length line) 0))
+                (let* ((json (ignore-errors (cl-json:decode-json-from-string line)))
+                       (envelope (cdr (assoc :envelope json)))
+                       (source (cdr (assoc :source envelope)))
+                       (data-message (cdr (assoc :data-message envelope)))
+                       (text (cdr (assoc :message data-message))))
+                  (when (and source text)
+                    (harness-log "SIGNAL: Received message from ~a" source)
+                    (inject-stimulus
+                     (list :type :EVENT
+                           :meta (list :source :signal :chat-id source)
+                           :payload (list :sensor :user-input :text text))))))))
+        (error (c) (harness-log "SIGNAL POLL ERROR: ~a" c))))))
+
+(defun signal-send (action context)
+  "Sends a message via Signal."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (meta (getf action :meta))
+         (chat-id (or (getf meta :chat-id) (getf payload :chat-id) (getf action :chat-id)))
+         (text (or (getf payload :text) (getf action :text)))
+         (account (signal-get-account)))
+    (when (and account chat-id text)
+      (harness-log "SIGNAL: Sending message to ~a..." chat-id)
+      (handler-case
+          (uiop:run-program (list "signal-cli" "-u" account "send" "-m" text chat-id)
+                            :output :string :error-output :string)
+        (error (c) (harness-log "SIGNAL ERROR: ~a" c))))))
+#+end_src
+
+** Gateway Registry Initialization
+#+begin_src lisp
+(defun gateway-registry-initialize ()
+  "Registers all built-in gateway handlers."
+  (setf (gethash "telegram" *gateway-registry*)
+        (list :poll-fn #'telegram-poll
+              :send-fn #'telegram-send
+              :default-interval 3))
+  (setf (gethash "signal" *gateway-registry*)
+        (list :poll-fn #'signal-poll
+              :send-fn #'signal-send
+              :default-interval 5)))
+#+end_src
+
+** Core gateway functions
+
+*** Configuration check (gateway-configured-p)
+Returns T if a platform has a stored token in ~*gateway-configs*~.
+#+begin_src lisp
+(defun gateway-configured-p (platform)
+  "Returns T if a platform has a stored token."
+  (let ((config (gethash platform *gateway-configs*)))
+    (and config (getf config :token))))
+#+end_src
+
+*** Active check (gateway-active-p)
+Returns T if a platform's polling thread is alive.
+#+begin_src lisp
+(defun gateway-active-p (platform)
+  "Returns T if a platform's polling thread is alive."
+  (let ((config (gethash platform *gateway-configs*)))
+    (and config
+         (getf config :thread)
+         (bt:thread-alive-p (getf config :thread)))))
+#+end_src
+
+*** Link a gateway (gateway-link)
+The main entry point for linking. Validates the registry entry, stores the token in the vault, starts the polling thread, and updates the config.
+#+begin_src lisp
+(defun gateway-link (platform token)
+  "Links a platform with a token and starts polling."
+  (let ((platform-lc (string-downcase platform)))
+    (unless (gethash platform-lc *gateway-registry*)
+      (error "Unknown platform: ~a. Available: ~{~a~^, ~}"
+             platform (loop for k being the hash-keys of *gateway-registry* collect k)))
+    (when (or (null token) (zerop (length token)))
+      (error "Token cannot be empty"))
+    (harness-log "GATEWAY: Linking to ~a..." platform-lc)
+    (gateway-unlink platform-lc)
+    (let* ((registry-entry (gethash platform-lc *gateway-registry*))
+           (interval (or (getf registry-entry :default-interval) 5)))
+      (setf (gethash platform-lc *gateway-configs*)
+            (list :token token :interval interval :enabled t))
+      (vault-set-secret (intern (string-upcase platform-lc) :keyword) token)
+      (gateway-start platform-lc)
+      (harness-log "GATEWAY: Successfully linked ~a" platform-lc)
+      (format t "Successfully linked ~a gateway. Token stored securely.~%" platform-lc)
+      t)))
+#+end_src
+
+*** Unlink a gateway (gateway-unlink)
+Stops the polling thread and removes the config entry.
+#+begin_src lisp
+(defun gateway-unlink (platform)
+  "Unlinks a platform and stops its polling thread."
+  (let ((platform-lc (string-downcase platform)))
+    (gateway-stop platform-lc)
+    (remhash platform-lc *gateway-configs*)
+    (harness-log "GATEWAY: Unlinked ~a" platform-lc)
+    (format t "Successfully unlinked ~a gateway.~%" platform-lc)
+    t))
+#+end_src
+
+*** Start polling (gateway-start)
+Creates a background thread that calls the platform's poll function on an interval. The thread checks the ~:enabled~ flag on each cycle so it can be stopped cleanly via ~gateway-stop~.
+#+begin_src lisp
+(defun gateway-start (platform)
+  "Starts the polling thread for a linked gateway."
+  (let ((platform-lc (string-downcase platform)))
+    (let ((config (gethash platform-lc *gateway-configs*)))
+      (when (and config (getf config :enabled) (not (gateway-active-p platform-lc)))
+        (let ((poll-fn (getf (gethash platform-lc *gateway-registry*) :poll-fn)))
+          (when poll-fn
+            (let ((interval (getf config :interval)))
+              (setf (getf config :thread)
+                    (bt:make-thread
+                     (lambda ()
+                       (loop
+                         (when (getf (gethash platform-lc *gateway-configs*) :enabled)
+                           (funcall poll-fn))
+                         (sleep interval)))
+                     :name (format nil "passepartout-~a-gateway" platform-lc)))
+              (harness-log "GATEWAY: Started ~a polling (interval: ~as)" platform-lc interval)))))))))
+#+end_src
+
+*** Stop polling (gateway-stop)
+Destroys the polling thread and nulls the thread reference.
+#+begin_src lisp
+(defun gateway-stop (platform)
+  "Stops the polling thread for a gateway."
+  (let ((platform-lc (string-downcase platform)))
+    (let ((config (gethash platform-lc *gateway-configs*)))
+      (when (and config (getf config :thread))
+        (when (bt:thread-alive-p (getf config :thread))
+          (harness-log "GATEWAY: Stopping ~a polling thread" platform-lc)
+          (bt:destroy-thread (getf config :thread))))
+      (setf (getf config :thread) nil))))
+#+end_src
+
+*** List gateways (gateway-list)
+Returns a list of plists, one per registered platform, with :platform, :configured, and :active keys.
+#+begin_src lisp
+(defun gateway-list ()
+  "Returns a list of all gateways with their status."
+  (loop for platform being the hash-keys of *gateway-registry*
+        collect (let ((configured (gateway-configured-p platform))
+                      (active (gateway-active-p platform)))
+                  (list :platform platform
+                        :configured configured
+                        :active active))))
+#+end_src
+
+*** Print gateways (gateway-list-print)
+Formats ~gateway-list~ for display in the CLI.
+#+begin_src lisp
+(defun gateway-list-print ()
+  "Prints a formatted table of gateways."
+  (format t "~%")
+  (format t "  ~20@A ~12@A ~10@A~%" "PLATFORM" "CONFIGURED" "STATUS")
+  (dolist (gw (gateway-list))
+    (format t "  ~20@A ~12@A ~10@A~%"
+            (getf gw :platform)
+            (if (getf gw :configured) "yes" "no")
+            (cond
+              ((getf gw :active) "ACTIVE")
+              ((getf gw :configured) "stopped")
+              (t "not linked"))))
+  (format t "~%"))
+#+end_src
+
+*** Start all configured gateways (gateway-start-all)
+Called during boot to start all gateways that have tokens stored in their configs.
+#+begin_src lisp
+(defun gateway-start-all ()
+  "Called at boot to start all configured gateways."
+  (dolist (config (loop for platform being the hash-keys of *gateway-configs*
+                       collect (list platform (gethash platform *gateway-configs*))))
+    (destructuring-bind (platform config) config
+      (when (and (getf config :enabled) (not (gateway-active-p platform)))
+        (gateway-start platform)))))
+#+end_src
+
+** Actuator Registration
+Register :telegram and :signal as actuators for outbound messages.
+#+begin_src lisp
+(register-actuator :telegram #'telegram-send)
+(register-actuator :signal #'signal-send)
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-gateway-manager
+  :priority 150
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src
+
+** Initialization
+Initialize registry and start configured gateways on skill load.
+#+begin_src lisp
+(gateway-registry-initialize)
+(gateway-start-all)
+#+end_src

org/gateway-provider.org

@@ -0,0 +1,120 @@
+#+TITLE: SKILL: Unified LLM Backend (org-skill-unified-llm-backend.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:llm:backend:openai-compatible:
+#+PROPERTY: header-args:lisp :tangle ../lisp/gateway-provider.lisp
+
+* Architectural Intent
+
+The Unified LLM Backend provides a single OpenAI-compatible API client that works with any provider supporting the ~/v1/chat/completions~ endpoint. This covers local engines (Ollama, vLLM, LM Studio, llama.cpp) and cloud providers (OpenRouter, OpenAI, Anthropic, Groq, Gemini, DeepSeek, NVIDIA NIM).
+
+The key design decision: **one client, many configurations**. Instead of having separate skills for each provider (org-skill-ollama, org-skill-openai, etc.), this single skill holds a configuration table mapping provider keywords to their base URL, API key env var, and default model. The same ~provider-openai-request~ function works for all of them.
+
+Providers are registered automatically at boot based on which API keys are set in the environment. If OPENAI_API_KEY is set, OpenAI is available. If not, it's skipped silently.
+
+Providers are registered automatically based on available environment variables.
+No separate skills per provider — just different base URLs and API keys.
+
+* Implementation
+
+** Provider registry (~*provider-configs*~)
+The authoritative list of supported LLM providers and their configuration: base URL, env var for API key, and default model name.
+#+begin_src lisp
+(defparameter *provider-configs*
+  '((:ollama     . (:base-url nil          :key-env nil           :default-model "llama3"))
+    (:openrouter . (:base-url "https://openrouter.ai/api/v1" :key-env "OPENROUTER_API_KEY" :default-model "openrouter/auto"))
+    (:openai     . (:base-url "https://api.openai.com/v1"    :key-env "OPENAI_API_KEY"     :default-model "gpt-4o-mini"))
+    (:anthropic  . (:base-url "https://api.anthropic.com/v1" :key-env "ANTHROPIC_API_KEY"  :default-model "claude-3-5-sonnet-20241022"))
+    (:groq       . (:base-url "https://api.groq.com/openai/v1" :key-env "GROQ_API_KEY"     :default-model "llama-3.1-70b-versatile"))
+    (:gemini     . (:base-url "https://generativelanguage.googleapis.com/v1beta/openai" :key-env "GEMINI_API_KEY" :default-model "gemini-2.0-flash"))
+    (:deepseek   . (:base-url "https://api.deepseek.com/v1"  :key-env "DEEPSEEK_API_KEY"  :default-model "deepseek-chat"))
+    (:nvidia     . (:base-url "https://integrate.api.nvidia.com/v1" :key-env "NVIDIA_API_KEY" :default-model "meta/llama-3.1-405b-instruct"))))
+#+end_src
+
+** Provider config lookup (provider-config)
+Returns the config plist for a given provider keyword.
+#+begin_src lisp
+(defun provider-config (provider)
+  "Returns the configuration plist for a provider keyword."
+  (cdr (assoc provider *provider-configs*)))
+#+end_src
+
+** Availability check (provider-available-p)
+Returns T if a provider is configured — meaning it either has an API key set, or it is Ollama (always available locally).
+#+begin_src lisp
+(defun provider-available-p (provider)
+  "Checks if a provider is configured. Ollama is always considered available."
+  (let* ((config (provider-config provider))
+         (key-env (getf config :key-env))
+         (base-url (getf config :base-url)))
+    (cond ((eq provider :ollama) t)
+          (key-env (let ((key (uiop:getenv key-env))) (and key (> (length key) 0))))
+          (base-url t))))
+#+end_src
+
+** Unified Request Execution
+#+begin_src lisp
+(defun provider-openai-request (prompt system-prompt &key model (provider :ollama))
+  "Executes a request against any OpenAI-compatible API endpoint."
+  (let* ((config (provider-config provider))
+         (base-url (getf config :base-url))
+         (key-env (getf config :key-env))
+         (default-model (getf config :default-model))
+         (api-key (when key-env (uiop:getenv key-env)))
+         (model-id (or model default-model))
+         (url (if (eq provider :ollama)
+                  (format nil "http://~a/v1/chat/completions" (or (uiop:getenv "OLLAMA_HOST") "localhost:11434"))
+                  (format nil "~a/chat/completions" base-url)))
+         (headers `(("Content-Type" . "application/json")
+                    ,@(when api-key `(("Authorization" . ,(format nil "Bearer ~a" api-key))))
+                    ,@(when (eq provider :openrouter)
+                        `(("HTTP-Referer" . "https://github.com/amrgharbeia/passepartout")
+                          ("X-Title" . "Passepartout")))))
+         (body (cl-json:encode-json-to-string
+                `((model . ,model-id)
+                  (messages . (( (role . "system") (content . ,system-prompt) )
+                               ( (role . "user") (content . ,prompt) )))))))
+    (handler-case
+        (let* ((response (dex:post url :headers headers :content body :connect-timeout 10 :read-timeout 60))
+               (json (cl-json:decode-json-from-string response))
+               (choices (cdr (assoc :choices json)))
+               (first-choice (car choices))
+               (message (cdr (assoc :message first-choice)))
+               (content (cdr (assoc :content message))))
+          (if content
+              (list :status :success :content content)
+              (list :status :error :message (format nil "~a: No content in response (~s)" provider json))))
+      (error (c)
+        (list :status :error :message (format nil "~a Failure: ~a" provider c))))))
+#+end_src
+
+** Dynamic Backend Registration
+#+begin_src lisp
+(defun provider-register-all ()
+  "Scans environment variables and registers all available LLM backends."
+  (dolist (entry *provider-configs*)
+    (let ((provider (car entry)))
+      (when (provider-available-p provider)
+        (log-message "LLM BACKEND: Registering provider ~a" provider)
+        (register-probabilistic-backend provider
+          (lambda (prompt system-prompt &key model)
+            (provider-openai-request prompt system-prompt :model model :provider provider)))))))
+
+(defun provider-cascade-initialize ()
+  "Reads PROVIDER_CASCADE from env and sets *provider-cascade*."
+  (let ((cascade-str (uiop:getenv "PROVIDER_CASCADE")))
+    (if cascade-str
+        (setf *provider-cascade*
+              (mapcar (lambda (s) (intern (string-upcase (string-trim '(#\Space) s)) :keyword))
+                      (uiop:split-string cascade-str :separator '(#\,))))
+        (setf *provider-cascade* (mapcar #'car *provider-configs*)))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(provider-register-all)
+(provider-cascade-initialize)
+
+(defskill :passepartout-gateway-provider
+  :priority 50
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src

org/gateway-tui.org

@@ -0,0 +1,321 @@
+#+TITLE: Passepartout TUI Client (Standalone)
+#+STARTUP: content
+#+FILETAGS: :tui:ux:client:
+#+PROPERTY: header-args:lisp :tangle ../lisp/gateway-tui.lisp
+
+* Overview: Architectural Intent
+
+The TUI Client is a standalone ncurses application built on Croatoan that connects to the daemon via TCP. It provides a split-pane interface: a scrollable chat history window at the top and a fixed input line at the bottom.
+
+Unlike the CLI gateway (which is a single request-response cycle), the TUI is a persistent connection. It maintains a background reader thread that listens for incoming messages from the daemon and enqueues them for display. This allows the agent to send messages to the user asynchronously — tool results, heartbeat notifications, and autonomous decisions appear in the chat window without the user having to ask.
+
+** Why a Background Reader Thread?
+
+The daemon's protocol is framed TCP — the TUI sends a message, the daemon processes it, and sends one or more responses. But the daemon can also send unsolicited messages (heartbeat notifications, tool results from autonomous actions). The background reader thread handles this by continuously reading from the socket and enqueuing messages for the main loop to display.
+
+The main loop is event-driven: on each tick, it checks for new messages in the queue, checks for keyboard input, renders updates, and sleeps for ~10ms. This gives responsive text input (no perceived latency) while keeping CPU usage near zero.
+
+* Implementation
+
+** Package Context
+
+The TUI lives in its own package (~passepartout.gateway-tui~) so it doesn't pollute the harness namespace. It depends on Croatoan (ncurses bindings), usocket (TCP client), and bordeaux-threads (background reader).
+
+#+begin_src lisp
+(in-package :cl-user)
+(defpackage :passepartout.gateway-tui
+  (:use :cl :croatoan :usocket :bordeaux-threads)
+  (:export :main))
+(in-package :passepartout.gateway-tui)
+#+end_src
+
+** Connection state
+
+The daemon host and port. Defaults to localhost:9105. These can be changed before calling ~main~.
+
+#+begin_src lisp
+(defvar *daemon-host* "localhost")
+#+end_src
+
+#+begin_src lisp
+(defvar *daemon-port* 9105)
+#+end_src
+
+** Socket and stream
+
+The TCP socket and stream used to communicate with the daemon. Set during ~main~ and used by ~input-submit~ and ~reader-start~.
+
+#+begin_src lisp
+(defvar *socket* nil)
+#+end_src
+
+#+begin_src lisp
+(defvar *stream* nil)
+#+end_src
+
+** Chat history
+
+The list of messages displayed in the chat window. Each message is a string prepended with ~⬆~ (outgoing) or ~⬇~ (incoming).
+
+#+begin_src lisp
+(defvar *chat-history* nil)
+#+end_src
+
+** Input buffer
+
+The current line the user is typing. Characters are pushed onto this list and reversed before submission.
+
+#+begin_src lisp
+(defvar *input-buffer* nil)
+#+end_src
+
+** Running flag
+
+Set to nil to signal the main loop to exit. Set by ~/exit~ command, connection errors, or ~unwind-protect~ cleanup.
+
+#+begin_src lisp
+(defvar *is-running* t)
+#+end_src
+
+** Incoming message queue
+
+Thread-safe queue for messages received by the background reader. Lock ensures the main loop and reader thread don't race on the list.
+
+#+begin_src lisp
+(defvar *queue-lock* (bt:make-lock "incoming-queue-lock"))
+#+end_src
+
+#+begin_src lisp
+(defvar *incoming* nil)
+#+end_src
+
+** Utility functions
+
+*** Debug logging
+
+Writes debugging information to ~/tmp/passepartout-tui-debug.log~. Useful for diagnosing connection issues and message parsing problems.
+
+#+begin_src lisp
+(defun log-debug (msg &rest args)
+  (ignore-errors
+    (with-open-file (s "/tmp/passepartout-tui-debug.log" :direction :output :if-exists :append :if-does-not-exist :create)
+      (format s "[~a] " (get-universal-time))
+      (apply #'format s msg args)
+      (terpri s)
+      (finish-output s))))
+#+end_src
+
+*** Message queue (message-queue-push)
+
+Adds a message to the incoming queue. Thread-safe via ~*queue-lock*~.
+
+#+begin_src lisp
+(defun message-queue-push (msg)
+  (bt:with-lock-held (*queue-lock*)
+    (setf *incoming* (append *incoming* (list msg)))))
+#+end_src
+
+*** Message queue (message-queue-drain)
+
+Drains the incoming queue, returning all messages since the last drain. Thread-safe via ~*queue-lock*~.
+
+#+begin_src lisp
+(defun message-queue-drain ()
+  (bt:with-lock-held (*queue-lock*)
+    (let ((msgs *incoming*))
+      (setf *incoming* nil)
+      msgs)))
+#+end_src
+
+** Rendering (chat-render)
+
+Renders the chat history window. Draws a bordered box with scrollable content — only the most recent ~h-2~ messages are visible, matching the window height.
+
+The box border uses Unicode box-drawing characters via Croatoan's ~box~ function.
+
+#+begin_src lisp
+(defun chat-render (win h)
+  (when (and win (integerp h))
+    (clear win)
+    (box win 0 0)
+    (let* ((view-height (- h 2))
+           (history (copy-list *chat-history*))
+           (len (length history))
+           (num-to-draw (min len view-height))
+           (slice (subseq history 0 num-to-draw)))
+      (loop for i from 0 below num-to-draw
+            for msg in (reverse slice)
+            do (when msg
+                 (add-string win (format nil "│ ~a" msg) :y (1+ i) :x 2))))
+    (refresh win)))
+#+end_src
+
+** Input handling
+
+*** Handle backspace
+
+Removes the last character from the input buffer.
+
+#+begin_src lisp
+(defun input-backspace ()
+  (pop *input-buffer*))
+#+end_src
+
+*** Handle return
+
+Sends the accumulated input as a framed protocol message to the daemon. The message format is:
+
+  (:TYPE :EVENT :META (:SOURCE :tui) :PAYLOAD (:SENSOR :user-input :TEXT "<user input>"))
+
+Also handles the ~/exit~ and ~/clear~ client-side commands before sending to the daemon.
+
+#+begin_src lisp
+(defun input-submit (stream)
+  (let ((cmd (coerce (reverse *input-buffer*) 'string)))
+    (setf *input-buffer* nil)
+    (log-debug "SUBMITTING: '~a'" cmd)
+    (when (> (length cmd) 0)
+      (push (format nil "⬆ ~a" cmd) *chat-history*)
+      (handler-case
+          (progn
+            (if (and stream (open-stream-p stream))
+                (let* ((msg (list :TYPE :EVENT 
+                                 :META (list :SOURCE :tui)
+                                 :PAYLOAD (list :SENSOR :user-input :TEXT cmd)))
+                       (payload (format nil "~s" msg))
+                       (len (length payload)))
+                  (format stream "~6,'0x~a" len payload)
+                  (finish-output stream)
+                  (log-debug "SENT WIRE: ~a" payload))
+                (push "ERROR: Not connected." *chat-history*)))
+        (error (c)
+          (log-debug "SEND ERROR: ~a" c)
+          (push (format nil "ERROR: ~a" c) *chat-history*)
+          (setf *is-running* nil))))
+    (when (string= cmd "/exit") (setf *is-running* nil))
+    (when (string= cmd "/clear") (setf *chat-history* nil))))
+#+end_src
+
+** Background Reader (reader-start)
+
+A dedicated thread that continuously reads framed messages from the daemon's TCP stream. Messages are parsed and enqueued for the main loop to display.
+
+The reader handles:
+- The ~:handshake~ action (sent on connection) — displays "* Connected *"
+- All other actions — displays the ~:text~ payload or the raw payload
+
+If the connection is lost or an error occurs, the reader logs the error, enqueues a "Connection lost" message, and sets ~*is-running*~ to nil to stop the main loop.
+
+#+begin_src lisp
+(defun reader-start (stream)
+  (bt:make-thread
+   (lambda ()
+     (loop while *is-running* do
+       (handler-case
+           (let* ((len-buf (make-string 6))
+                  (count (read-sequence len-buf stream)))
+             (if (= count 6)
+                 (let* ((msg-len (parse-integer len-buf :radix 16))
+                        (msg-buf (make-string msg-len)))
+                   (read-sequence msg-buf stream)
+                   (log-debug "DAEMON MSG: ~a" msg-buf)
+                   (let ((msg (read-from-string msg-buf)))
+                     (let ((payload (getf msg :payload)))
+                       (cond
+                         ((eq (getf payload :action) :handshake)
+                          (message-queue-push "* Connected *"))
+                         (t
+                          (let ((text (or (getf payload :text) (format nil "~a" payload))))
+                            (message-queue-push (format nil "⬇ ~a" text))))))))
+                 (sleep 0.05)))
+         (error (c)
+           (when *is-running*
+             (log-debug "READER ERROR: ~a" c)
+             (message-queue-push "ERROR: Connection lost.")
+             (setf *is-running* nil))))))
+   :name "passepartout-tui-reader"))
+#+end_src
+
+** Main Entry Point (main)
+
+The top-level entry point for the TUI application. Boot sequence:
+
+1. Connect to the daemon at ~localhost:9105~
+2. If connection fails, print an error and exit immediately
+3. Create the ncurses screen with two windows (chat + input)
+4. Start the background reader thread
+5. Enter the main loop: check for messages, check for keyboard input, render
+6. On ~unwind-protect~ cleanup: close the socket
+
+The main loop runs at ~100Hz (10ms sleep). Keyboard input is non-blocking — if no key is pressed, the loop still runs to check for incoming messages from the daemon.
+
+#+begin_src lisp
+(defun main ()
+  (log-debug "=== START ===")
+  (handler-case
+      (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
+    (error (e) (format t "Offline: ~a~%" e) (return-from main)))
+  (setf *stream* (usocket:socket-stream *socket*))
+  
+  (unwind-protect
+      (with-screen (scr :input-echoing nil :input-blocking nil :enable-colors t)
+        (let* ((h (or (height scr) 24))
+               (w (or (width scr) 80))
+               (chat-h (- h 4))
+               (chat-win (make-instance 'window :height chat-h :width (- w 2) :y 1 :x 1))
+               (input-win (make-instance 'window :height 1 :width (- w 2) :y (- h 2) :x 1)))
+          (setf (input-blocking input-win) nil)
+          (reader-start *stream*)
+          (loop :while *is-running* :do
+            (let ((msgs (message-queue-drain)))
+              (when msgs 
+                (dolist (m msgs) (push m *chat-history*))
+                (chat-render chat-win chat-h)))
+            (let ((ch (get-char input-win)))
+              (when (and ch (not (equal ch -1)))
+                (log-debug "KEY: ~s" ch)
+                (cond
+                  ((or (eql ch 10) (eql ch 13) (eq ch :enter) (eql ch #\Newline) (eql ch #\Return))
+                   (input-submit *stream*)
+                   (chat-render chat-win chat-h))
+                  ((or (eql ch 127) (eql ch 8) (eq ch :backspace) (eql ch #\Backspace))
+                   (input-backspace))
+                  ((characterp ch)
+                   (push ch *input-buffer*))
+                  ((integerp ch)
+                   (let ((converted (code-char ch)))
+                     (when (graphic-char-p converted)
+                       (push converted *input-buffer*))))))
+              (clear input-win)
+              (add-string input-win (format nil "▶ ~a" (coerce (reverse *input-buffer*) 'string)) :y 0 :x 1)
+              (refresh input-win))
+            (sleep 0.01))))
+    (setf *is-running* nil)
+    (when *socket* (ignore-errors (usocket:socket-close *socket*)))))
+#+end_src
+
+** REPL test script (tmux)
+
+Use this script to test the TUI non-interactively in a tmux session. It launches the TUI in a headless tmux window, sends text, and captures the output.
+
+#+begin_src bash :tangle no
+#!/bin/bash
+SESSION="oct-tui-test"
+tmux new-session -d -s "$SESSION" \
+    -e OC_CONFIG_DIR="$HOME/.config/passepartout" \
+    -e PASSEPARTOUT_DATA_DIR="$HOME/.local/share/passepartout" \
+    -e TERM="screen-256color" \
+    "sbcl --non-interactive \
+        --eval '(load (merge-pathnames \"quicklisp/setup.lisp\" (user-homedir-pathname)))' \
+        --eval '(push (truename \"$HOME/.local/share/passepartout/\") asdf:*central-registry*)' \
+        --eval '(ql:quickload :passepartout/tui)' \
+        --eval '(passepartout.gateway-tui:main)'"
+sleep 5
+tmux capture-pane -t "$SESSION" -p -S -20
+tmux send-keys -t "$SESSION" 'hello' Enter
+sleep 8
+tmux capture-pane -t "$SESSION" -p -S -20
+tmux send-keys -t "$SESSION" '/exit' Enter
+sleep 1
+tmux kill-session -t "$SESSION" 2>/dev/null || true
+#+end_src

org/package.lisp

@@ -0,0 +1,226 @@
+(defpackage :passepartout
+  (:use :cl)
+  (:export
+   #:frame-message
+   #:read-framed-message
+   #:PROTO-GET
+   #:LIST-OBJECTS-WITH-ATTRIBUTE
+   #:COSINE-SIMILARITY
+   #:VAULT-MASK-STRING
+   #:*VAULT-MEMORY*
+   #:parse-message
+   #:make-hello-message
+   #:validate-communication-protocol-schema
+   #:start-daemon
+   #:stop-daemon
+   #:log-message
+   #:main
+   #:doctor-run-all
+   #:doctor-main
+   #:doctor-check-dependencies
+   #:doctor-check-env
+   #:register-provider
+   #:system-ready-p
+   #:run-setup-wizard
+   #:skill-gateway-register
+   #:skill-gateway-link
+   #:gateway-manager-main
+   #:ingest-ast
+   #:lookup-object
+   #:list-objects-by-type
+   #:org-id-new
+   #:*memory*
+   #:*history-store*
+   #:org-object
+   #:make-org-object
+   #:org-object-id
+   #:org-object-type
+   #:org-object-attributes
+   #:org-object-parent-id
+   #:org-object-children
+   #:org-object-version
+   #:org-object-last-sync
+   #:org-object-vector
+   #:org-object-content
+   #:org-object-hash
+   #:snapshot-memory
+   #:rollback-memory
+   #:context-query-store
+   #:context-get-active-projects
+   #:context-get-recent-completed-tasks
+   #:context-list-all-skills
+   #:context-get-skill-source
+   #:context-get-system-logs
+   #:context-resolve-path
+   #:context-get-skill-telemetry
+   #:telemetry-track
+   #:context-assemble-global-awareness
+   #:process-signal
+   #:perceive-gate
+   #:probabilistic-gate
+   #:consensus-gate
+   #:act-gate
+   #:reason-gate
+   #:dispatch-gate
+   #:inject-stimulus
+   #:initialize-actuators
+   #:dispatch-action
+   #:register-actuator
+   #:load-skill-from-org
+   #:initialize-all-skills
+   #:load-skill-with-timeout
+   #:topological-sort-skills
+   #:validate-lisp-syntax
+   #:defskill
+   #:*skill-registry*
+   #:skill
+   #:skill-name
+   #:skill-priority
+   #:skill-dependencies
+   #:skill-trigger-fn
+   #:skill-probabilistic-prompt
+   #:skill-deterministic-fn
+   #:cognitive-tool-define
+   #:*cognitive-tool-registry*
+   #:verify-git-clean-p
+   #:engineering-standards-verify-lisp
+   #:engineering-standards-format-lisp
+   #:literate-check-block-balance
+   #:check-tangle-sync
+   #:*tangle-targets*
+   #:utils-org-read-file
+   #:utils-org-write-file
+   #:utils-org-add-headline
+   #:utils-org-set-property
+   #:utils-org-set-todo
+   #:utils-org-find-headline-by-id
+   #:utils-org-find-headline-by-title
+   #:utils-org-generate-id
+   #:utils-org-id-format
+   #:utils-org-ast-to-org
+   #:utils-org-modify
+   #:utils-lisp-validate
+   #:utils-lisp-check-structural
+   #:utils-lisp-check-syntactic
+   #:utils-lisp-check-semantic
+   #:utils-lisp-eval
+   #:utils-lisp-format
+   #:utils-lisp-list-definitions
+   #:utils-lisp-structural-extract
+   #:utils-lisp-structural-wrap
+   #:utils-lisp-structural-inject
+   #:utils-lisp-structural-slurp
+   #:utils-lisp-register
+   #:get-oc-config-dir
+   #:prompt-for
+   #:save-secret
+   #:get-tool-permission
+   #:set-tool-permission
+   #:check-tool-permission-gate
+   #:cognitive-tool
+   #:cognitive-tool-name
+   #:cognitive-tool-description
+   #:cognitive-tool-parameters
+   #:cognitive-tool-guard
+   #:cognitive-tool-body
+   #:*emacs-clients*
+   #:*clients-lock*
+   #:register-emacs-client
+   #:unregister-emacs-client
+   #:ask-probabilistic
+   #:register-probabilistic-backend
+   #:distill-prompt
+   #:*probabilistic-backends*
+   #:*provider-cascade*
+   #:vault-get-secret
+   #:vault-set-secret
+   #:memory-objects-by-attribute
+   #:deterministic-verify
+   #:find-headline-missing-id))
+
+(in-package :passepartout)
+
+(defun plist-get (plist key)
+  "Robust plist accessor — checks both :KEY and :key variants."
+  (let* ((s (string key))
+         (up (intern (string-upcase s) :keyword))
+         (dn (intern (string-downcase s) :keyword)))
+    (or (getf plist up) (getf plist dn))))
+
+(defvar *log-buffer* nil)
+(defvar *log-lock* (bordeaux-threads:make-lock "log-messages-lock"))
+(defvar *log-limit* 100)
+
+(defvar *skill-registry* (make-hash-table :test 'equal)
+  "Global registry of all loaded skills.")
+
+(defvar *telemetry-table* (make-hash-table :test 'equal))
+(defvar *telemetry-lock* (bordeaux-threads:make-lock "harness-telemetry-lock"))
+
+(defun telemetry-track (skill-name duration status)
+  "Updates performance metrics for a skill. STATUS is :success or :rejected."
+  (when skill-name
+    (bordeaux-threads:with-lock-held (*telemetry-lock*)
+      (let ((entry (or (gethash skill-name *telemetry-table*) (list :executions 0 :total-time 0 :failures 0))))
+        (incf (getf entry :executions))
+        (incf (getf entry :total-time) duration)
+        (when (eq status :rejected) (incf (getf entry :failures)))
+        (setf (gethash skill-name *telemetry-table*) entry)))))
+
+(defvar *cognitive-tool-registry* (make-hash-table :test 'equal))
+
+(defstruct cognitive-tool
+  name
+  description
+  parameters
+  guard
+  body)
+
+(defmacro cognitive-tool-define (name description parameters &key guard body)
+  "Registers a cognitive tool. PARAMETERS is a list of plists, one per parameter."
+  `(setf (gethash (string-downcase (string ',name)) *cognitive-tool-registry*)
+         (make-cognitive-tool :name (string-downcase (string ',name))
+                              :description ,description
+                              :parameters ',parameters
+                              :guard ,guard
+                              :body ,body)))
+
+(defun cognitive-tool-prompt ()
+  "Serialises all registered tools into a prompt string for the LLM."
+  (let ((descriptions nil))
+    (maphash (lambda (k tool)
+               (declare (ignore k))
+               (push (format nil "- ~a: ~a~%  Parameters: ~a~%"
+                             (cognitive-tool-name tool)
+                             (cognitive-tool-description tool)
+                             (cognitive-tool-parameters tool))
+                     descriptions))
+              *cognitive-tool-registry*)
+    (if descriptions
+        (format nil "Available tools:~%~a" (apply #'concatenate 'string (sort descriptions #'string<)))
+        "No tools registered.")))
+
+(defun log-message (msg &rest args)
+  "Centralized, thread-safe logging for the harness."
+  (let ((formatted-msg (apply #'format nil msg args)))
+    (bordeaux-threads:with-lock-held (*log-lock*)
+      (push formatted-msg *log-buffer*)
+      (when (> (length *log-buffer*) *log-limit*)
+        (setq *log-buffer* (subseq *log-buffer* 0 *log-limit*))))
+    (format t "~a~%" formatted-msg)
+    (finish-output)))
+
+(setf *debugger-hook* (lambda (condition hook)
+  "Friendly error handler - shows diagnostic message instead of raw debugger."
+  (declare (ignore hook))
+  (format t "~%")
+  (format t "┌─────────────────────────────────────────────┐~%")
+  (format t "│  ERROR: ~A~%" (type-of condition))
+  (format t "│~%")
+  (format t "│  Run: opencortex doctor~%")
+  (format t "│  For system diagnostics~%")
+  (format t "└─────────────────────────────────────────────┘~%")
+  (format t "~%")
+  (format t "Details: ~A~%" condition)
+  (finish-output)
+  (uiop:quit 1)))

org/programming-lisp.org

@@ -0,0 +1,282 @@
+#+TITLE: SKILL: Utils Lisp (org-skill-utils-lisp.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:utils:lisp:validation:evaluation:
+#+PROPERTY: header-args:lisp :tangle ../lisp/programming-lisp.lisp
+
+* Architectural Intent: The Lisp Surgeon's Toolkit
+
+When the agent needs to modify its own code — fix a bug, add a feature, refactor a skill — it reaches for Utils Lisp. This skill provides every operation needed to read, validate, modify, and write Lisp code from within Lisp itself.
+
+This is possible only because Lisp is homoiconic: code is data. The agent can parse a function definition from a string, extract its body, wrap it in a new form, inject a new expression, and validate the result — all using the same data structures that the Lisp runtime uses to execute the code.
+
+The skill has four layers:
+1. **Validation** — three-phase gate: structural (paren balance) → syntactic (reader safety) → semantic (dangerous forms)
+2. **Evaluation** — sandboxed ~eval~ in a jailed package with ~*read-eval*~ nil
+3. **Structural surgery** — extract, inject, wrap, slurp — surgical code transformations without regex
+4. **Formatting** — auto-indentation via Emacs batch mode
+
+* Implementation
+
+** Structural Validation
+#+begin_src lisp
+(defun lisp-structural-check (code)
+  "Checks if parentheses are balanced and the code is readable."
+  (handler-case
+      (let ((*read-eval* nil))
+        (with-input-from-string (s code)
+          (loop for form = (read s nil :eof) until (eq form :eof)))
+        (values t nil))
+    (error (c)
+      (values nil (format nil "Reader Error: ~a" c)))))
+#+end_src
+
+** Syntactic Validation
+#+begin_src lisp
+(defun lisp-syntactic-check (code)
+  "Checks for valid Lisp syntax beyond just balanced parentheses."
+  (lisp-structural-check code))
+#+end_src
+
+** Semantic Validation (Safety)
+#+begin_src lisp
+(defun lisp-semantic-check (code)
+  "Checks for potentially unsafe forms."
+  (let ((unsafe-tokens '("eval" "load" "uiop:run-program" "sb-ext:run-program" "cl-user::eval")))
+    (loop for token in unsafe-tokens
+          when (search token (string-downcase code))
+          do (return-from lisp-semantic-check (values nil (format nil "Unsafe form detected: ~a" token))))
+    (values t nil)))
+#+end_src
+
+** Unified Validation Gate
+#+begin_src lisp
+(defun lisp-validate (code &key (strict t))
+  "Unified validation gate for Lisp code."
+  (multiple-value-bind (struct-ok struct-err) (lisp-structural-check code)
+    (unless struct-ok
+      (return-from lisp-validate (list :status :error :reason struct-err)))
+    (when strict
+      (multiple-value-bind (sem-ok sem-err) (lisp-semantic-check code)
+        (unless sem-ok
+          (return-from lisp-validate (list :status :error :reason sem-err)))))
+    (list :status :success)))
+#+end_src
+
+** Evaluation (REPL)
+#+begin_src lisp
+(defun lisp-eval (code-string &key (package :passepartout))
+  "Evaluates a Lisp string and captures its output/results."
+  (let ((out (make-string-output-stream))
+        (err (make-string-output-stream)))
+    (handler-case
+        (let* ((*standard-output* out)
+               (*error-output* err)
+               (*package* (or (find-package package) (find-package :passepartout)))
+               (result (with-input-from-string (s code-string)
+                         (let ((last-val nil))
+                           (loop for form = (read s nil :eof) until (eq form :eof)
+                                 do (setf last-val (eval form)))
+                           last-val))))
+          (list :status :success
+                :result (format nil "~a" result)
+                :output (get-output-stream-string out)
+                :error (get-output-stream-string err)))
+      (error (c)
+        (list :status :error
+              :reason (format nil "~a" c)
+              :output (get-output-stream-string out)
+              :error (get-output-stream-string err))))))
+#+end_src
+
+** Formatting (Emacs Batch)
+#+begin_src lisp
+(defun lisp-format (code-string)
+  "Attempts to format Lisp code using Emacs batch mode if available."
+  (handler-case
+      (let ((tmp-file "/tmp/oc-format-temp.lisp"))
+        (uiop:with-output-file (s tmp-file :if-exists :supersede)
+          (format s "~a" code-string))
+        (multiple-value-bind (out err code)
+            (uiop:run-program (list "emacs" "--batch" tmp-file 
+                                   "--eval" "(indent-region (point-min) (point-max))"
+                                   "--eval" "(princ (buffer-string))")
+                             :output :string :error-output :string :ignore-error-status t)
+          (if (= code 0)
+              out
+              (progn
+                (harness-log "FORMAT ERROR: ~a" err)
+                code-string))))
+    (error (c)
+      (harness-log "FORMAT EXCEPTION: ~a" c)
+      code-string)))
+#+end_src
+
+** Structural Extraction (AST)
+#+begin_src lisp
+(defun lisp-extract (code function-name)
+  "Extracts the definition of a specific function from a code string."
+  (let ((*read-eval* nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            when (and (listp form) 
+                      (symbolp (car form))
+                      (member (symbol-name (car form)) '("DEFUN" "DEFMACRO" "DEFMETHOD") :test #'string-equal)
+                      (symbolp (second form))
+                      (string-equal (symbol-name (second form)) function-name))
+            do (return-from lisp-extract (format nil "~s" form))))
+    nil))
+#+end_src
+
+** Structural Wrapping (AST)
+#+begin_src lisp
+(defun lisp-wrap (code target-name wrapper-symbol)
+  "Wraps a specific form in a wrapper form (e.g., wrap in a let)."
+  (let ((*read-eval* nil) (results nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            do (if (and (listp form) 
+                        (symbolp (second form))
+                        (string-equal (symbol-name (second form)) target-name))
+                   (push (list wrapper-symbol form) results)
+                   (push form results))))
+    (format nil "~{~s~^~%~%~}" (nreverse results))))
+#+end_src
+
+** List Definitions
+#+begin_src lisp
+(defun lisp-list-definitions (code)
+  "Returns a list of names for all top-level definitions (defun, defmacro, etc.)."
+  (let ((*read-eval* nil) (names nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            when (and (listp form) 
+                      (symbolp (car form))
+                      (member (symbol-name (car form)) 
+                              '("DEFUN" "DEFMACRO" "DEFMETHOD" "DEFVAR" "DEFPARAMETER")
+                              :test #'string-equal)
+                      (symbolp (second form)))
+            do (push (second form) names)))
+    (nreverse names)))
+#+end_src
+
+** Structural Injection (AST)
+#+begin_src lisp
+(defun lisp-inject (code target-name new-form-string)
+  "Injects a new form into the body of a targeted definition."
+  (let ((*read-eval* nil)
+        (new-form (read-from-string new-form-string))
+        (results nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            do (if (and (listp form) 
+                        (symbolp (car form))
+                        (member (symbol-name (car form)) '("DEFUN" "DEFMACRO" "DEFMETHOD") :test #'string-equal)
+                        (symbolp (second form))
+                        (string-equal (symbol-name (second form)) target-name))
+                   (push (append form (list new-form)) results)
+                   (push form results))))
+    (format nil "~{~s~^~%~%~}" (nreverse results))))
+#+end_src
+
+** Structural Slurp (AST)
+#+begin_src lisp
+(defun lisp-slurp (code target-name form-to-slurp-string)
+  "Adds a form to the end of a named list or definition (Paredit slurp)."
+  (let ((*read-eval* nil)
+        (to-slurp (read-from-string form-to-slurp-string))
+        (results nil))
+    (with-input-from-string (s code)
+      (loop for form = (read s nil :eof) until (eq form :eof)
+            do (if (and (listp form) 
+                        (symbolp (second form))
+                        (string-equal (symbol-name (second form)) target-name))
+                   (push (append form (list to-slurp)) results)
+                   (push form results))))
+    (format nil "~{~s~^~%~%~}" (nreverse results))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-programming-lisp
+  :priority 400
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src
+
+* Test Suite
+Tests for the Lisp Validator structural, syntactic, and semantic gates.
+#+begin_src lisp :tangle ../lisp/programming-lisp.lisp
+(defpackage :passepartout-utils-lisp-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:utils-lisp-suite))
+
+(in-package :passepartout-utils-lisp-tests)
+
+(def-suite utils-lisp-suite
+  :description "Tests for the Lisp Validator structural, syntactic, and semantic gates")
+
+(in-suite utils-lisp-suite)
+
+(test structural-balanced
+  (is (eq t (passepartout:lisp-structural-check "(+ 1 2)"))))
+
+(test structural-unbalanced-open
+  (multiple-value-bind (ok reason) (passepartout:lisp-structural-check "(+ 1 2")
+    (is (null ok))
+    (is (search "Reader Error" reason))))
+
+(test structural-unbalanced-close
+  (multiple-value-bind (ok reason) (passepartout:lisp-structural-check "+ 1 2)")
+    (is (null ok))
+    (is (search "Reader Error" reason))))
+
+(test syntactic-valid
+  (is (eq t (passepartout:lisp-syntactic-check "(+ 1 2)"))))
+
+(test semantic-safe
+  (is (eq t (passepartout:lisp-semantic-check "(+ 1 2)"))))
+
+(test semantic-blocked-eval
+  (multiple-value-bind (ok reason) (passepartout:lisp-semantic-check "(eval '(+ 1 2))")
+    (is (null ok))
+    (is (search "Unsafe" reason))))
+
+(test unified-success
+  (let ((result (passepartout:lisp-validate "(+ 1 2)" :strict t)))
+    (is (eq (getf result :status) :success))))
+
+(test unified-failure
+  (let ((result (passepartout:lisp-validate "(+ 1 2" :strict nil)))
+    (is (eq (getf result :status) :error))))
+
+(test eval-basic
+  (let ((result (passepartout:lisp-eval "(+ 1 2)")))
+    (is (eq (getf result :status) :success))
+    (is (string= (getf result :result) "3"))))
+
+(test structural-extract
+  (let* ((code "(defun hello () (print \"hi\")) (defun bye () (print \"bye\"))")
+         (extracted (passepartout:lisp-extract code "hello")))
+    (is (not (null extracted)))
+    (let ((form (read-from-string extracted)))
+      (is (eq (car form) 'DEFUN))
+      (is (eq (second form) 'HELLO)))))
+
+(test list-definitions
+  (let ((code "(defun foo () t) (defmacro bar () nil) (defparameter *baz* 10)"))
+    (let ((names (passepartout:lisp-list-definitions code)))
+      (is (member 'FOO names))
+      (is (member 'BAR names))
+      (is (member '*BAZ* names)))))
+
+(test structural-inject
+  (let* ((code "(defun my-fun (x) (print x))")
+         (injected (passepartout:lisp-inject code "my-fun" "(finish-output)")))
+    (let ((form (read-from-string injected)))
+      (is (equal (last form) '((FINISH-OUTPUT)))))))
+
+(test structural-slurp
+  (let* ((code "(defun work () (step-1))")
+         (slurped (passepartout:lisp-slurp code "work" "(step-2)")))
+    (let ((form (read-from-string slurped)))
+      (is (equal (last form) '((STEP-2)))))))
+#+end_src

org/programming-literate.org

@@ -0,0 +1,55 @@
+#+TITLE: SKILL: Literate Programming (org-skill-literate-programming.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:literate:tangle:
+#+PROPERTY: header-args:lisp :tangle ../lisp/programming-literate.lisp
+
+* Overview
+This skill enforces the literal programming discipline for all Passepartout source code. It defines the rules for one-function-per-block, prose-before-code, reflecting working code back from the REPL to Org, and the tangle mandate (never edit .lisp directly). Every Org file that contains Lisp code should follow the rules defined here.
+
+** Discipline Rules
+
+*** One Function, One Block
+Every ~#+begin_src lisp~ block contains exactly one function definition. Never bundle multiple definitions in a single block. This keeps the Org file granular, reviewable, and tanglable without side effects.
+
+*** Prose Before Code
+Every block must be preceded by an Org headline and explanatory prose that covers:
+- What the function does
+- Its arguments (including any &key, &optional)
+- Its return value
+- The rationale for its existence
+
+The prose is not a comment — it is the authoritative specification. The code implements what the prose describes.
+
+*** Reflect Back, Don't Write Directly
+Code is explored and verified in the REPL first (per Engineering Standards lifecycle). Once working, it is *reflected back* into the Org file. This means:
+- The REPL is the proving ground — iterate there
+- The Org file is the record — copy working code there
+- Never write code directly into an Org block without first evaluating it in the REPL
+
+*** Code and Prose Together
+Every ~#+begin_src lisp~ block flows from the prose above it. The reader (human or agent) should understand the function's contract from the prose before reading the code. If the code and prose disagree, the prose is wrong — update both.
+
+*** Tangle Mandate
+The `.lisp` file is derived, not authored. Never edit `.lisp` directly. All changes flow through Org: edit Org → tangle → `.lisp` updates. Violating this corrupts the skill loader and causes boot failure.
+
+* Implementation
+
+** Synchronization Logic
+#+begin_src lisp
+(defun literate-block-balance-check (org-file)
+  "Verifies that all Lisp source blocks in an Org file are balanced."
+  (harness-log "LITERATE: Checking block balance for ~a" org-file)
+  t)
+
+(defun literate-tangle-sync-check (org-file lisp-file)
+  "Verifies that the Lisp file matches the tangled output of the Org file."
+  (harness-log "LITERATE: Checking tangle sync for ~a <-> ~a" org-file lisp-file)
+  t)
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-programming-literate
+  :priority 300
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src

org/programming-org.org

@@ -0,0 +1,243 @@
+#+TITLE: SKILL: Utils Org (org-skill-utils-org.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:utils:org:
+#+PROPERTY: header-args:lisp :tangle ../lisp/programming-org.lisp
+
+* Overview
+Structural manipulation tools for Org-mode files. This skill handles reading, writing, and modifying Org files at the AST level: finding headlines by ID or title, setting properties and TODO states, adding new headlines, generating UUIDs, and converting ASTs back to Org text. It also implements the privacy filter — when reading an Org file, it strips headlines tagged with ~@personal~ (or any tag in ~bouncer-privacy-tags~) and rejects files with matching ~#+FILETAGS:~.
+
+* Implementation
+
+** Reading Files (with Privacy Filter)
+#+begin_src lisp
+(defun org-filetags-extract (content)
+  "Extracts the list of tags from a #+FILETAGS: line."
+  (let ((lines (uiop:split-string content :separator '(#\Newline))))
+    (dolist (line lines)
+      (when (uiop:string-prefix-p "#+FILETAGS:" (string-trim '(#\Space) line))
+        (let ((tag-str (string-trim " :" (subseq (string-trim '(#\Space) line) 10))))
+          (return-from org-filetags-extract
+            (mapcar (lambda (tag) (format nil ":~a" (string-trim '(#\Space) tag)))
+                    (uiop:split-string tag-str :separator '(#\space #\tab))))))))
+  nil)
+
+(defun org-privacy-tag-p (tags-list)
+  "Returns T if any tag in TAGS-LIST matches bouncer-privacy-tags."
+  (let ((privacy-tags (symbol-value (find-symbol "BOUNCER-PRIVACY-TAGS" :passepartout))))
+    (when (and tags-list privacy-tags)
+      (some (lambda (tag)
+              (some (lambda (private-tag)
+                      (string-equal (string-trim '(#\: #\space) tag)
+                                    (string-trim '(#\: #\space) private-tag))
+                    privacy-tags))
+            tags-list)))))
+
+(defun org-privacy-strip (content)
+  "Removes Org headlines whose :TAGS: property contains a privacy-filtered tag.
+Returns the filtered content as a string."
+  (let* ((lines (uiop:split-string content :separator '(#\Newline)))
+         (result-lines nil)
+         (skip-depth nil)
+         (current-tags nil)
+         (in-properties nil))
+    (dolist (line lines)
+      (cond
+        (skip-depth
+         ;; We're inside a skipped subtree
+         (when (and (uiop:string-prefix-p "*" (string-trim '(#\Space) line))
+                    (<= (length (string-trim '(#\Space) line)) skip-depth))
+           (setf skip-depth nil)))
+        ((uiop:string-prefix-p ":PROPERTIES:" (string-trim '(#\Space) line))
+         (setf in-properties t)
+         (push line result-lines))
+        ((uiop:string-prefix-p ":END:" (string-trim '(#\Space) line))
+         (setf in-properties nil)
+         (when current-tags
+           (when (org-privacy-tag-p (reverse current-tags))
+             (setf skip-depth
+                   (length (car (last result-lines
+                                      (1+ (position-if
+                                           (lambda (l)
+                                             (uiop:string-prefix-p "*" (string-trim '(#\Space) l)))
+                                           (reverse result-lines))))))))
+           (setf current-tags nil))
+         (push line result-lines))
+        ((and in-properties (uiop:string-prefix-p ":TAGS:" (string-trim '(#\Space) line)))
+         (let ((tag-val (string-trim '(#\Space) (subseq (string-trim '(#\Space) line) 6))))
+           (setf current-tags (uiop:split-string tag-val :separator '(#\space #\tab))))
+         (push line result-lines))
+        (t
+         (push line result-lines))))
+    (format nil "~{~a~%~}" (nreverse result-lines))))
+
+(defun org-read-file (filepath)
+  "Reads an Org file into a string, applying privacy filtering."
+  (let* ((raw (uiop:read-file-string filepath))
+         (filetags (org-filetags-extract raw)))
+    (if (org-privacy-tag-p filetags)
+        (progn
+          (harness-log "UTILS-ORG: Blocked read of ~a — file-level privacy tag(s) ~a" filepath filetags)
+          nil)
+        (org-privacy-strip raw))))
+#+end_src
+
+** Writing Files
+#+begin_src lisp
+(defun org-write-file (filepath content)
+  "Writes content to an Org file."
+  (uiop:with-output-file (s filepath :if-exists :supersede)
+    (format s "~a" content)))
+#+end_src
+
+** ID Generation
+#+begin_src lisp
+(defun org-id-generate ()
+  "Generates a new UUID for an Org node."
+  (string-downcase (format nil "~a" (uuid:make-v4-uuid))))
+#+end_src
+
+** ID Formatting
+#+begin_src lisp
+(defun org-id-format (id)
+  "Ensures the ID has the 'id:' prefix."
+  (if (uiop:string-prefix-p "id:" id)
+      id
+      (format nil "id:~a" id)))
+#+end_src
+
+** Setting Properties (Recursive)
+#+begin_src lisp
+(defun org-property-set (ast target-id property value)
+  "Recursively sets a property on a headline with a matching ID in the AST."
+  (let ((type (getf ast :type))
+        (props (getf ast :properties))
+        (contents (getf ast :contents)))
+    (when (and (eq type :HEADLINE) (string= (getf props :ID) target-id))
+      (setf (getf (getf ast :properties) property) value)
+      (return-from org-property-set t))
+    (dolist (child contents)
+      (when (listp child)
+        (when (org-property-set child target-id property value)
+          (return-from org-property-set t)))))
+  nil)
+#+end_src
+
+** Setting TODO Status
+#+begin_src lisp
+(defun org-todo-set (ast target-id status)
+  "Sets the TODO status of a headline in the AST."
+  (org-property-set ast target-id :TODO status))
+#+end_src
+
+** Adding Headlines
+#+begin_src lisp
+(defun org-headline-add (ast parent-id title)
+  "Adds a new headline as a child of the parent-id in the AST."
+  (let* ((type (getf ast :type))
+         (props (getf ast :properties))
+         (id (getf props :ID))
+         (contents (getf ast :contents)))
+    (when (and (eq type :HEADLINE) (string= id parent-id))
+      (let ((new-node (list :type :HEADLINE
+                           :properties (list :ID (org-id-format (org-id-generate))
+                                            :TITLE title)
+                           :contents nil)))
+        (setf (getf ast :contents) (append contents (list new-node)))
+        (return-from org-headline-add t)))
+    (dolist (child contents)
+      (when (listp child)
+        (when (org-headline-add child parent-id title)
+          (return-from org-headline-add t)))))
+  nil)
+#+end_src
+
+** Searching Headlines (by ID)
+#+begin_src lisp
+(defun org-headline-find-by-id (ast id)
+  "Finds a headline by its ID in the AST."
+  (let ((props (getf ast :properties)))
+    (when (string= (getf props :ID) id)
+      (return-from org-headline-find-by-id ast))
+    (dolist (child (getf ast :contents))
+      (when (listp child)
+        (let ((found (org-headline-find-by-id child id)))
+          (when found (return-from org-headline-find-by-id found)))))
+    nil))
+#+end_src
+
+** Searching Headlines (by Title)
+#+begin_src lisp
+(defun org-headline-find-by-title (ast title)
+  "Finds a headline by its title in the AST."
+  (let ((props (getf ast :properties)))
+    (when (string-equal (getf props :TITLE) title)
+      (return-from org-headline-find-by-title ast))
+    (dolist (child (getf ast :contents))
+      (when (listp child)
+        (let ((found (org-headline-find-by-title child title)))
+          (when found (return-from org-headline-find-by-title found)))))
+    nil))
+#+end_src
+
+** Placeholder for External Edits
+#+begin_src lisp
+(defun org-modify (filepath id changes)
+  "Placeholder for Emacs-driven modification of a specific node."
+  (declare (ignore changes))
+  (harness-log "UTILS-ORG: Applying changes to ~a in ~a" id filepath)
+  t)
+#+end_src
+
+** Placeholder for AST to Org conversion
+#+begin_src lisp
+(defun org-ast-render (ast)
+  "Minimal converter from AST back to Org text (Placeholder)."
+  (declare (ignore ast))
+  "* TITLE (Placeholder)")
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-programming-org
+  :priority 100
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src
+
+* Test Suite
+Verification of the structural manipulation for Org-mode files and their AST representation.
+#+begin_src lisp :tangle ../lisp/programming-org.lisp
+(defpackage :passepartout-utils-org-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:utils-org-suite))
+
+(in-package :passepartout-utils-org-tests)
+
+(def-suite utils-org-suite
+  :description "Tests for Utils Org skill.")
+
+(in-suite utils-org-suite)
+
+(test id-generation
+  (let ((id1 (org-id-generate))
+        (id2 (org-id-generate)))
+    (is (plusp (length id1)))
+    (is (not (string= id1 id2)))))
+
+(test id-format
+  (let ((formatted (org-id-format "abc12345")))
+    (is (search "id:" formatted))))
+
+(test property-setter
+  (let ((ast (list :type :HEADLINE
+                  :properties (list :ID "id:test123" :TITLE "Test")
+                  :contents nil)))
+    (org-property-set ast "id:test123" :STATUS "ACTIVE")
+    (is (string= (getf (getf ast :properties) :STATUS) "ACTIVE"))))
+
+(test todo-setter
+  (let ((ast (list :type :HEADLINE
+                  :properties (list :ID "id:todo001" :TITLE "Task")
+                  :contents nil)))
+    (org-todo-set ast "id:todo001" "DONE")
+    (is (string= (getf (getf ast :properties) :TODO) "DONE"))))
+#+end_src

org/programming-repl.org

@@ -0,0 +1,211 @@
+#+TITLE: SKILL: REPL (org-skill-repl.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:repl:interactive:debug:
+#+PROPERTY: header-args:lisp :tangle ../lisp/programming-repl.lisp
+
+* Overview
+The *REPL Skill* provides persistent Lisp evaluation, inspection, and debugging capabilities. This enables the agent to verify behavior at runtime rather than just at the text level.
+
+* Phase A: Demand (Thinking)
+** Why a REPL?
+The utils-lisp-eval function provides one-shot evaluation but:
+- No state persistence between calls
+- No variable inspection
+- No debugging capabilities
+
+The REPL skill fills this gap by:
+- Maintaining evaluation state across turns
+- Supporting variable inspection
+- Providing debugging commands
+- Optionally connecting to external Swank servers
+
+** Success Criteria
+- Code evaluation returns result + stdout/stderr separately
+- Variables can be inspected
+- Can load code into image
+- Optional: connect to external SLIME/Swank session
+
+* Phase B: Protocol (Spec)
+- `repl-eval` returns: (values result output error)
+- `repl-inspect` returns: structured description
+- `repl-list-vars` returns: list of bound symbols
+- `repl-load-file` returns: t on success, error on failure
+
+* Phase C: Implementation
+
+** Global State
+#+begin_src lisp
+(in-package :passepartout)
+
+(defvar *repl-package* :passepartout
+  "Default package for REPL evaluations.")
+
+(defvar *repl-history* nil
+  "History of evaluated forms for session continuity.")
+
+(defvar *repl-variables* (make-hash-table :test #'eq)
+  "Cache of bound variables for inspection.")
+#+end_src
+
+** Core Evaluation
+#+begin_src lisp
+(defun repl-eval (code-string &key (package *repl-package*))
+  "Evaluate Lisp code and return (values result output error).
+   - result: the return value as string
+   - output: captured stdout
+   - error: error message or nil on success"
+  (let ((out (make-string-output-stream))
+        (err (make-string-output-stream))
+        (pkg (or (find-package package) (find-package :passepartout))))
+    (handler-case
+        (let* ((*standard-output* out)
+               (*error-output* err)
+               (*package* pkg)
+               (*read-eval* nil)
+               (result nil))
+          (with-input-from-string (s code-string)
+            (loop for form = (read s nil :eof) until (eq form :eof)
+                  do (setf result (eval form))))
+          (push code-string *repl-history*)
+          (values
+           (format nil "~a" result)
+           (get-output-stream-string out)
+           nil))
+      (error (c)
+        (values
+         nil
+         (get-output-stream-string out)
+         (format nil "~a" c))))))
+#+end_src
+
+** Variable Inspection
+#+begin_src lisp
+(defun repl-inspect (symbol-name &key (package *repl-package*))
+  "Inspect a variable's value and structure."
+  (let* ((pkg (or (find-package package) (find-package :passepartout)))
+         (sym (find-symbol (string-upcase symbol-name) pkg)))
+    (cond
+      ((null sym)
+       (format nil "Symbol ~a not found in package ~a" symbol-name package))
+      ((boundp sym)
+       (let ((val (symbol-value sym)))
+         (format nil "~a = ~a~%Type: ~a~%~%"
+                 sym val (type-of val))))
+      ((fboundp sym)
+       (format nil "~a is a function~%Args: ~a~%"
+               sym (documentation sym 'function)))
+      (t
+       (format nil "~a is unbound" symbol-name)))))
+#+end_src
+
+** List Bound Variables
+#+begin_src lisp
+(defun repl-list-vars (&key (package *repl-package*))
+  "List all bound variables in the package."
+  (let* ((pkg (or (find-package package) (find-package :passepartout)))
+         (vars nil))
+    (do-symbols (sym pkg)
+      (when (boundp sym)
+        (push (format nil "~a" sym) vars)))
+    (sort vars #'string<)))
+#+end_src
+
+** Load File into Image
+#+begin_src lisp
+(defun repl-load-file (filepath)
+  "Load a Lisp file into the current image."
+  (handler-case
+      (progn
+        (load filepath)
+        (format nil "Loaded ~a" filepath))
+    (error (c)
+      (format nil "Error loading ~a: ~a" filepath c))))
+#+end_src
+
+** Package Switching
+#+begin_src lisp
+(defun repl-set-package (package-name)
+  "Set the default package for REPL evaluations."
+  (let ((pkg (find-package (string-upcase package-name))))
+    (if pkg
+        (setf *repl-package* pkg)
+        (format nil "Package ~a not found" package-name))))
+#+end_src
+
+** Help/Info
+#+begin_src lisp
+(defun repl-help ()
+  "Return available REPL commands."
+  (format nil "~%
+REPL Skill Commands:
+-------------------
+(repl-eval \"code\" :package :passepartout)
+  - Evaluate Lisp code, returns (values result output error)
+
+(repl-inspect \"symbol\" :package :passepartout)
+  - Inspect a variable or function
+
+(repl-list-vars :package :passepartout)
+  - List all bound variables
+
+(repl-load-file \"/path/to/file.lisp\")
+  - Load a file into the image
+
+(repl-set-package :package-name)
+  - Switch default package
+
+(repl-help)
+  - Show this message
+"))
+#+end_src
+
+* Phase D: Verification
+
+** Basic Evaluation Test
+#+begin_src lisp :tangle no
+(test test-repl-eval-simple
+  "Test basic arithmetic evaluation."
+  (multiple-value-bind (result output error)
+      (passepartout:repl-eval "(+ 1 2)")
+    (is (string= result "3"))
+    (is (null error))))
+#+end_src
+
+** Error Handling Test
+#+begin_src lisp :tangle no
+(test test-repl-eval-error
+  "Test that errors are caught and returned."
+  (multiple-value-bind (result output error)
+      (passepartout:repl-eval "(+ 1 \"string\")")
+    (is (null result))
+    (is (not (null error)))))
+#+end_src
+
+* Phase E: Lifecycle
+The REPL skill loads at priority 200 (after diagnostics at 100, before utils-lisp at 400).
+
+** System Prompt Augment (repl-mandate)
+#+begin_src lisp
+(defun repl-mandate (context)
+  "Returns REPL-first engineering mandate when context involves code editing."
+  (let ((raw (or (proto-get (proto-get context :payload) :text) "")))
+    (when (or (search "org-skill-" raw :test #'char-equal)
+              (and (search ".org" raw :test #'char-equal)
+                   (or (search "defun" raw :test #'char-equal)
+                       (search "tangle" raw :test #'char-equal)
+                       (search "write-file" raw :test #'char-equal)
+                       (search "lisp" raw :test #'char-equal)))
+              (search "defun " raw :test #'char-equal)
+              (search "repl-eval" raw :test #'char-equal)
+              (search "validate" raw :test #'char-equal))
+      (format nil "~%REPL-FIRST MANDATE:~%Before writing any defun to an Org file, prototype it in the REPL first. Set :repl-verified t on the write action. On rejection, fix the error and retry.~%"))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-programming-repl
+  :priority 200
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil)
+  :deterministic (lambda (action ctx) (declare (ignore action ctx)) nil)
+  :system-prompt-augment #'repl-mandate)
+#+end_src

org/programming-standards.org

@@ -0,0 +1,90 @@
+#+TITLE: SKILL: Engineering Standards (org-skill-engineering-standards.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:engineering:chaos:
+#+DEPENDS_ON: org-skill-utils-lisp
+#+PROPERTY: header-args:lisp :tangle ../lisp/programming-standards.lisp
+
+* Overview
+The *Engineering Standards Skill* defines the REPL-first engineering lifecycle and enforces technical invariants, including the **Commit-Before-Modify** rule and **Chaos-Driven Development**.
+
+** Engineering Lifecycle (Two-Track)
+
+The canonical workflow. Two tracks, not to be confused:
+
+*** Track 1 — Org-First: Prose, Tests, Thinking (Phases 0/A)
+
+This track stays in Org. No code is written yet.
+
+**** Phase 0: Exploration & Documentation
+1. Read the relevant Org source files for context
+2. Explore the problem in the running REPL with ~repl-inspect~ and ~repl-eval~
+3. Document findings in Org prose
+4. If a bug: document investigation in Org before fixing (Org as thinking medium)
+
+**** Phase A: Test-First Design
+1. Write the success criteria in Org prose — what the function does, arguments, return value, rationale
+2. Write the FiveAM test in a ~#+begin_src lisp :tangle no~ block
+3. Tangle the test and evaluate in the REPL — confirm it fails (red)
+4. The failing test is the success criteria. Do not proceed to Track 2 until it exists and is red.
+
+*** Track 2 — REPL-First: Implementation, Iteration, Reflection (Phases B/C/D/E)
+
+Code is prototyped in the REPL, never written directly into Org first.
+
+**** Phase B/C: REPL Implementation
+1. Write the function directly in the REPL using ~repl-eval~
+2. Iterate: evaluate, inspect, fix, re-evaluate — the image accumulates state
+3. Run the test in the REPL — confirm green
+4. Explore edge cases with ~repl-inspect~ and ad-hoc evaluations
+5. Before writing any ~defun~ in an Org block, verify it was prototyped and tested in the REPL first
+
+**** Phase D: Chaos Verification
+Run the appropriate chaos tier before reflecting code back to Org:
+- *Tier 1 (Deterministic)*: Full FiveAM test suite — required on every change
+- *Tier 2 (Probabilistic)*: Randomized fuzzing — required on every major release
+- *Tier 3 (Stress)*: Load and resource starvation — required during hardening sprints
+
+**** Phase E: Reflect Back to Org
+1. Copy the working function into its own ~#+begin_src lisp~ block in the Org file
+2. Update the prose to match what the function actually does (arguments, return, rationale)
+3. Before closing Phase E, run ~(utils-lisp-validate (uiop:read-file-string "path/to/file.lisp") :strict t)~ in the REPL — never external scripts or manual paren-counting
+4. Verify the Org file tangles correctly
+5. Tangle, commit, update GTD
+
+**** Syntax Error Protocol
+If a LOADER ERROR or reader-error occurs:
+1. Run ~(utils-lisp-validate (uiop:read-file-string "file.lisp") :strict t)~ in the REPL — never Python, never grep, never manual counting
+2. Fix the error in the Org file (since the code was prototyped in REPL first, this should be rare)
+3. Retangle and re-evaluate
+
+Rationale: The two tracks prevent the two failure modes we have observed. Writing implementation code directly in Org (without REPL prototyping) produces syntax errors that require external tools to debug. Skipping Org-first test writing produces code without verified success criteria. The split is not bureaucratic — it is the mechanism by which both failures are prevented.
+
+* Implementation
+
+** Standards Enforcement
+#+begin_src lisp
+(defun standards-git-clean-p (dir)
+  "Checks if a directory has uncommitted changes."
+  (let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain")
+                                 :output :string
+                                 :ignore-error-status t)))
+    (string= "" (string-trim '(#\Space #\Newline #\Tab) status))))
+
+(defun standards-lisp-verify (code)
+  "Enforces Lisp structural and semantic standards using utils-lisp."
+  (let ((result (utils-lisp-validate code :strict t)))
+    (if (eq (getf result :status) :success)
+        t
+        (error (getf result :reason)))))
+
+(defun standards-lisp-format (code)
+  "Ensures Lisp code adheres to formatting standards."
+  (utils-lisp-format code))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-programming-standards
+  :priority 100
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src

org/security-dispatcher.org

@@ -0,0 +1,423 @@
+#+TITLE: SKILL: Bouncer (org-skill-bouncer.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:bouncer:authorization:autonomy:
+#+PROPERTY: header-args:lisp :tangle ../lisp/security-dispatcher.lisp
+
+* Deep Reasoning: Beyond Permission
+
+The Bouncer is the physical security layer of Passepartout. While the Policy skill ensures an action is "legal" (e.g., "Yes, you are allowed to send a Telegram message"), the Bouncer ensures the action is "safe" by inspecting the payload content via Deep Packet Inspection.
+
+Every action that reaches the Bouncer has already been approved by the Reasoning pipeline. The LLM generated it, the deterministic gates verified it, and the Act stage is about to execute it. The Bouncer is the last gate before the action touches the physical world.
+
+The Bouncer inspects nine vectors:
+1. **REPL verification** — warns if a defun is written without REPL prototyping
+2. **Lisp syntax** — blocks writes with unbalanced parens
+3. **Secret paths** — blocks reads to ~.env~, SSH keys, PEM files, etc.
+4. **Content exposure** — scans for API keys, PGP blocks, tokens
+5. **Vault secrets** — matches against stored credentials
+6. **Privacy tags** — blocks ~@personal~ tagged content
+7. **Privacy text** — warns if text references privacy tag names
+8. **Shell safety** — blocks destructive commands and injection patterns
+9. **Network exfil** — blocks unwhitelisted outbound connections
+
+The Bouncer also handles the **Flight Plan** system: when a high-risk action is blocked, it creates a Flight Plan node in the Org files that the user can manually approve.
+
+* Implementation
+
+* Implementation
+
+** Security Configuration — network whitelist
+Domains that the Bouncer considers safe for outbound connections. Network calls to unlisted domains are blocked or queued for approval.
+#+begin_src lisp
+(defvar *dispatcher-network-whitelist*
+  '("api.telegram.org" "matrix.org" "googleapis.com" "openai.com" "anthropic.com")
+  "Domains the Bouncer considers safe for outbound connections.")
+#+end_src
+
+** Privacy filter tags (*dispatcher-privacy-tags*)
+List of tag strings that mark content as private. Content with these tags is filtered from the LLM context window. Configurable via ~PRIVACY_FILTER_TAGS~ env var.
+#+begin_src lisp
+(defvar *dispatcher-privacy-tags*
+  (let ((env (uiop:getenv "PRIVACY_FILTER_TAGS")))
+    (if env
+        (uiop:split-string env :separator '(#\,))
+        '("@personal")))
+  "Tags marking content as private. Set via PRIVACY_FILTER_TAGS.")
+#+end_src
+
+** Protected file paths (*dispatcher-protected-paths*)
+Path patterns (with * wildcards) that are blocked from file reads. Covers SSH keys, PEM/PGP files, credentials, tokens, env files, and cloud configs.
+#+begin_src lisp
+(defvar *dispatcher-protected-paths*
+  '(".env" ".env.example" ".env.local" ".env.production"
+    "*credentials*" "*cred*"
+    "*id_rsa*" "*id_dsa*" "*id_ecdsa*" "*id_ed25519*"
+    "*.pem" "*.key" "*.p12" "*.pfx" "*.asc" "*.gpg" "*.pgp"
+    "secring.*" "pubring.*" "private-keys-v1.d/*"
+    "token*" "*secret*" "*token*"
+    ".netrc" ".git-credentials" "auth.json"
+    ".aws/credentials" ".aws/config"
+    ".kube/config" "kubeconfig"
+    "*.cert" "*.crt" "*.csr"
+    "*password*" "*passwd*")
+  "Path patterns blocked from file reads.")
+#+end_src
+
+** Content exposure patterns (*dispatcher-exposure-patterns*)
+Named regex patterns for scanning content for secret exposure. Each entry is a (name regex) pair. Matches are reported by name so downstream code can act on specific categories.
+#+begin_src lisp
+(defvar *dispatcher-exposure-patterns*
+  '((:pem-key "-----BEGIN +(RSA|DSA|EC|OPENSSH|PGP) +PRIVATE +KEY *-----")
+    (:pgp-key "-----BEGIN +PGP +PRIVATE +KEY +BLOCK-----")
+    (:pgp-public "-----BEGIN +PGP +PUBLIC +KEY +BLOCK-----")
+    (:openai-key "sk-[A-Za-z0-9-]{20,}")
+    (:google-key "AIza[0-9A-Za-z_-]{35}")
+    (:github-token "gh[pousr]_[A-Za-z0-9]{36,}")
+    (:slack-token "xox[baprs]-[A-Za-z0-9-]{24,}")
+    (:env-assignment "[A-Z_]+=[A-Za-z0-9+/=_\\-]{20,}")
+    (:generic-secret "(api|secret|password|token)[ ]*[:=][ ]*[\"']?[A-Za-z0-9_\\-]{16,}"))
+  "Named regex patterns for secret exposure detection.")
+#+end_src
+
+** Shell safety — timeout
+Maximum seconds a shell command is allowed to run before being killed.
+#+begin_src lisp
+(defvar *dispatcher-shell-timeout* 30
+  "Maximum seconds for a shell command before timeout.")
+#+end_src
+
+** Shell safety — output limit
+Maximum characters of shell command output to capture. Prevents memory exhaustion from infinite output.
+#+begin_src lisp
+(defvar *dispatcher-shell-max-output* 100000
+  "Maximum characters of shell output to capture.")
+#+end_src
+
+** Shell safety — blocked patterns
+Destructive and injection patterns that are blocked in shell commands. Covers ~rm -rf /~, ~dd~, ~mkfs~, ~shred~, backtick injection, and ~$()~ subshell injection.
+#+begin_src lisp
+(defvar *dispatcher-shell-blocked*
+  '((:destructive-rm    "\\brm\\s+-rf\\s+/")
+    (:destructive-dd    "\\bdd\\s+if=")
+    (:destructive-mkfs  "\\bmkfs\\.")
+    (:destructive-format "\\bmformat\\b")
+    (:disk-wipe         "\\bshred\\s+/dev/")
+    (:disk-wipe-b       "\\bwipefs\\s+/dev/")
+    (:injection-backtick "`[^`]+`")
+    (:injection-subshell "\\$\\([^)]+\\)"))
+  "Destructive and injection patterns blocked in shell commands.")
+#+end_src
+
+** Secret Path Check (dispatcher-check-secret-path)
+#+begin_src lisp
+(defun wildcard-match (pattern path)
+  "Matches PATH against PATTERN where * matches any characters."
+  (let ((regex (cl-ppcre:regex-replace-all
+                "\\*" (cl-ppcre:quote-meta-chars pattern) ".*")))
+    (cl-ppcre:scan regex path)))
+
+(defun dispatcher-check-secret-path (filepath)
+  "Returns the matching pattern if FILEPATH matches a protected path, nil otherwise."
+  (when (and filepath (stringp filepath))
+    (some (lambda (pattern)
+            (when (wildcard-match pattern filepath)
+              pattern))
+          *dispatcher-protected-paths*)))
+#+end_src
+
+** Content Exposure Scanner (dispatcher-exposure-scan)
+#+begin_src lisp
+(defun dispatcher-exposure-scan (text)
+  "Scans TEXT for patterns matching known secret formats.
+Returns a list of matched category keywords."
+  (when (and text (stringp text) (> (length text) 0))
+    (let ((matches nil))
+      (dolist (entry *dispatcher-exposure-patterns*)
+        (let ((name (first entry))
+              (regex (second entry)))
+          (when (cl-ppcre:scan regex text)
+            (push name matches))))
+      matches)))
+#+end_src
+
+** Vault Secret Scanning (dispatcher-vault-scan)
+#+begin_src lisp
+(defun dispatcher-vault-scan (text)
+  "Scans TEXT for known secrets from the vault."
+  (when (and text (stringp text))
+    (let ((found-secret nil))
+      (maphash (lambda (key val)
+                 (when (and val (stringp val) (> (length val) 5))
+                   (when (search val text)
+                     (setf found-secret key))))
+               *vault-memory*)
+      found-secret)))
+#+end_src
+
+** Privacy Tag Check (dispatcher-check-privacy-tags)
+#+begin_src lisp
+(defun dispatcher-check-privacy-tags (tags-list)
+  "Returns T if any tag in TAGS-LIST matches a privacy filter tag."
+  (when (and tags-list (listp tags-list))
+    (some (lambda (tag)
+            (some (lambda (private)
+                    (or (string-equal tag private)
+                        (search private tag :test #'string-equal)))
+                  *dispatcher-privacy-tags*))
+          tags-list)))
+
+(defun dispatcher-check-text-for-privacy (text)
+  "Scans TEXT for leaked privacy-tagged content."
+  (when (and text (stringp text))
+    (let ((lower (string-downcase text)))
+      (some (lambda (tag)
+              (search (string-downcase tag) lower))
+            *dispatcher-privacy-tags*))))
+#+end_src
+
+** Lisp Validation Gate (dispatcher-check-lisp-valid)
+#+begin_src lisp
+(defun org-blocks-extract (content)
+  "Extracts concatenated Lisp code from #+begin_src lisp blocks in an Org string."
+  (when (and content (stringp content))
+    (let ((lines (uiop:split-string content :separator '(#\Newline)))
+          (in-block nil)
+          (code ""))
+      (dolist (line lines)
+        (let ((clean (string-trim '(#\Space #\Tab) line)))
+          (cond
+            ((search "#+begin_src lisp" clean)
+             (setf in-block t))
+            ((search "#+end_src" clean)
+             (setf in-block nil))
+            (in-block
+             (setf code (concatenate 'string code line (string #\Newline)))))))
+      (when (> (length code) 0) code))))
+
+(defun dispatcher-check-lisp-valid (filepath content)
+  "Validates Lisp syntax when writing .lisp files or Org files with lisp blocks.
+Returns the validation result plist or nil if not applicable."
+  (when (and content (stringp content) (> (length content) 0))
+    (let ((to-validate
+           (cond
+             ((uiop:string-suffix-p filepath ".lisp") content)
+             ((uiop:string-suffix-p filepath ".org") (org-blocks-extract content))
+             (t nil))))
+      (when to-validate
+        (multiple-value-bind (valid-p err) (ignore-errors
+                                            (let ((*read-eval* nil))
+                                              (with-input-from-string (s (format nil "(progn ~a)" to-validate))
+                                                (loop for form = (read s nil :eof) until (eq form :eof)))
+                                              (values t nil)))
+          (unless valid-p
+            (list :status :error :reason err)))))))
+#+end_src
+
+** REPL Verification Gate (dispatcher-check-repl-verified)
+#+begin_src lisp
+(defun org-has-defuns-p (content)
+  "Returns T if the Org content contains any #+begin_src lisp blocks with defuns."
+  (when (and content (stringp content))
+    (search "defun " content :test #'char-equal)))
+
+(defun dispatcher-check-repl-verified (action filepath content)
+  "Warns if writing a defun to an Org file without :repl-verified metadata."
+  (let ((repl-verified (getf action :repl-verified)))
+    (when (and filepath
+               (uiop:string-suffix-p filepath ".org")
+               (org-has-defuns-p content)
+               (not repl-verified))
+      (list :type :LOG
+            :payload (list :level :warn
+                           :text (format nil "Lint: Writing defun to ~a without :repl-verified flag. Did you prototype this in the REPL first?" filepath))))))
+#+end_src
+
+** Shell Safety Check (dispatcher-check-shell-safety)
+#+begin_src lisp
+(defun dispatcher-check-shell-safety (cmd)
+  "Checks a shell command for destructive patterns and injection vectors.
+Returns a list of matched pattern names or nil if safe."
+  (when (and cmd (stringp cmd) (> (length cmd) 0))
+    (let ((matches nil))
+      (dolist (entry *dispatcher-shell-blocked*)
+        (let ((name (first entry))
+              (regex (second entry)))
+          (when (cl-ppcre:scan regex cmd)
+            (push name matches))))
+      matches)))
+#+end_src
+
+** Network Check (dispatcher-check-network-exfil)
+#+begin_src lisp
+(defun dispatcher-check-network-exfil (cmd)
+  "Detects if CMD attempts to contact an unwhitelisted external host."
+  (when (and cmd (stringp cmd))
+    (multiple-value-bind (match regs)
+        (cl-ppcre:scan-to-strings "(http|https|ftp)://([\\w\\.-]+)" cmd)
+      (declare (ignore match))
+      (when regs
+        (let ((domain (aref regs 1)))
+          (not (some (lambda (safe) (search safe domain))
+                    *dispatcher-network-whitelist*)))))))
+#+end_src
+
+** Main Security Gate (dispatcher-check)
+#+begin_src lisp
+(defun dispatcher-check (action context)
+  "Security gate for high-risk actions.
+Vectors: lisp validation, secret path, secret content, vault secrets,
+privacy tags, privacy text, shell safety, network exfil, high-impact approval."
+  (declare (ignore context))
+  (let* ((target (proto-get action :target))
+         (payload (proto-get action :payload))
+         (text (or (proto-get payload :text) (proto-get action :text)))
+         (filepath (or (proto-get payload :filepath)
+                       (when (equal (proto-get payload :tool) "read-file")
+                         (proto-get (proto-get payload :args) :filepath))
+                       (when (equal (proto-get payload :tool) "write-file")
+                         (proto-get (proto-get payload :args) :filepath))))
+         (content (when filepath (proto-get (proto-get payload :args) :content)))
+         (cmd (or (proto-get payload :cmd)
+                  (when (and (eq target :tool) (equal (proto-get payload :tool) "shell"))
+                    (proto-get (proto-get payload :args) :cmd))))
+         (approved (proto-get action :approved))
+         (tags (proto-get payload :tags))
+         (lisp-valid (when (and filepath content (not approved))
+                       (dispatcher-check-lisp-valid filepath content)))
+         (repl-lint (when (and filepath content (not approved))
+                     (dispatcher-check-repl-verified action filepath content))))
+    (cond
+      (approved action)
+
+       ;; Vector 0: REPL verification lint (warn, don't block)
+      (repl-lint
+       (harness-log "BOUNCER: ~a" (proto-get repl-lint :text))
+       action)
+
+       ;; Vector 1: Lisp syntax validation (block bad lisp writes)
+      ((and lisp-valid (eq (getf lisp-valid :status) :error))
+       (harness-log "LINT VIOLATION: Blocked write — lisp syntax error in ~a: ~a" filepath (getf lisp-valid :reason))
+       (list :type :LOG
+             :payload (list :level :error
+                            :text (format nil "Lisp syntax error in ~a: ~a. The write was blocked. Fix the parenthesis balance and retry." filepath (getf lisp-valid :reason)))))
+
+      ;; Vector 2: File read to a protected secret path
+      ((and filepath (dispatcher-check-secret-path filepath))
+       (let ((matched (dispatcher-check-secret-path filepath)))
+         (harness-log "SECURITY VIOLATION: Blocked read of protected path '~a' (matched: ~a)" filepath matched)
+         (list :type :LOG
+               :payload (list :level :error
+                              :text (format nil "Action blocked: Attempted read of protected path '~a'" filepath)))))
+
+      ;; Vector 3: Content contains secret patterns
+      ((and text (dispatcher-exposure-scan text))
+       (let ((matched (dispatcher-exposure-scan text)))
+         (harness-log "SECURITY VIOLATION: Content contains secret patterns: ~a" matched)
+         (list :type :LOG
+               :payload (list :level :error
+                              :text "Action blocked: Content contains potential secret exposure."))))
+
+      ;; Vector 4: Content contains vault secrets
+      ((and text (dispatcher-vault-scan text))
+       (let ((secret-name (dispatcher-vault-scan text)))
+         (harness-log "SECURITY VIOLATION: Blocked potential leak of secret '~a'" secret-name)
+         (list :type :LOG
+               :payload (list :level :error
+                              :text (format nil "Action blocked: Potential exposure of '~a'" secret-name)))))
+
+      ;; Vector 5: Privacy-tagged content in action
+      ((and tags (dispatcher-check-privacy-tags tags))
+       (harness-log "PRIVACY VIOLATION: Action contains privacy-tagged content")
+       (list :type :LOG
+             :payload (list :level :warn
+                            :text "Action blocked: Content tagged with privacy filter.")))
+
+      ;; Vector 6: Text leaks privacy tag names
+      ((and text (dispatcher-check-text-for-privacy text))
+       (harness-log "PRIVACY WARNING: Text may contain leaked private content")
+       (list :type :LOG
+             :payload (list :level :warn
+                            :text "Action blocked: Text may reference private content.")))
+
+       ;; Vector 7: Shell destructive/injection patterns
+      ((and cmd (dispatcher-check-shell-safety cmd))
+       (let ((matched (dispatcher-check-shell-safety cmd)))
+         (harness-log "SHELL VIOLATION: Destructive or injection pattern in command: ~a" matched)
+         (list :type :LOG
+               :payload (list :level :error
+                              :text (format nil "Shell command blocked: contains unsafe pattern ~a" matched)))))
+
+      ;; Vector 8: Network exfiltration
+      ((and (or (eq target :shell)
+                (and (eq target :tool) (equal (proto-get payload :tool) "shell")))
+            (dispatcher-check-network-exfil cmd))
+        (harness-log "SECURITY WARNING: External network call detected. Queuing for approval.")
+        (list :type :EVENT :payload (list :sensor :approval-required :action action)))
+
+      ;; Vector 8: High-impact action approval
+      ((or (member target '(:shell))
+           (and (eq target :tool) (member (proto-get payload :tool) '("shell" "repair-file") :test #'string=))
+           (and (eq target :emacs) (eq (proto-get payload :action) :eval)))
+       (harness-log "SECURITY: High-impact action requires approval: ~a" (or (proto-get payload :tool) target))
+       (list :type :EVENT :payload (list :sensor :approval-required :action action)))
+      (t action))))
+
+#+end_src
+
+** Approval Processing (dispatcher-approvals-process)
+#+begin_src lisp
+(defun dispatcher-approvals-process ()
+  "Scans for APPROVED flight plans and re-injects them."
+  (let ((approved-nodes (list-objects-with-attribute :TODO "APPROVED"))
+        (found-any nil))
+    (dolist (node approved-nodes)
+      (let* ((attrs (org-object-attributes node))
+             (tags (getf attrs :TAGS))
+             (action-str (getf attrs :ACTION)))
+        (when (and (member "FLIGHT_PLAN" tags :test #'string-equal) action-str)
+          (harness-log "BOUNCER: Found approved flight plan '~a'. Re-injecting..." (org-object-id node))
+          (let ((action (ignore-errors (read-from-string action-str))))
+            (when action
+              (setf (getf action :approved) t)
+              (inject-stimulus action)
+              (setf (getf (org-object-attributes node) :TODO) "DONE")
+              (setq found-any t))))))
+    found-any))
+#+end_src
+
+** Flight Plan Creation (dispatcher-flight-plan-create)
+#+begin_src lisp
+(defun dispatcher-flight-plan-create (blocked-action)
+  "Creates a Flight Plan node for manual approval."
+  (let ((id (org-id-new)))
+    (harness-log "BOUNCER: Creating flight plan node '~a'..." id)
+    (list :type :REQUEST :target :emacs
+          :payload (list :action :insert-node :id id
+                         :attributes (list :TITLE "Flight Plan: High-Risk Action"
+                                           :TODO "PLAN" :TAGS '("FLIGHT_PLAN")
+                                           :ACTION (format nil "~s" blocked-action))))))
+#+end_src
+
+** Gate Logic (dispatcher-gate)
+#+begin_src lisp
+(defun dispatcher-gate (action context)
+  "Main deterministic gate for the Bouncer skill."
+  (let* ((payload (getf context :payload))
+         (sensor (getf payload :sensor)))
+    (case sensor
+      (:approval-required
+       (dispatcher-flight-plan-create (getf payload :action)))
+      (:heartbeat
+       (dispatcher-approvals-process)
+       (if action (dispatcher-check action context) action))
+      (otherwise
+       (if action (dispatcher-check action context) action)))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-security-dispatcher
+  :priority 150
+  :trigger (lambda (ctx) (declare (ignore ctx)) t)
+  :deterministic #'dispatcher-gate)
+#+end_src

org/security-permissions.org

@@ -0,0 +1,41 @@
+#+TITLE: SKILL: Tool Permissions (org-skill-tool-permissions.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:security:permissions:
+#+PROPERTY: header-args:lisp :tangle ../lisp/security-permissions.lisp
+
+* Overview: The Authorization Matrix
+
+Every cognitive tool (file read, file write, shell execute, etc.) has a permission level: ~:allow~ (executed without asking), ~:ask~ (user is prompted before execution), or ~:deny~ (blocked entirely). Tool Permissions maintains the registry of these levels and provides the ~permission-gate-check~ that the Bouncer calls before dispatching a tool action.
+
+The default for any unregistered tool is ~:ask~ — cautious by default, permissive by configuration. This prevents a hallucinated tool call from executing without at least giving the user a chance to review it.
+
+* Implementation
+
+** Permission store (tool level)
+Hash table mapping tool names to their permission level.
+#+begin_src lisp
+(defvar *permission-table* (make-hash-table :test 'equal))
+#+end_src
+
+** Set permission
+Sets the permission level for a specific cognitive tool.
+#+begin_src lisp
+(defun permission-set (tool-name level)
+  "Sets the permission level for a tool."
+  (setf (gethash (string-downcase (string tool-name)) *permission-table*) level))
+#+end_src
+
+** Get permission
+Retrieves the current permission level for a tool. Defaults to ~:ask~ if unset.
+#+begin_src lisp
+(defun permission-get (tool-name)
+  "Retrieves the permission level for a tool. Defaults to :ask."
+  (gethash (string-downcase (string tool-name)) *permission-table* :ask))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-security-permissions
+  :priority 600
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src

org/security-policy.org

@@ -0,0 +1,38 @@
+#+TITLE: SKILL: Policy (org-skill-policy.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:policy:constitutional:
+#+PROPERTY: header-args:lisp :tangle ../lisp/security-policy.lisp
+
+* Architectural Intent: The Constitutional Layer
+
+The Policy skill encodes the non-negotiable values of Passepartout. Every action the agent proposes must pass through this gate. If the action lacks justification, it is blocked — not because it's dangerous, but because it's opaque.
+
+This is the "Radical Transparency" invariant in practice. The agent must explain *why* it wants to do something, not just *what* it wants to do. An action with ~:explanation "Because I said so"~ is rejected. An action with ~:explanation "The user asked me to read their TODO list and summarize it"~ passes.
+
+The Policy skill is intentionally simple. It has one job: ensure every action has a meaningful explanation. Other security concerns (secret scanning, path blocking, network exfiltration) are handled by the Bouncer. The Policy is about values, not threats.
+
+* Implementation
+
+** Policy Logic (policy-compliance-check)
+#+begin_src lisp
+(defun policy-compliance-check (action context)
+  "Enforces constitutional invariants on proposed actions."
+  (declare (ignore context))
+  (let* ((payload (proto-get action :payload))
+         (explanation (proto-get payload :explanation)))
+    (if (and explanation (stringp explanation) (> (length explanation) 10))
+        action
+        (progn
+          (harness-log "POLICY VIOLATION: Action lacks sufficient explanation.")
+          (list :type :LOG
+                :payload (list :level :warn
+                              :text "Action blocked: Missing or insufficient :explanation. Please justify your reasoning."))))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-security-policy
+  :priority 500
+  :trigger (lambda (ctx) (declare (ignore ctx)) t)
+  :deterministic #'policy-compliance-check)
+#+end_src

org/security-validator.org

@@ -0,0 +1,29 @@
+#+TITLE: SKILL: Protocol Validator (org-skill-protocol-validator.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:protocol:validation:
+#+PROPERTY: header-args:lisp :tangle ../lisp/security-validator.lisp
+
+* Overview
+The Protocol Validator enforces schema compliance on every message entering or leaving the cognitive pipeline. It checks that messages are valid plists, that they have the required ~:type~ and ~:payload~ fields, and that the type is one of the known types (~:REQUEST~, ~:EVENT~, ~:RESPONSE~, ~:LOG~, ~:STATUS~). This prevents malformed messages from crashing the pipeline and ensures backward compatibility when the protocol evolves.
+
+* Implementation
+
+** Validation Logic
+#+begin_src lisp
+(defun validator-protocol-check (msg)
+  "Enforces structural schema compliance on protocol messages."
+  (validate-communication-protocol-schema msg))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-security-validator
+  :priority 95
+  :trigger (lambda (ctx) (declare (ignore ctx)) t)
+  :deterministic (lambda (action ctx)
+                   (declare (ignore ctx))
+                   (handler-case
+                       (progn (validator-protocol-check action) action)
+                     (error (c)
+                       (list :type :LOG :payload (list :level :error :text (format nil "Protocol Violation: ~a" c)))))))
+#+end_src

org/security-vault.org

@@ -0,0 +1,44 @@
+#+TITLE: SKILL: Credentials Vault (org-skill-credentials-vault.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:security:vault:
+#+PROPERTY: header-args:lisp :tangle ../lisp/security-vault.lisp
+
+* Overview
+The *Credentials Vault* provides secure in-memory storage for sensitive API keys and session tokens.
+
+* Implementation
+
+** Vault Storage
+#+begin_src lisp
+(defvar *vault-memory* (make-hash-table :test 'equal)
+  "In-memory cache of sensitive credentials.")
+#+end_src
+
+** Secret Management
+#+begin_src lisp
+(defun vault-get (provider &key (type :api-key))
+  "Retrieves a credential from the vault or environment."
+  (let* ((key (format nil "~a-~a" provider type))
+         (val (gethash key *vault-memory*)))
+    (if val
+        val
+        (let ((env-var (case provider
+                          (:gemini "GEMINI_API_KEY")
+                          (:openai "OPENAI_API_KEY")
+                          (:anthropic "ANTHROPIC_API_KEY")
+                          (:openrouter "OPENROUTER_API_KEY")
+                          (otherwise nil))))
+          (when env-var (uiop:getenv env-var))))))
+
+(defun vault-set (provider secret &key (type :api-key))
+  "Stores a secret in the vault."
+  (let ((key (format nil "~a-~a" provider type)))
+    (setf (gethash key *vault-memory*) secret)))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-security-vault
+  :priority 600
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src

org/setup.org

@@ -0,0 +1,38 @@
+#+TITLE: Kernel Bootstrap (setup.org)
+#+AUTHOR: Amr
+#+FILETAGS: :harness:kernel:bootstrap:
+#+STARTUP: content
+
+* Overview: Architectural Intent
+
+The Kernel Bootstrap is the transition from a bare POSIX shell to a running Lisp environment. It's the only part of Passepartout that executes before the Lisp image is ready.
+
+The bootstrap has exactly three jobs, nothing more:
+1. **Directory Resolution**: Locating and creating XDG paths for config, data, and state
+2. **System Tangle**: Transforming literate Org sources into runnable Lisp files
+3. **Dependency Check**: Ensuring SBCL, Quicklisp, and Emacs are available
+
+This minimal interface is deliberate. The bootstrap should NOT know about LLM providers, diagnostic suites, or gateway configuration. Those are the job of the Lisp-level setup wizard, which runs after the bootstrap is complete.
+
+* Phase A: Demand (Thinking)
+** The Minimalist Kernel
+To maintain sovereignty, the harness must remain a "dumb" bus. It should not know about LLM providers or diagnostic suites. Its only responsibilities are:
+1. **Directory Resolution**: Locating XDG paths.
+2. **System Tangle**: Transforming literate Org sources into runnable Lisp.
+3. **Dependency Check**: Ensuring SBCL and Quicklisp are available.
+
+* Phase B: Protocol (Success Criteria)
+** Bootstrap Verification
+1. `test-xdg-dirs`: Verify that `setup_system` creates the Config/Data/State folders.
+2. `test-asdf-registration`: Verify that the `INSTALL_DIR` is correctly pushed to the ASDF central registry.
+
+* Phase C: Implementation (Build)
+
+** The Installer Script (passepartout)
+The shell script is the primary entry point. It handles the initial git clone, dependency installation, and literate tangle.
+
+#+begin_src bash :tangle no
+#!/bin/bash
+# (The content here is a duplicate of the main passepartout for literate consistency)
+# [Note: Implementation is already verified in the top-level script]
+#+end_src

org/setup.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+# (The content here is a duplicate of the main opencortex.sh for literate consistency)
+# [Note: Implementation is already verified in the top-level script]

org/system-actuator-shell.org

@@ -0,0 +1,51 @@
+#+TITLE: SKILL: Shell Actuator (org-skill-shell-actuator.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:actuator:shell:
+#+PROPERTY: header-args:lisp :tangle ../lisp/system-actuator-shell.lisp
+
+* Overview: The Physical Actuator
+
+The Shell Actuator is the agent's hand in the physical world. Given a shell command, it executes it via ~bash -c~ and returns the output. This is how the agent installs packages, reads files, runs scripts, and interacts with any Unix tool.
+
+Because shell execution is the highest-risk operation in the system, the Shell Actuator is protected by multiple safety layers:
+1. The Bouncer's shell safety gate blocks destructive commands (~rm -rf /~, ~dd~, ~mkfs~)
+2. The Bouncer's injection gate blocks backtick and ~$()~ patterns
+3. The Bouncer's network exfil gate blocks connections to unwhitelisted hosts
+4. The actuator enforces a timeout (default 30s) so hanging commands don't freeze the agent
+5. The actuator caps output (default 100KB) so infinite output doesn't exhaust memory
+
+* Implementation
+
+** Shell Execution (actuator-shell-execute)
+#+begin_src lisp
+(defun actuator-shell-execute (action context)
+  "Executes a bash command with timeout (via timeout(1)) and output limit."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (cmd (getf payload :cmd))
+         (timeout-sym (find-symbol "*BOUNCER-SHELL-TIMEOUT*" :passepartout))
+         (timeout (or (getf payload :timeout) (if timeout-sym (symbol-value timeout-sym) 30)))
+         (max-sym (find-symbol "*BOUNCER-SHELL-MAX-OUTPUT*" :passepartout))
+         (max-output (or (getf payload :max-output) (if max-sym (symbol-value max-sym) 100000)))
+         (wrapped-cmd (format nil "timeout ~a bash -c ~s" timeout cmd)))
+    (harness-log "ACT [Shell]: ~a (timeout: ~as)" cmd timeout)
+    (multiple-value-bind (out err code)
+        (uiop:run-program (list "bash" "-c" wrapped-cmd)
+                          :output :string :error-output :string
+                          :ignore-error-status t)
+      (cond
+        ((= code 124) (format nil "ERROR: Command timed out after ~a seconds" timeout))
+        ((> (length out) max-output)
+         (format nil "~a~%... (output truncated to ~a chars)" (subseq out 0 max-output) max-output))
+        ((= code 0) out)
+        (t (format nil "ERROR [~a]: ~a" code err))))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(register-actuator :shell #'actuator-shell-execute)
+
+(defskill :passepartout-system-actuator-shell
+  :priority 50
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src

org/system-archivist.org

@@ -0,0 +1,26 @@
+#+TITLE: SKILL: Scribe (org-skill-scribe.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:scribe:documentation:
+#+PROPERTY: header-args:lisp :tangle ../lisp/system-archivist.lisp
+
+* Overview
+The *Scribe Skill* manages the agent's internal documentation and logs.
+
+* Implementation
+
+** Documentation Logic
+#+begin_src lisp
+(defun archivist-log (signal)
+  "Logs a metabolic signal for later analysis."
+  (let ((type (getf signal :type))
+        (payload (getf signal :payload)))
+    (harness-log "SCRIBE: [~a] ~s" type payload)))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-system-archivist
+  :priority 100
+  :trigger (lambda (ctx) (member (getf ctx :type) '(:LOG :STATUS)))
+  :deterministic (lambda (action ctx) (declare (ignore action)) (archivist-log ctx) nil))
+#+end_src

org/system-config.org

@@ -0,0 +1,292 @@
+#+TITLE: SKILL: Config Manager (org-skill-config-manager.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:setup:config:
+#+PROPERTY: header-args:lisp :tangle ../lisp/system-config.lisp
+
+* Overview
+The *Config Manager* skill provides the Passepartout Agent with the capability to manage its own environment variables and provider configurations. It includes an interactive setup wizard for LLM providers, gateways, and system settings.
+
+* Implementation
+
+** Configuration directory (config-directory)
+Resolves the XDG config directory for Passepartout.
+#+begin_src lisp
+(defun config-directory ()
+  "Returns the absolute path to the opencortex config directory."
+  (let ((xdg (uiop:getenv "OC_CONFIG_DIR")))
+    (if xdg xdg (namestring (merge-pathnames ".config/passepartout/" (user-homedir-pathname))))))
+#+end_src
+
+** Config file path (config-file-path)
+Returns the path to the ~.env~ file within the config directory.
+#+begin_src lisp
+(defun config-file-path ()
+  "Returns the path to the .env configuration file."
+  (merge-pathnames ".env" (config-directory)))
+#+end_src
+
+** Ensure config directory (config-directory-ensure)
+Creates the config directory tree if it does not exist.
+#+begin_src lisp
+(defun config-directory-ensure ()
+  "Creates the configuration directory if it does not exist."
+  (ensure-directories-exist (config-directory)))
+#+end_src
+
+** Config File Operations
+#+begin_src lisp
+(defun config-read ()
+  "Reads the .env config file and returns an alist of KEY=VALUE pairs."
+  (let ((config-file (config-file-path)))
+    (when (uiop:file-exists-p config-file)
+      (let ((lines (uiop:read-file-lines config-file))
+            (result nil))
+        (dolist (line lines)
+          (when (and line (> (length line) 0)
+                     (not (uiop:string-prefix-p "#" line)))
+            (let ((eq-pos (position #\= line)))
+              (when eq-pos
+                (let ((key (string-trim " " (subseq line 0 eq-pos)))
+                      (value (string-trim " " (subseq line (1+ eq-pos)))))
+                  (push (cons key value) result))))))
+        (nreverse result)))))
+
+(defun config-write (config-alist)
+  "Writes the config alist to the .env file."
+  (config-directory-ensure)
+  (let ((config-file (config-file-path)))
+    (with-open-file (stream config-file :direction :output :if-exists :supersede :if-does-not-exist :create)
+      (format stream "# Passepartout Configuration~%")
+      (format stream "# Generated by opencortex setup~%~%")
+      (dolist (pair config-alist)
+        (format stream "~a=~a~%" (car pair) (cdr pair))))))
+
+(defun config-get (key)
+  "Gets a config value by key."
+  (let ((config (config-read)))
+    (cdr (assoc key config :test #'string=))))
+
+(defun config-set (key value)
+  "Sets a config value and saves to file."
+  (let ((config (config-read))
+        (pair (cons key value)))
+    (let ((existing (assoc key config :test #'string=)))
+      (if existing
+          (setf (cdr existing) value)
+          (push pair config))
+      (config-write config))))
+#+end_src
+
+** Input Utilities
+#+begin_src lisp
+(defun prompt (prompt-text)
+  "Simple prompt that returns user input as a string."
+  (format t "~a" prompt-text)
+  (finish-output)
+  (read-line))
+
+(defun prompt-yes-no (prompt-text)
+  "Prompts yes/no question. Returns T for yes, nil for no."
+  (let ((response (prompt (format nil "~a [Y/n]: " prompt-text))))
+    (or (string= response "")
+        (string-equal response "Y")
+        (string-equal response "y")
+        (string-equal response "yes"))))
+
+(defun prompt-choice (prompt-text options)
+  "Prompts user to choose from a list of options. Returns the chosen option or nil."
+  (format t "~a~%" prompt-text)
+  (let ((i 1))
+    (dolist (opt options)
+      (format t "  ~a) ~a~%" i opt)
+      (incf i)))
+  (let ((response (prompt "Choice")))
+    (let ((num (ignore-errors (parse-integer response))))
+      (when (and num (<= 1 num) (>= (length options) num))
+        (nth (1- num) options)))))
+#+end_src
+
+** LLM Provider Setup
+#+begin_src lisp
+(defparameter *available-providers*
+  '(("OpenAI" . "OPENAI_API_KEY")
+    ("Anthropic" . "ANTHROPIC_API_KEY")
+    ("OpenRouter" . "OPENROUTER_API_KEY")
+    ("Groq" . "GROQ_API_KEY")
+    ("Gemini" . "GEMINI_API_KEY")
+    ("Ollama (local)" . "OLLAMA_URL")))
+
+(defun setup-llm-providers ()
+  "Interactive wizard for configuring LLM providers."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " LLM Provider Configuration~%")
+  (format t "==================================================~%~%")
+  
+  (let ((current-providers (loop for (name . key) in *available-providers*
+                                when (config-get key)
+                                collect name)))
+    (when current-providers
+      (format t "Current providers: ~{~a~^, ~}~%~%" current-providers))
+    
+    (format t "Available providers:~%")
+    (dolist (p *available-providers*)
+      (format t "  - ~a~%" (car p)))
+    (format t "~%")
+    
+    (when (prompt-yes-no "Configure a new provider?")
+      (let ((chosen (prompt-choice "Select provider:" (mapcar #'car *available-providers*))))
+        (when chosen
+          (let ((env-key (cdr (assoc chosen *available-providers* :test #'string=))))
+            (if (string= chosen "Ollama (local)")
+                (progn
+                  (format t "Enter Ollama URL (e.g., http://localhost:11434): ")
+                  (let ((url (read-line)))
+                    (config-set env-key url)
+                    (format t "✓ Ollama configured at ~a~%" url)))
+                (progn
+                  (format t "Enter API key for ~a: " chosen)
+                  (let ((key (read-line)))
+                    (config-set env-key key)
+                    (format t "✓ ~a API key saved~%" chosen)))))))))
+  
+  (format t "~%"))
+
+(defun setup-add-provider ()
+  "Entry point for adding a single provider (called from CLI)."
+  (setup-llm-providers))
+#+end_src
+
+** Gateway Setup
+#+begin_src lisp
+(defun setup-gateways ()
+  "Interactive wizard for configuring external gateways."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " Gateway Configuration~%")
+  (format t "==================================================~%~%")
+  
+  (format t "Available gateways:~%")
+  (format t "  - Slack (https://api.slack.com/)~%")
+  (format t "  - Discord (https://discord.com/developers/)~%")
+  (format t "~%")
+  
+  (when (prompt-yes-no "Configure a gateway?")
+    (let ((chosen (prompt-choice "Select platform:" '("Slack" "Discord"))))
+      (when chosen
+        (let ((token (prompt (format nil "Enter ~a bot token: " chosen))))
+          (if (string= chosen "Slack")
+              (config-set "SLACK_TOKEN" token)
+              (config-set "DISCORD_TOKEN" token))
+          (format t "✓ ~a gateway configured~%" chosen)))))
+  
+  (format t "~%"))
+#+end_src
+
+** Skill Management
+#+begin_src lisp
+(defun setup-skills ()
+  "Interactive wizard for enabling/disabling skills."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " Skill Management~%")
+  (format t "==================================================~%~%")
+  
+  (format t "Note: Skill management is not yet implemented.~%")
+  (format t "Skills are automatically loaded from ~a~%" (or (uiop:getenv "PASSEPARTOUT_DATA_DIR") "~/.local/share/passepartout"))
+  (format t "~%"))
+#+end_src
+
+** Memory Settings
+#+begin_src lisp
+(defun setup-memory ()
+  "Interactive wizard for memory settings."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " Memory Settings~%")
+  (format t "==================================================~%~%")
+  
+  (let ((auto-save (prompt "Auto-save interval in seconds [300]:")))
+    (when (and auto-save (> (length auto-save) 0))
+      (config-set "MEMORY_AUTO_SAVE_INTERVAL" auto-save)))
+  
+  (let ((history (prompt "History retention in lines [1000]:")))
+    (when (and history (> (length history) 0))
+      (config-set "MEMORY_HISTORY_RETENTION" history)))
+  
+  (format t "✓ Memory settings saved~%")
+  (format t "~%"))
+#+end_src
+
+** Network Settings
+#+begin_src lisp
+(defun setup-network ()
+  "Interactive wizard for network settings."
+  (format t "~%~%")
+  (format t "==================================================~%")
+  (format t " Network Settings~%")
+  (format t "==================================================~%~%")
+  
+  (let ((timeout (prompt "Request timeout in seconds [30]:")))
+    (when (and timeout (> (length timeout) 0))
+      (config-set "REQUEST_TIMEOUT" timeout)))
+  
+  (let ((proxy (prompt "Proxy URL (leave empty for none) []:")))
+    (when (and proxy (> (length proxy) 0))
+      (config-set "HTTP_PROXY" proxy)))
+  
+  (format t "✓ Network settings saved~%")
+  (format t "~%"))
+#+end_src
+
+** Main Setup Wizard
+#+begin_src lisp
+(defun setup-wizard-run ()
+  "Main entry point for the interactive setup wizard."
+  (format t "~%~%")
+  (format t "╔═══════════════════════════════════════════════════╗~%")
+  (format t "║         Passepartout Setup Wizard                   ║~%")
+  (format t "╚═══════════════════════════════════════════════════╝~%")
+  (format t "~%")
+  (format t "This wizard will help you configure:~%")
+  (format t "  1. LLM Providers (OpenAI, Anthropic, etc.)~%")
+  (format t "  2. Gateway Links (Slack, Discord)~%")
+  (format t "  3. Memory Settings~%")
+  (format t "  4. Network Settings~%")
+  (format t "~%")
+  
+  (config-directory-ensure)
+  
+  ;; Step 1: LLM Providers
+  (when (prompt-yes-no "Configure LLM providers?")
+    (setup-llm-providers))
+  
+  ;; Step 2: Gateways
+  (when (prompt-yes-no "Configure gateways?")
+    (setup-gateways))
+  
+  ;; Step 3: Memory
+  (when (prompt-yes-no "Configure memory settings?")
+    (setup-memory))
+  
+  ;; Step 4: Network
+  (when (prompt-yes-no "Configure network settings?")
+    (setup-network))
+  
+  ;; Summary
+  (format t "==================================================~%")
+  (format t " Setup Complete!~%")
+  (format t "==================================================~%")
+  (format t "~%")
+  (format t "Configuration saved to: ~a~%" (config-file-path))
+  (format t "~%")
+  (format t "To verify your setup, run: passepartout doctor~%")
+  (format t "~%"))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-system-config
+  :priority 100
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src

org/system-diagnostics.org

@@ -0,0 +1,250 @@
+#+TITLE: SKILL: Diagnostics (org-skill-diagnostics.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:diagnostics:doctor:
+#+PROPERTY: header-args:lisp :tangle ../lisp/system-diagnostics.lisp
+
+* Why a Doctor?
+
+The Diagnostics skill is the self-knowledge of Passepartout. It answers "Is everything working?" by checking dependencies, environment variables, and LLM connectivity. Unlike the harness-level Doctor (which runs at boot and on CLI demand), this skill provides the Lisp-level diagnostic functions — defining what "healthy" means: which binaries must be present, which directories must exist, which API keys should be configured.
+
+* Phase A: Demand (Thinking)
+** Why a Doctor?
+The Doctor transforms opaque startup failures into actionable engineering reports. It ensures the Brain never attempts to boot in a compromised state.
+
+** Detection Invariant
+Binary detection must use shell probing (`which`) to account for varying `$PATH` inheritance between interactive and headless sessions.
+
+* Phase B: Protocol (Success Criteria)
+- Dependency check passes when all required binaries are found
+- Environment check passes when XDG directories exist and are accessible
+- LLM check passes when at least one provider is configured or Ollama is running locally
+
+* Phase C: Implementation (Build)
+
+** Global Configuration
+#+begin_src lisp
+(defvar *diagnostics-binaries* '("sbcl" "emacs" "git" "socat" "nc")
+  "List of external binaries required for full system operation.")
+
+(defvar *diagnostics-package-map*
+  '(("sbcl" . "sbcl")
+    ("emacs" . "emacs")
+    ("git" . "git")
+    ("socat" . "socat")
+    ("nc" . "netcat-openbsd")
+    ("curl" . "curl")
+    ("rlwrap" . "rlwrap"))
+  "Map binary names to apt package names.")
+
+(defvar *doctor-missing-deps* nil
+  "List of missing dependencies populated by diagnostics-dependencies-check.")
+
+(defvar *doctor-auto-install* t
+  "When T, doctor will attempt to install missing dependencies automatically.")
+#+end_src
+
+** Dependency Verification
+#+begin_src lisp
+(defun diagnostics-dependencies-check ()
+  "Verifies that required external binaries are available in the PATH via shell probe."
+  (setf *doctor-missing-deps* nil)
+  (let ((all-ok t))
+    (format t "DOCTOR: Checking system dependencies...~%")
+    (dolist (dep *diagnostics-binaries*)
+      (let ((path (ignore-errors
+                    (uiop:run-program (list "which" dep)
+                                      :output :string :ignore-error-status t))))
+        (if (and path (> (length path) 0))
+            (format t "  [OK] Found ~a~%" dep)
+            (progn
+              (format t "  [FAIL] Missing binary: ~a~%" dep)
+              (push dep *doctor-missing-deps*)
+              (setf all-ok nil)))))
+    (when (and all-ok (null *doctor-missing-deps*))
+      (format t "DOCTOR: All dependencies satisfied.~%"))
+    all-ok))
+#+end_src
+
+** Auto-Install Dependencies
+#+begin_src lisp
+(defun diagnostics-dependencies-install ()
+  "Attempts to install missing system dependencies via apt."
+  (when (null *doctor-missing-deps*)
+    (format t "DOCTOR: No missing dependencies to install.~%")
+    (return-from diagnostics-dependencies-install t))
+
+  (format t "DOCTOR: Attempting to install ~a missing dependencies...~%" (length *doctor-missing-deps*))
+
+  (let ((packages (remove-duplicates
+                   (mapcar (lambda (dep)
+                             (or (cdr (assoc dep *diagnostics-package-map* :test #'string=))
+                                 dep))
+                           *doctor-missing-deps*)
+                   :test #'string=)))
+    (format t "DOCTOR: Packages to install: ~a~%" packages)
+
+    (let ((cmd (format nil "apt-get install -y ~{~a~^ ~}" packages)))
+      (format t "DOCTOR: Running: ~a~%" cmd)
+      (handler-case
+          (let ((output (uiop:run-program cmd
+                                           :output :string
+                                           :error-output :string
+                                           :external-format :utf-8)))
+            (if (zerop (uiop:run-program (format nil "which ~a" (car *doctor-missing-deps*))
+                                          :ignore-error-status t))
+                (progn
+                  (format t "DOCTOR: Dependencies installed successfully.~%")
+                  (setf *doctor-missing-deps* nil)
+                  t)
+                (progn
+                  (format t "DOCTOR: Installation failed. Output: ~a~%" output)
+                  nil)))
+        (error (c)
+          (format t "DOCTOR: Installation error: ~a~%" c)
+          nil)))))
+#+end_src
+
+** XDG Environment Validation
+#+begin_src lisp
+(defun diagnostics-env-check ()
+  "Validates XDG directories and environment configuration."
+  (format t "DOCTOR: Checking XDG environment...~%")
+  (let ((all-ok t)
+        (config-dir (uiop:getenv "PASSEPARTOUT_CONFIG_DIR"))
+        (data-dir (uiop:getenv "PASSEPARTOUT_DATA_DIR"))
+        (state-dir (uiop:getenv "PASSEPARTOUT_STATE_DIR"))
+        (memex-dir (uiop:getenv "MEMEX_DIR")))
+
+    (flet ((check-dir (name path critical)
+             (if (and path (> (length path) 0))
+                 (if (uiop:directory-exists-p path)
+                     (format t "  [OK] ~a: ~a~%" name path)
+                     (progn
+                       (format t "  [FAIL] ~a directory missing: ~a~%" name path)
+                       (when critical (setf all-ok nil))))
+                 (progn
+                   (format t "  [FAIL] ~a variable not set.~%" name)
+                   (when critical (setf all-ok nil))))))
+
+      (check-dir "Config (PASSEPARTOUT_CONFIG_DIR)" config-dir t)
+      (check-dir "Data (PASSEPARTOUT_DATA_DIR)" data-dir t)
+      (check-dir "State (PASSEPARTOUT_STATE_DIR)" state-dir t)
+      (check-dir "Memex (MEMEX_DIR)" memex-dir t))
+    all-ok))
+#+end_src
+
+** LLM Connectivity
+The doctor checks all supported LLM providers and detects local Ollama instances.
+
+#+begin_src lisp
+(defun diagnostics-llm-check ()
+  "Tests connectivity to LLM providers. Returns T if at least one provider is configured."
+  (format t "DOCTOR: Checking LLM connectivity...~%")
+  (let ((providers '((:openrouter . "OPENROUTER_API_KEY")
+                     (:anthropic . "ANTHROPIC_API_KEY")
+                     (:openai . "OPENAI_API_KEY")
+                     (:groq . "GROQ_API_KEY")
+                     (:gemini . "GEMINI_API_KEY")
+                     (:deepseek . "DEEPSEEK_API_KEY")
+                     (:nvidia . "NVIDIA_API_KEY")
+                     (:ollama . "OLLAMA_URL")))
+        (configured nil))
+    (dolist (p providers)
+      (let ((env-val (uiop:getenv (cdr p))))
+        (cond
+          ((and env-val (> (length env-val) 0))
+           (format t "  [OK] ~a configured~%" (car p))
+           (setf configured t))
+          ((eq (car p) :ollama)
+           (let ((ollama-check (ignore-errors
+                                 (uiop:run-program '("curl" "-s" "http://localhost:11434/api/tags")
+                                                    :output :string :ignore-error-status t))))
+             (when (and ollama-check (search "\"models\"" ollama-check))
+               (format t "  [OK] Ollama local model server detected~%")
+               (setf configured t)))))))
+    (if configured
+        (progn
+          (format t "  [OK] LLM provider(s) available~%")
+          t)
+        (progn
+          (format t "  [WARN] No LLM provider configured.~%")
+          (format t "  Run 'passepartout configure' to configure a provider.~%")
+          t))))
+#+end_src
+
+** Orchestration
+#+begin_src lisp
+(defun diagnostics-run-all (&key (auto-install t))
+  "Executes the full diagnostic suite and returns T if system is healthy."
+  (format t "==================================================~%")
+  (format t " PASSEPARTOUT DOCTOR: Commencing Health Check~%")
+  (format t "==================================================~%")
+  (let ((dep-ok (diagnostics-dependencies-check)))
+    (when (and (not dep-ok) auto-install *doctor-auto-install*)
+      (format t "DOCTOR: Attempting automatic installation...~%")
+      (setf dep-ok (diagnostics-dependencies-install))
+      (when dep-ok
+        (setf dep-ok (diagnostics-dependencies-check))))
+    (let ((env-ok (diagnostics-env-check))
+          (llm-ok (diagnostics-llm-check)))
+      (format t "==================================================~%")
+      (if (and dep-ok env-ok)
+          (progn
+            (format t " ✓ SYSTEM HEALTHY: Ready for ignition.~%")
+            t)  ;; Explicitly return T
+          (progn
+            (format t "==================================================~%")
+            (format t " ISSUES FOUND:~%")
+            (when (not dep-ok)
+              (format t "  - Missing system dependencies~%"))
+            (when (not llm-ok)
+              (format t "  - No LLM provider configured~%"))
+            (format t "~%")
+            (format t " RECOMMENDED ACTIONS:~%")
+            (format t "  1. Run 'passepartout configure' to configure everything~%")
+            (format t "  2. Or run 'passepartout doctor --fix' for auto-repair~%")
+            (format t "==================================================~%")
+            nil)))))  ;; Return nil when issues found
+#+end_src
+
+** CLI Entry Point
+#+begin_src lisp
+(defun diagnostics-main ()
+  "Entry point for the 'doctor' CLI command."
+  (if (diagnostics-run-all)
+      (uiop:quit 0)
+      (uiop:quit 1)))
+#+end_src
+
+* Phase D: Verification (Testing)
+
+** Dependency Test
+#+begin_src lisp :tangle no
+(test test-doctor-dependency-check
+  "Verify that missing binaries are correctly identified as failures."
+  (let ((passepartout::*diagnostics-binaries* '("non-existent-binary-123")))
+    (is (null (passepartout:diagnostics-dependencies-check)))))
+#+end_src
+
+** Environment Test
+#+begin_src lisp :tangle no
+(test test-doctor-env-check
+  "Verify that an invalid MEMEX_DIR triggers a critical failure."
+  (let ((old-m (uiop:getenv "MEMEX_DIR")))
+    (unwind-protect
+         (progn
+           (setf (uiop:getenv "MEMEX_DIR") "/non/existent/path/999")
+           (is (null (passepartout:diagnostics-env-check))))
+      (setf (uiop:getenv "MEMEX_DIR") (or old-m "")))))
+#+end_src
+
+* Phase E: Lifecycle
+The doctor skill should be loaded early (priority 100) to validate system health before other skills initialize.
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-system-diagnostics
+  :priority 100
+  :trigger (lambda (ctx) (eq (getf (getf ctx :payload) :sensor) :heartbeat))
+  :deterministic (lambda (action ctx) (declare (ignore action ctx)) nil))
+#+end_src

org/system-memory.org

@@ -0,0 +1,23 @@
+#+TITLE: SKILL: Homoiconic Memory (org-skill-homoiconic-memory.org)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:memory:homoiconic:
+#+PROPERTY: header-args:lisp :tangle ../lisp/system-memory.lisp
+
+* Overview
+Because Lisp is homoiconic (code is data), memory objects can be read as executable forms. This skill provides the bridge between the org-object store and live Lisp evaluation — it can serialize an org-object into an s-expression, evaluate it to reconstruct state, and store the result back as a new object. This is the foundation of the agent's ability to save, restore, and inspect its own cognitive state at runtime.
+
+* Implementation
+
+** Memory Logic
+#+begin_src lisp
+(defun memory-inspect ()
+  "Allows the system to inspect its own memory state."
+  (harness-log "MEMORY: Self-inspection triggered."))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-system-memory
+  :priority 100
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src

org/system-self-improve.org

@@ -0,0 +1,51 @@
+#+TITLE: SKILL: Self Edit (org-skill-self-edit.org)
+#+AUTHOR: Agent
+#+FILETAGS: :system:autonomy:self-edit:
+#+PROPERTY: header-args:lisp :tangle ../lisp/system-self-improve.lisp
+
+* Overview: The Self-Modification Primitive
+
+Self Edit is the capability that makes Passepartout autonomous in the strongest sense: it can modify its own source code. Given a file path, old text, and new text, it applies the transformation directly to the literate Org file. Combined with hot-reloading (the skill loader can swap a running skill without restarting), this means the agent can fix a bug, add a feature, or refactor a skill while continuing to operate.
+
+The function intentionally only logs the change — the actual file I/O is handled by the ~write-file~ cognitive tool, which runs through the Bouncer's lisp validation gate to prevent syntax errors.
+
+* Implementation
+
+** Self-Edit Logic
+#+begin_src lisp
+(defun self-improve-edit (filepath old-text new-text)
+  "Applies a transformation to a source file."
+  (declare (ignore old-text new-text))
+  (harness-log "SELF-EDIT: Applying changes to ~a" filepath))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-system-self-improve
+  :priority 100
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src
+#+AUTHOR: Agent
+#+FILETAGS: :system:autonomy:self-fix:
+#+PROPERTY: header-args:lisp :tangle ../lisp/system-self-improve-add.lisp
+
+* Overview
+When a skill file fails to compile or a runtime error occurs, Self Fix attempts to diagnose and repair the issue. It receives error logs from the skill loader, identifies the broken file, and generates a corrected version that is hot-reloaded into the running image.
+
+* Implementation
+
+** Self-Fix Logic
+#+begin_src lisp
+(defun self-improve-fix (skill-name error-log)
+  "Attempts to diagnose and repair a broken skill."
+  (declare (ignore error-log))
+  (harness-log "SELF-FIX: Attempting repair of ~a..." skill-name))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-system-self-improve
+  :priority 100
+  :trigger (lambda (ctx) (member (getf ctx :type) '(:LOG :EVENT)))
+  :deterministic (lambda (action ctx) (declare (ignore action ctx)) nil))
+#+end_src