Move config/test/models to daemon TCP protocol, TUI uses .env fallback

- Daemon: add handle-client-config inline handler for :config-get,
  :config-set, :config-list, :provider-test, :provider-models
- TUI cmd-config: write .env directly, send reload to daemon if connected
- TUI: /config test and /config models send TCP to daemon (fallback:
  daemon-not-running message)
- Add Test Provider and Discover Models to Ctrl+P daemon commands

.env.example

@@ -1,50 +1,96 @@
-# opencortex: Neural Engine Configuration
-# Core LLM Providers
-LLAMACPP_ENDPOINT="http://localhost:8080"
-GEMINI_API_KEY="your_gemini_key_here"
-ANTHROPIC_API_KEY="your_anthropic_key_here"
-OPENAI_API_KEY="your_openai_key_here"
-GROQ_API_KEY="your_groq_key_here"
+# passepartout: Environment Configuration Template
+# Copy this to .env and fill in your values
+
+# =============================================================================
+# IDENTITY
+# =============================================================================
+MEMEX_USER="YourName"
+MEMEX_ASSISTANT="AgentName"
+
+# =============================================================================
+# LLM PROVIDERS (OpenRouter recommended as primary)
+# =============================================================================
 OPENROUTER_API_KEY="your_openrouter_key_here"
+OPENAI_API_KEY="your_openai_key_here"
+ANTHROPIC_API_KEY="your_anthropic_key_here"
+GROQ_API_KEY="your_groq_api_key_here"
+GEMINI_API_KEY="your_gemini_key_here"
+DEEPSEEK_API_KEY="your_deepseek_key_here"
+NVIDIA_API_KEY="your_nvidia_nim_key_here"
 
-# Legacy/Default (Optional)
-LLM_API_KEY="your_api_key_here"
-LLM_ENDPOINT="https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent"
+# Cascade order (first available provider wins)
+# Default (if unset): openrouter,openai,anthropic,groq,gemini-api,deepseek,nvidia
+PROVIDER_CASCADE=deepseek,openrouter,openai,anthropic,groq,gemini,nvidia
 
-# Communication Gateways
+# =============================================================================
+# LOCAL LLM (generic OpenAI-compatible endpoint)
+# =============================================================================
+# Set this to the base URL of any local OpenAI-compatible server
+# (llama.cpp, Ollama, vLLM, LM Studio, etc.)
+LOCAL_BASE_URL="localhost:8080"
+
+# Ollama host (legacy: falls back to LOCAL_BASE_URL if not set)
+OLLAMA_HOST="localhost:11434"
+
+# =============================================================================
+# VECTOR EMBEDDINGS (semantic search)
+# =============================================================================
+EMBEDDING_PROVIDER="hashing"  # "hashing" (local, no deps), "local", or "openai"
+EMBEDDING_MODEL="nomic-embed-text"  # model name for embeddings
+EMBEDDING_BASE_URL="https://api.openai.com/v1"  # for :openai provider
+
+# =============================================================================
+# MESSAGING GATEWAYS (optional)
+# =============================================================================
 TELEGRAM_BOT_TOKEN="your_telegram_bot_token_here"
 SIGNAL_ACCOUNT_NUMBER="+1..."
 
-# System 2: Symbolic Constraints
-SAFETY_BLOCK_SHELL=true
-GTD_ENFORCE_INTEGRITY=true
-
-# Harness Protocol Daemon Configuration
+# =============================================================================
+# DAEMON CONFIGURATION
+# =============================================================================
 ORG_AGENT_DAEMON_PORT=9105
-ORG_AGENT_WEB_PORT=8080
 DAEMON_HOST="0.0.0.0"
 HEARTBEAT_INTERVAL=60
 DAEMON_SLEEP_INTERVAL=3600
-
-# Outbound Communication Defaults
 DEFAULT_ACTUATOR="cli"
 SILENT_ACTUATORS="cli,system-message,emacs"
 
-# Core Skill Requirements
-# A comma-separated list of skill Org files (without extension) required for boot.
-MANDATORY_SKILLS="org-skill-policy,org-skill-bouncer"
+# =============================================================================
+# SECURITY
+# =============================================================================
+PROTOCOL_ENFORCE_HMAC=false
+PROTOCOL_HMAC_SECRET="change-this-to-a-secure-random-string"
 
-# Context Management & Peripheral Vision
+# Privacy filter tags: comma-separated list of tags that mark content as private.
+# Files/headings tagged with any of these will be filtered from LLM context.
+# Default: @personal
+PRIVACY_FILTER_TAGS="@personal,@health,@finance"
+
+# =============================================================================
+# DISPATCHER RULE LEARNING
+# =============================================================================
+# Number of HITL approvals before a pattern becomes a permanent rule
+DISPATCHER_RULE_THRESHOLD=3
+
+# Where learned rules are persisted
+RULES_FILE="$HOME/memex/system/rules.org"
+
+# =============================================================================
+# BOOTSTRAP
+# =============================================================================
+MANDATORY_SKILLS="security-policy,security-dispatcher"
+
+# =============================================================================
+# CONTEXT / MEMORY
+# =============================================================================
 CONTEXT_SEMANTIC_THRESHOLD=0.75
 CONTEXT_LOG_LIMIT=20
 
-# Memex Integration
-# Inside Docker, /app/ is the root for consolidated notes
+# =============================================================================
+# MEMEX STRUCTURE
+# =============================================================================
 MEMEX_DIR="$HOME/memex"
 ZETTELKASTEN_DIR="$HOME/memex/notes"
-SKILLS_DIR="skills/"
-
-# PARA Structure (Consolidated)
 INBOX_DIR="$HOME/memex/inbox"
 DAILY_DIR="$HOME/memex/daily"
 PROJECTS_DIR="$HOME/memex/projects"
@@ -52,15 +98,25 @@ AREAS_DIR="$HOME/memex/areas"
 RESOURCES_DIR="$HOME/memex/resources"
 ARCHIVES_DIR="$HOME/memex/archives"
 SYSTEM_DIR="$HOME/memex/system"
+LLM_REQUEST_TIMEOUT=30
 
-# Identity Configuration
-MEMEX_USER="YourName"
-MEMEX_ASSISTANT="AgentName"
-RECIPIENT_ID="+1..." # For Signal/Telegram delivery
+# =============================================================================
+# TOKEN ECONOMICS (v0.5.0)
+# =============================================================================
+# Max tokens for the combined system prompt + context + user prompt.
+# Default: 16384 (half of a 32K context window, leaves room for model response).
+CONTEXT_MAX_TOKENS=16384
 
-# Harness Protocol Integrity & Authentication (HMAC-SHA256)
-PROTOCOL_ENFORCE_HMAC=false
-PROTOCOL_HMAC_SECRET="change-this-to-a-secure-random-string"
+# Soft daily cost cap in USD. Warning injected into system prompt when
+# approaching budget.
+COST_BUDGET_DAILY=1.00
 
-# Neural Reasoning Cascade Order (Comma-separated keywords)
-PROVIDER_CASCADE="openrouter,openai,anthropic,groq,gemini-api,ollama"
+# v0.7.2: Privacy tag severity tiers. Format: @tag:block,@tag:warn,@tag:log
+# :block = filter content, :warn = log+allow, :log = silently record
+# Default: empty (no tags configured)
+#TAG_CATEGORIES=@personal:block,@financial:block,@draft:warn
+
+# v0.7.2: Self-build core file protection mode
+# When true, writes to core-*.org and core-*.lisp require HITL approval.
+# Default: false (unrestricted — use during development)
+SELF_BUILD_MODE=false

.gitea/workflows/deploy.yml

@@ -1,44 +1,24 @@
-name: Deploy-Agent-V15-Stdin
+name: Deploy (Gitea)
+
 on:
   push:
     branches:
       - main
 
 jobs:
-  JOB-V15-STDIN:
+  deploy:
     runs-on: debian-latest
     steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
+      - name: Checkout
+        uses: actions/checkout@v4
 
       - name: Install Docker CLI
         run: |
-          echo "Installing Docker CLI..."
-          apt-get update
-          apt-get install -y docker.io docker-compose
+          apt-get update && apt-get install -y docker.io docker-compose
 
-      - name: Deploy via Host Docker Socket (Stdin Method)
+      - name: Build and deploy via Docker Compose
         run: |
-          echo "Piping local compose file to host Docker daemon..."
-          
-          # We read the compose file from the checked-out code in the runner,
-          # but we tell the host Docker daemon that the "project directory" is /memex/projects/opencortex.
-          # The host daemon will use its own /memex files to build the image.
-          
-          cat deploy/docker/docker-compose.yml | docker-compose \
-            -p opencortex \
-            --project-directory /memex/projects/opencortex \
-            -f - \
-            down
-            
-          cat deploy/docker/docker-compose.yml | docker-compose \
-            -p opencortex \
-            --project-directory /memex/projects/opencortex \
-            -f - \
-            build --no-cache opencortex
-            
-          cat deploy/docker/docker-compose.yml | docker-compose \
-            -p opencortex \
-            --project-directory /memex/projects/opencortex \
-            -f - \
-            up -d --force-recreate opencortex
+          cd infrastructure/docker
+          docker-compose -p passepartout down
+          docker-compose -p passepartout build --no-cache passepartout
+          docker-compose -p passepartout up -d --force-recreate passepartout

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,25 @@
+name: Bug Report
+
+about: Report something that is not working as expected.
+
+---
+
+**Describe the bug**
+A clear description of what went wrong.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Run '...'
+3. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment:**
+- OS: [e.g. Debian 12, macOS 14]
+- SBCL version: [e.g. 2.4.0]
+- OpenCortex version: [e.g. v0.1.0]
+
+**Additional context**
+Any other relevant information (logs, stack traces, etc.)

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature Request
+
+about: Suggest a new feature or enhancement.
+
+---
+
+**Describe the problem**
+What problem does this feature solve?
+
+**Describe the ideal solution**
+A clear description of what you want to happen.
+
+**Describe alternatives considered**
+Any alternative solutions you've considered.
+
+**Additional context**
+Any other relevant context (mockups, related issues, etc.)
+
+**Implementation suggestion**
+(Optional) If you have thoughts on how to implement this in pure Common Lisp + Org-mode:
+- Which skill should own this?
+- Should it be a =def-cognitive-tool=, a new skill, or an enhancement to an existing one?

.github/workflows/lint.yml

@@ -0,0 +1,74 @@
+name: Lint
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends \
+            git emacs-nox
+
+      - name: Check for forbidden patterns
+        run: |
+          ! grep -r "json\." --include="*.lisp" lisp/ && \
+            echo "OK: No JSON in Lisp files"
+
+      - name: Check org files have lisp source blocks
+        run: |
+          FAIL=0
+          for f in org/*.org; do
+            if ! grep -q "#+begin_src lisp" "$f"; then
+              echo "WARNING: $f has no lisp blocks"
+              FAIL=1
+            fi
+          done
+          echo "OK: Org files checked for lisp blocks"
+
+      - name: Verify each .lisp has a corresponding .org source
+        run: |
+          FAIL=0
+          for f in lisp/*.lisp; do
+            [ -f "$f" ] || continue
+            base=$(basename "$f" .lisp)
+            if [ -f "org/${base}.org" ]; then
+              : # direct match
+            else
+              # Check if generated from a parent org via :tangle header
+              if grep -q ":tangle.*$(basename "$f")" org/*.org 2>/dev/null; then
+                : # :tangle reference found
+              else
+                echo "WARNING: $f has no corresponding .org source"
+                FAIL=1
+              fi
+            fi
+          done
+          [ "$FAIL" = 0 ] && echo "OK: All .lisp files have .org sources"
+
+      - name: Check literate granularity (one function per block)
+        run: |
+          for f in org/*.org; do
+            blocks=$(grep -c "^[[:space:]]*(defun " "$f" 2>/dev/null || true)
+            srcblocks=$(grep -c "#+begin_src lisp" "$f" 2>/dev/null || true)
+            if [ "$blocks" -gt "$srcblocks" ] && [ "$srcblocks" -gt 0 ]; then
+              echo "WARNING: $f has $blocks defuns but only $srcblocks src blocks"
+            fi
+          done
+          echo "OK: Granularity check complete"
+
+      - name: Check README has quick install
+        run: |
+          grep -q "curl.*passepartout" README.org && \
+            echo "OK: Quick install in README" || \
+            echo "WARNING: Quick install curl command not found in README"

.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create tarball
+        run: |
+          git archive --format=tar.gz --prefix=passepartout-$(git describe --tags) HEAD -o passepartout.tar.gz
+
+      - name: Create zipball
+        run: |
+          git archive --format=zip --prefix=passepartout-$(git describe --tags) HEAD -o passepartout.zip
+
+      - name: Extract tag message as release notes
+        run: |
+          git tag -l --format='%(contents)' ${GITHUB_REF#refs/tags/} > /tmp/release-notes.md
+          echo "--- Notes preview ---"
+          head -20 /tmp/release-notes.md
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            passepartout.tar.gz
+            passepartout.zip
+          body_path: /tmp/release-notes.md
+          generate_release_notes: true

.github/workflows/test.yml

@@ -0,0 +1,92 @@
+name: Tests
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends \
+            sbcl emacs-nox git curl socat rlwrap
+
+      - name: Install Quicklisp
+        run: |
+          curl -fsSL https://beta.quicklisp.org/quicklisp.lisp -o /tmp/quicklisp.lisp
+          sbcl --noinform --non-interactive \
+            --load /tmp/quicklisp.lisp \
+            --eval '(quicklisp-quickstart:install)'
+          rm -f /tmp/quicklisp.lisp
+          sbcl --noinform --non-interactive \
+            --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' \
+            --eval '(ql:quickload :fiveam :silent t)' \
+            --eval '(quit)'
+
+      - name: Load and verify system
+        run: |
+          export PASSEPARTOUT_DATA_DIR="$PWD/.github-test"
+          mkdir -p "$PASSEPARTOUT_DATA_DIR/org" "$PASSEPARTOUT_DATA_DIR/lisp" "$PASSEPARTOUT_DATA_DIR/test"
+
+          # Tangle org files into lisp/
+          cp org/*.org "$PASSEPARTOUT_DATA_DIR/org/"
+          cd "$PASSEPARTOUT_DATA_DIR/org" && for f in *.org; do
+            if command -v emacs; then
+              emacs -Q --batch --eval "(require 'org)" \
+                --eval "(setq org-confirm-babel-evaluate nil)" \
+                --eval "(org-babel-tangle-file \"$f\")" 2>/dev/null || true
+            fi
+          done
+          rm -f *.org
+          cd "$OLDPWD"
+
+          # Move test files to test/
+          find "$PASSEPARTOUT_DATA_DIR/lisp" -name "*-tests.lisp" -exec mv {} "$PASSEPARTOUT_DATA_DIR/test/" \; 2>/dev/null || true
+
+      - name: Load passepartout and initialize skills
+        run: |
+          export PASSEPARTOUT_DATA_DIR="$PWD/.github-test"
+          sbcl --non-interactive \
+            --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' \
+            --eval "(push (truename \"$PWD/\") asdf:*central-registry*)" \
+            --eval "(push (truename \"$PASSEPARTOUT_DATA_DIR/\") asdf:*central-registry*)" \
+            --eval '(ql:quickload :passepartout :silent t)' \
+            --eval "(setf (uiop:getenv \"PASSEPARTOUT_DATA_DIR\") \"$PASSEPARTOUT_DATA_DIR\")" \
+            --eval '(passepartout:skill-initialize-all)' \
+            --eval "(let ((n (hash-table-count passepartout:*skill-registry*))) (format t \"~%Skills loaded: ~a~%\" n) (unless (>= n 10) (sb-ext:exit :code 1)))"
+
+      - name: Daemon smoke test
+        run: |
+          export PASSEPARTOUT_DATA_DIR="$PWD/.github-test"
+          sbcl --non-interactive \
+            --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' \
+            --eval "(push (truename \"$PWD/\") asdf:*central-registry*)" \
+            --eval "(push (truename \"$PASSEPARTOUT_DATA_DIR/\") asdf:*central-registry*)" \
+            --eval '(ql:quickload :passepartout :silent t)' \
+            --eval "(setf (uiop:getenv \"PASSEPARTOUT_DATA_DIR\") \"$PASSEPARTOUT_DATA_DIR\")" \
+            --eval '(passepartout:main)' \
+            > /tmp/passepartout-daemon.log 2>&1 &
+          DAEMON_PID=$!
+
+          for i in $(seq 1 20); do
+            if ss -tln 2>/dev/null | grep -q 9105; then
+              echo "✓ Daemon ready on port 9105"
+              timeout 3 bash -c 'exec 3<>/dev/tcp/localhost/9105; head -c 200 <&3' 2>/dev/null | grep -q "handshake" && \
+                echo "✓ Protocol handshake received"
+              break
+            fi
+            sleep 1
+          done
+
+          kill $DAEMON_PID 2>/dev/null || true
+          wait $DAEMON_PID 2>/dev/null || true
+          echo "✓ Daemon smoke test passed"

.gitignore

@@ -1,8 +1,16 @@
 .env
-opencortex-server
+passepartout-server
 \$MEMEX_DIR/
 *.log
 *~
 \#*#
-opencortex-tui
+passepartout-tui
 test_input.txt
+
+# Generated artifacts (source of truth is .org)
+/skills/*.lisp
+/tmp/*.lisp
+*.fasl
+docs/#DESIGN_DECISIONS.org# docs/DESIGN_DECISIONS.org~
+extras/*.elc
+state/

Dockerfile

@@ -1,71 +0,0 @@
-# OPENCORTEX v1.0 Production Environment
-FROM debian:bookworm-slim
-
-# Prevent interactive prompts during build
-ENV DEBIAN_FRONTEND=noninteractive
-
-# 1. Install System Dependencies
-# - sbcl: The Lisp Runtime
-# - curl/git/unzip: Standard tools for Quicklisp and binaries
-# - default-jre: Required by signal-cli
-# - python3/pip: Required for Playwright bridge
-# - socat: Required for stateful CLI interaction
-RUN apt-get update && apt-get install -y \
-    sbcl \
-    curl \
-    git \
-    unzip \
-    default-jre \
-    libsqlite3-0 \
-    python3 \
-    python3-pip \
-    python3-venv \
-    emacs-nox \
-    socat \
-    && rm -rf /var/lib/apt/lists/*
-
-# 2. Setup Playwright (High-Fidelity Browsing)
-RUN python3 -m venv /opt/venv
-ENV PATH="/opt/venv/bin:$PATH"
-RUN pip install playwright \
-    && playwright install --with-deps chromium
-
-# 3. Install signal-cli (v0.14.0)
-ENV SIGNAL_CLI_VERSION=0.14.0
-RUN curl -L https://github.com/AsamK/signal-cli/releases/download/v${SIGNAL_CLI_VERSION}/signal-cli-${SIGNAL_CLI_VERSION}-Linux.tar.gz | tar xz -C /opt \
-    && ln -s /opt/signal-cli-${SIGNAL_CLI_VERSION}/bin/signal-cli /usr/local/bin/signal-cli
-
-# 4. Install Quicklisp & Pin Distribution
-# Pinned to 2026-04-01 for bit-rot resistance.
-WORKDIR /root
-RUN curl -O https://beta.quicklisp.org/quicklisp.lisp \
-    && sbcl --non-interactive \
-        --load quicklisp.lisp \
-        --eval '(quicklisp-quickstart:install)' \
-        --eval '(ql-dist:install-dist "http://beta.quicklisp.org/dist/quicklisp/2026-04-01/distinfo.txt" :prompt nil :replace t)'
-
-# 5. Configure SBCL to load Quicklisp on startup
-RUN echo '(let ((quicklisp-init (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))) (when (probe-file quicklisp-init) (load quicklisp-init)))' > /root/.sbclrc
-
-# 6. Setup Application Directory
-WORKDIR /app
-COPY . /app/projects/opencortex
-
-# 7. Pre-cache Lisp Dependencies
-RUN sbcl --non-interactive \
-    --eval '(push #p"/app/projects/opencortex/" asdf:*central-registry*)' \
-    --eval '(ql:quickload :opencortex)'
-
-# 8. Environment & Volumes
-# The host's memex root should be mounted to /memex
-ENV MEMEX_DIR=/memex
-VOLUME ["/memex"]
-
-# Default Ports
-EXPOSE 9105 8080
-
-# Entrypoint
-CMD ["sbcl", "--non-interactive", \
-     "--eval", "(push #p\"/app/projects/opencortex/\" asdf:*central-registry*)", \
-     "--eval", "(ql:quickload :opencortex)", \
-     "--eval", "(opencortex:main)"]

README.org

@@ -1,144 +1,163 @@
-#+TITLE: OpenCortex: The Conductor of your Life Stack
+#+TITLE: Passepartout — The Plain-Text AI Assistant That Never Gets More Expensive
+#+AUTHOR: Amr
+#+FILETAGS: :passepartout:ai:assistant:
 
-*opencortex* is a minimalist, extensible AI agent framework designed to manage and continuously organize your personal knowledge base. It transforms a static collection of plaintext notes into a live, programmable [[https://en.wikipedia.org/wiki/Memex][Memex]]—an automated, personalized memory system where humans and AI collaborate in the exact same workspace.
+#+HTML: <div style="display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 1em;">
+#+HTML: <img src="https://img.shields.io/badge/version-v0.7.2-blue?style=flat-square">
+#+HTML: <img src="https://img.shields.io/badge/license-AGPLv3-green?style=flat-square">
+#+HTML: <img src="https://img.shields.io/badge/Lisp-Common%20Lisp-forestgreen?style=flat-square">
+#+HTML: <img src="https://img.shields.io/badge/docs-Org--mode-darkgreen?style=flat-square">
+#+HTML: </div>
 
-* The Problem with Current AI Agents
+Passepartout is an AI assistant that runs in your terminal. It reads and writes your Org-mode files, executes tasks through a verified safety gate, and works fully offline with local LLMs. Every action the LLM proposes is checked by ten deterministic safety gates before it touches a file, runs a command, or sends a message. The LLM suggests. The gate decides.
+Everything it knows is a folder of plain text files that you own.
 
-The current ecosystem of AI agents (typically built in Python or TypeScript) is overwhelmingly built on architectural choices that prioritize rapid prototyping over long-term reliability, security, and self-modification:
-
-1. *The Format Trap (Markdown & JSON):* Most agents force a painful translation layer. Humans write in Markdown, which lacks a strict Abstract Syntax Tree (AST)—a rigorous, nested representation of data that machines need to parse context reliably. Machines, in turn, output JSON or YAML, which are hostile formats for human thought and note-taking. The result is a fractured workspace where the agent's memory and the human's memory are fundamentally incompatible. Furthermore, because Markdown cannot be efficiently collapsed, agents are forced to consume massive amounts of tokens by reading entire files just to find a single paragraph.
-2. *The Language Trap (Python & TypeScript):* Python and TypeScript are fantastic for gluing together APIs or training models, but they are poorly suited for an agent that needs to safely read, write, and execute its own code at runtime. Their underlying structures are complex and opaque, making autonomous self-editing incredibly brittle and dangerous.
-3. *The Probabilistic Trap:* Almost all modern agents rely entirely on /probabilistic/ reasoning. We ask an AI model to guess a shell command or write a Python script, and then blindly pipe that output to a terminal. Without a rigorous, /deterministic/ layer to formally verify the model's proposals before execution, these systems are fundamentally unsafe. 
-
-* The Vision: A Modern, Homoiconic Memex
-
-opencortex abandons these fragile paradigms by returning to first principles and embracing two historically powerful technologies: *Org-mode* and *Common Lisp*. 
-
-** 1. Org-mode: The Universal Language
-Instead of wrestling with Markdown parsers or hiding data in opaque databases, opencortex mandates that *Org-mode is the native AST for both humans and machines.* 
-
-Org-mode is unique because it seamlessly brings together human-readable prose, structured metadata (properties and tags), lifecycle states (TODO/DONE), and executable code blocks into a single plain-text file. The code is the data, and the data is the interface. When the agent "remembers" a fact or schedules a task, it writes an Org headline. You read exactly what the agent reads.
-
-*The Token Advantage:* Because Org-mode is a strict outline, opencortex never needs to send an entire document to an AI model. It uses *Sparse Trees* to send a high-level table of contents, zooming in only on the specific headline relevant to the task. This drastically reduces token consumption and eliminates context window overflow.
-
-** 2. Common Lisp: The Engine of Self-Modification
-There is a beautiful irony to opencortex: Lisp was invented in 1958 specifically to achieve Artificial Intelligence, and it has been waiting nearly 70 years for /this exact moment/ in computing history. 
-
-Lisp possesses a unique property called *Homoiconicity*: the primary representation of the program is also a data structure (nested lists) within the language itself. Because Lisp code /is/ Lisp data, it is trivially easy for an AI to generate, manipulate, and safely evaluate new tools at runtime. This makes Lisp the ultimate, un-brittle language for a "self-writing" agent.
-
-** 3. The Probabilistic-Protodeterministic Loop
-opencortex does not let AI models touch your system directly. Instead, it splits cognition into two distinct engines:
-- *The Probabilistic Engine (The AI Models):* Provides semantic understanding, multimodal translation, and probabilistic creativity. It looks at your Memex and proposes an action by writing a strictly formatted Lisp s-expression.
-- *The Deterministic Engine (Common Lisp):* Provides deterministic logic, physics, and safety. It intercepts the model's Lisp proposal, formally verifies its structure against your security rules, and only executes it if it is mathematically sound.
-
-Crucially, the Deterministic engine is *continuously progressive*. Right now, it starts by acting as a strict security bouncer—enforcing rules and bounding the AI's actions. But as the system matures, the Deterministic engine will progressively take over more and more of the actual reasoning, reducing the AI models' involvement to a mere semantic translation layer for the messy outside world. We are moving from a /probabilistic-protodeterministic/ system today, toward a fully autonomous /probabilistic-deterministic/ Lisp machine tomorrow.
-
-* Architecture: Thin Harness, Fat Skills
-
-To guarantee long-term stability, opencortex enforces a strict architectural boundary inspired by the "thin harness, fat skills" philosophy.
-
-** The Minimalist Harness
-The Lisp microkernel does almost no actual "work." It is a thin, unbreakable harness strictly responsible for three things:
-1. *The Memory:* Maintaining the live graph of your Memex in RAM.
-2. *The Communication Protocol:* Managing the secure bridge between the agent and the outside world. While power users can connect natively via Emacs or Vim, the vast majority of users will interact with opencortex exclusively through chat clients (like Telegram, Signal, or Matrix), web dashboards, or a Terminal UI (TUI). The harness doesn't care; it just securely routes the messages.
-3. *The Cognitive Cycle:* Moving signals through the Perceive -> Probabilistic -> Deterministic -> Dispatch pipeline.
-
-Everything else—AI routing, vector embeddings, shell execution, or web browsing—is pushed entirely out of the harness and into *Fat Skills*.
-
-** Literate, Single-File Skills
-In standard agent frameworks, adding a new capability (like "Search the Web") requires creating a sprawling folder with a Python script, a JSON configuration file, and a separate text file for the AI prompt. This creates massive structural bloat.
-
-In opencortex, a Skill is simply a *single .org file*. 
-
-Using *Literate Programming*, this single file contains everything:
-- The human-readable documentation and architectural intent.
-- The system prompt instructions for the Probabilistic Engine.
-- The deterministic Lisp code for the Deterministic engine's safety checks.
-- The actual execution logic.
-
-When the system boots, it parses these single files, mathematically proves their dependencies, and compiles them directly into the live Lisp image.
-
-** The Anatomy: Three Data Stores
-The agent's "mind" is not a transient chat session; it is a durable, stateful architecture consisting of three layers:
-1. *The Linguistic Substrate (Plaintext Files):* The human-readable Source of Truth on your hard drive. You can edit these files in any text editor, and the agent will instantly perceive the changes.
-2. *The Lisp Memory (RAM):* The "Active Brain," a live, threaded graph of Lisp objects representing every headline, paragraph, and tag in your Memex. It allows the agent to navigate your life instantly without constantly re-reading files.
-3. *The Telemetry Store (External):* A high-volume database for sub-deterministic sensory data (e.g., smart home logs or system metrics), which the agent monitors and distills.
-
-** The Psychology: The 2x2 Cognitive Matrix
-The agent operates on a matrix that balances cognitive speed with cognitive state:
-
-| | Probabilistic (Neural/Intuitive) | Deterministic (Deterministic/Logical) |
-| :--- | :--- | :--- |
-| Foreground (Active) | *The Interface:* Fast AI models for conversation, multimodal ingestion, and semantic understanding. | *The Steward:* Lisp engine that safely retrieves requested data from the Memex and enforces security rules while the Interface keeps you engaged. |
-| Background (Passive) | *The Editor:* Deep AI models finding hidden patterns while you sleep. | *The Librarian:* Lisp engine continuously maintaining data integrity and filing away loose notes. |
-
-** The Physiology: Five Core Processes
-1. *Perception:* Automatically vectorizes your input and sets the "Foreground Focus" so the agent knows exactly what you are looking at or talking about.
-2. *Reasoning:* Uses Lisp-native logic to reconcile contradictions and enforce the physics of the Memex.
-3. *Distillation:* A Background loop that reads your chronological daily logs and automatically extracts concepts into permanent, evergreen notes.
-4. *Reflection:* A heartbeat-driven process that finds forgotten links and maintains the structural health of the system.
-5. *Sensation:* A converter that monitors the raw flood of telemetry data and turns significant anomalies into actionable TODO items on your list.
-
-* The Ecosystem: Core Skill Groups
-
-Because the harness is deliberately thin, every capability of opencortex is implemented as a single-file Literate Skill. This allows you to hot-reload, modify, or completely remove features on the fly without restarting the core environment. 
-
-The ecosystem is divided into five primary skill groups:
-
-** 1. Gateways (How you talk to the agent)
-The agent meets you where you are. While it natively integrates with text editors, it features standalone gateway skills for modern interfaces. 
-- *Chat Gateways:* Interact securely from your phone via clients like Matrix, Signal, or Telegram.
-- *Web & TUI Dashboards:* High-level visual overviews of your agent's background processes and telemetry.
-
-** 2. Cognition & Memory (How the agent thinks)
-- *Model Routing:* Dynamically routes requests to the best available Probabilistic model (e.g., Anthropic, OpenAI, Local Llama) based on task complexity or privacy needs.
-- *Peripheral Vision & Embeddings:* Manages the vectorization of your notes, ensuring the agent retrieves semantically relevant context via sparse trees.
-- *The Ontology Scribe:* Centralizes all rules regarding Org, GTD, and Org-Roam parsing into a single background subroutine, eliminating parser confusion across the codebase.
-
-** 3. Actuators (How the agent affects the world)
-- *The Shell Actuator:* Safely executes whitelisted terminal commands to interact with the host OS.
-- *The Playwright Bridge:* Grants the agent the ability to spin up a headless browser, navigate the web, read documentation, and interact with web applications.
-
-** 4. Security & Alignment (How the agent stays safe)
-- *Formal Verification:* The mathematical gatekeeper that proves a proposed action is safe (e.g., ensuring file writes are confined strictly to your Memex directory) before execution.
-- *The Credentials Vault:* A secure, masked enclave that prevents AI models from ever reading your raw API keys or .env files.
-
-** 5. Background Subroutines (The Autonomous Workers)
-- *The Journal Scribe:* Periodically distills messy chronological logs into clean, permanent notes.
-- *The Gardener:* A heartbeat-driven worker that flags broken links, finds orphaned ideas, and maintains the structural health of your Memex.
-
-* Quick Start (The Zero-to-One Experience)
-
-opencortex can be installed and booted with a single command. The unified entrypoint script will detect your OS, offer to install Docker if missing, interactively gather your API keys, and launch the autonomous kernel in the background.
+*Install:*
 
 #+begin_src bash
-curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash
+curl -fsSL https://raw.githubusercontent.com/amrgharbeia/passepartout/main/passepartout | bash -s configure
 #+end_src
 
-After installation, simply type `opencortex` in your terminal to start chatting with your autonomous brain.
+This installs dependencies (SBCL, Quicklisp), tangles the Org source files, and runs the setup wizard for LLM providers. Requires curl and sudo access for package installation.
 
-For power users who wish to run the agent natively (Baremetal), please refer to the [[file:literate/setup.org][setup.org]] literate documentation.
+* What is an AI Agent?
 
-* The Evolutionary Roadmap (v0.1.0 to v4.0.0+)
+An AI agent is a program that can act on your behalf — reading files, running commands, sending messages — rather than just answering questions. Unlike a chatbot that only produces text, an agent has /actuators/ that let it affect the world: a shell, a file editor, a message sender. See [[https://en.wikipedia.org/wiki/Software_agent][Software agent]] on Wikipedia.
 
-** v0.1.0: The Autonomous Foundation (Current Release)
-The initial MVP that establishes a secure, auditable Lisp kernel for a personal operating system. It features a robust metabolic pipeline, mandatory skill enforcement, and background distillation.
+Passepartout is a /sovereign/ agent: it runs on your machine, operates on your plain-text files, and verifies every action through deterministic safety gates before execution.
 
-** v1.0.0 (Phase 2.5): The Verified Wrapper (Current Target)
-At this stage, opencortex achieves feature parity with State-of-the-Art autonomous agents (like Devin or SWE-agent) but with Lisp-grade mathematical security.
-- *The Tools are External:* The agent uses a standard bash shell, a headless browser (via Playwright), and standard file I/O.
-- *The Safety is Internal:* The Bouncer and Formal Verification gates mathematically prove actions are safe before piping them to external tools.
-- *The Result:* An autonomous agent capable of end-to-end software engineering, web research, and system administration, running securely and locally.
+* What Makes Passepartout Different
 
-** v2.0.0 (Phase 3): The Cannibalization
-Replacing string-based tool wrappers with native Lisp data structures to eliminate LLM fragility.
-- *Cannibalizing the Browser:* Ingesting the DOM as a native Lisp AST rather than fighting with Playwright scripts.
-- *Cannibalizing the Shell & Editor:* Moving from bash execution to native OS API bindings. Emacs becomes a viewport for the live AST, not a master.
-- *The Result:* The LLM no longer has to guess at messy `stdout` or raw HTML strings; it manipulates deterministic data structures directly.
+** Every action is verified, not trusted.
 
-** v3.0.0 (Phase 4): True Symbolic Determinism
-The great inversion. The Lisp engine takes the wheel, and the LLM is relegated to translation.
-- *The Semantic Translator:* The LLM exclusively translates unstructured human intent (natural language, images) into strict Lisp S-expressions.
-- *Deterministic Planning (The Solver):* The core reasoning engine uses formal logic, graph traversal, and constraint solving to plan and execute workflows.
-- *Self-Correcting Syntax:* The Lisp engine catches and repairs hallucinated syntax errors without consulting the LLM.
+Most AI agents add safety checks as an afterthought — prompt-based guardrails that consume LLM tokens and can be evaded with clever phrasing. Passepartout inverts this: ten deterministic safety gates run in pure Lisp between the LLM's proposal and execution. Secret scanning checks for API key leaks. Path protection blocks reads and writes to sensitive files, including a self-build safety boundary that prevents the agent from modifying its own core pipeline without human review. Shell safety detects destructive commands and injection vectors. Network exfiltration detection flags unauthorized outbound connections. Lisp syntax validation catches malformed code before it writes to disk.
 
+Every gate costs 0 LLM tokens. Every gate is a Common Lisp function, not a prompt. Every gate runs for every action, unconditionally.
+
+If a gate blocks a proposal, the rejection feedback goes back to the LLM so it can self-correct and try again. If the deterministic Dispatcher is uncertain, it creates a Flight Plan — a human-readable Org buffer you review and approve. The human decides. The Dispatcher learns from your decision and writes a rule for next time.
+
+** The more you use it, the cheaper it gets (architectural aspiration)
+
+Passepartout is designed with a downward cost curve — an architectural property, not yet measured empirically. Here is the thesis.
+
+When you use Passepartout, the Dispatcher observes every blocked action and every human-approved exception. Each decision becomes a deterministic rule. A file write you approved once becomes an allowed path pattern. A shell command you denied becomes a permanent block. Each hardened rule means one fewer LLM call next time. This rule-learning system is planned for v0.5.0.
+
+Meanwhile, the foveal-peripheral context model prunes your [[https://en.wikipedia.org/wiki/Memex][memex]] — your personal knowledge base, a term coined by Vannevar Bush in 1945 for a mechanised private library — to the relevant Org subtrees before sending anything to the LLM. The agent does not load your entire knowledge base, or even the entire file like agents that use Markdown do — it loads precisely the headlines that matter. Less context in, fewer tokens out.
+
+These mechanisms are implemented and working today. Token cost measurement and optimization are tracked in the [[file:docs/ROADMAP.org][v0.5.0 Roadmap]]. Until empirically verified, the cost claims in [[file:docs/DESIGN_DECISIONS.org][Design Decisions]] (2-3x fewer tokens for coding, 13-24x for knowledge management) should be read as architectural projections, not measured results.
+
+** It edits its own source code. Verified before execution.
+
+Passepartout can read its own Org-mode source files, propose changes, and hot-reload skills into the running image without restarting. The skill engine loads every skill into a jailed Common Lisp package, validates its syntax, tests its trigger function in isolation, and only then promotes it to the live registry.
+
+Core pipeline files — the Perceive-Reason-Act loop, the Merkle-tree memory, the Dispatcher gate stack — are path-protected. The agent could modify its own brain stem, but it cannot do this without human review. Skills and system modules expand freely. The core stays small, protected, and auditable.
+
+No other AI agent can modify its own reasoning engine and reload the change while it is running. This is not a planned feature. It works today.
+
+** Your memory and your tasks are the same format. Org-mode.
+
+Passepartout makes a bet that most systems consider too expensive: humans and machines should share the same file format. That format is Org-mode.
+
+Your notes, your calendar, your project plans, the agent's memory, and the agent's own source code are all the same thing: Org files in ~/memex/. =headline trees. Property drawers for metadata. Source blocks for code. TODO keywords for task state. Tags for categorization.
+
+When you write a TODO in Emacs, the agent sees it immediately as a native data structure and acts on it. When the agent creates a note, you can open it in any text editor and read it. There is no import/export step, no hidden database (except maybe for indexing), no format conversion. If Passepartout stops existing tomorrow, your data survives in plain text, readable in 2040.
+
+** Works offline. Works locally. The safety doesn't stop.
+
+You can run Passepartout entirely on your hardware with a local LLM via Ollama or some other inference engine. No internet connection required. But unlike most local AI tools, offline mode does not mean safety-last. The ten deterministic safety gates are pure Common Lisp — they run identically whether you are online or off. The Merkle-tree memory with snapshot rollback is in-process, 0 milliseconds, 0 network calls. Semantic retrieval runs on in-image vectors, 0 LLM tokens per query.
+
+Cloud providers (OpenRouter, OpenAI, Anthropic, Groq, Gemini, DeepSeek, NVIDIA NIM...) are optional add-ons. When you use them, the model-tier router automatically selects the cheapest provider that matches your task's complexity. Privacy-tagged content stays local even when cloud providers are configured.
+
+* How It Works
+
+Every signal — a chat message, a heartbeat tick, a file change notification — moves through three stages:
+
+#+begin_example
+Signal  →  Perceive  →  Reason  →  Act
+            normalize    LLM proposes  dispatch approved action
+                         gates verify  tool output feeds back
+#+end_example
+
+*Perceive* normalizes raw input from any gateway (TUI, CLI, Telegram, Signal) into a uniform signal plist. Buffer updates from Emacs ingest Org AST nodes into memory. Heartbeat ticks trigger background maintenance. HITL commands intercept before the LLM is invoked.
+
+*Reason* calls the LLM to generate a proposal, then runs the proposal through every registered deterministic gate — sorted by priority, highest first. If a gate rejects (shell command blocked, path protected, secret exposed), the rejection trace feeds back to the LLM for self-correction, up to three retries. If a gate requests human approval, the action becomes a Flight Plan awaiting your decision. If all gates pass, the action proceeds to Act.
+
+*Act* dispatches the approved action to the correct actuator: shell commands go to the shell actuator (with timeout and output limiting), tool invocations go to the cognitive tool registry, system commands trigger internal harness operations, and chat responses route to the TUI or messaging gateway. Each stage can feed back into Perceive — a tool output becomes the next perception.
+
+This pipeline is not a single-threaded bottleneck. The priority-queued signal processor (v0.5.0 roadmap) preempts background maintenance for user interactions. The Merkle-tree memory supports concurrent reads and writes through versioned snapshots — multiple signals can process simultaneously without corrupting shared state.
+
+Deep detail: [[file:docs/ARCHITECTURE.org][Architecture]] for the full code map and pipeline flow, [[file:docs/DESIGN_DECISIONS.org][Design Decisions]] for the rationale behind every architectural choice.
+
+* Current Capabilities
+
+Features marked =Stable= ship in the current release. Features marked =Planned= are scheduled in the [[file:docs/ROADMAP.org][Roadmap]].
+
+| Capability                       | Status   | Since   | Notes                                                                |
+|----------------------------------+----------+---------+----------------------------------------------------------------------|
+| 10-vector deterministic safety   | Stable   | v0.2.0  | Secrets, paths, self-build, shells, network, lisp, privacy, approval |
+| Foveal-peripheral context model | Stable   | v0.2.0  | Sends relevant subtrees, not all files                               |
+| Merkle-tree memory + snapshots   | Stable   | v0.2.0  | Integrity hashing, copy-on-write rollback                            |
+| Self-editing + hot-reload         | Stable   | v0.2.0  | Agent reads, modifies, reloads its own code                          |
+| 8 provider cascade                | Stable   | v0.1.0  | OpenRouter, OpenAI, Anthropic, Groq, Gemini, DeepSeek, NVIDIA, local |
+| Terminal UI (Croatoan)            | Stable   | v0.2.0  | Scrollback, history, themes, commands, tab completion                |
+| Skill engine (20+ skills)         | Stable   | v0.1.0  | Jailed loading, topological sort, hot-reload                         |
+| Human-in-the-Loop approval        | Stable   | v0.3.0  | Flight Plan workflow for blocked actions                             |
+| Model-tier routing                | Stable   | v0.3.0  | Sends simple tasks to cheaper models                                 |
+| Event orchestrator (hooks + cron) | Stable   | v0.3.0  | Org-based hook and cron dispatch                                     |
+| Context manager (project scoping) | Stable   | v0.3.0  | Push/pop focus, persist across restart                               |
+| Semantic retrieval (trigram)      | Stable   | v0.4.0  | Trigram Jaccard — lexical overlap, 0 LLM tokens                      |
+| TUI gate trace + focus map        | Stable   | v0.4.0  | Visual safety trace + what the agent is looking at                   |
+| Emacs bridge                      | Stable   | v0.4.0  | Native Emacs client over the wire protocol                           |
+| Self-build safety boundary        | Stable   | v0.4.0  | Core files path-protected, HITL Flight Plan required                 |
+| Expanded theme (25-color)         | Stable   | v0.4.0  | 4 named presets (dark/light/gruvbox/solarized), /theme command       |
+| Discord + Slack gateways          | Stable   | v0.4.0  | 4 platforms: Telegram, Signal, Discord, Slack                        |
+| Native embedding inference        | Beta     | v0.4.x  | CFFI llama.cpp binding, nomic-embed-text (768-dim)                   |
+| Structured output (function-calling) | Stable | v0.4.2 | LLM tool use via native function-calling API, JSON→plist boundary |
+| Shell sandbox (bwrap)               | Stable | v0.4.3 | Bubblewrap namespace isolation, network/IPC lockdown   |
+| Shell severity classification        | Stable | v0.4.3 | catastrophic→dangerous→moderate→harmless tier system   |
+| Token economics + cost tracking   | Stable   | v0.5.0  | Per-session cost counter, prompt caching, budget enforcement         |
+| Time awareness                    | Stable   | v0.6.0  | Symbolic-time-memory + sensor-time skills, ISO timestamps in prompts |
+| TUI readline/Ctrl bindings        | Stable   | v0.7.0  | Ctrl+U/W/A/E/L/D, Ctrl+X+E editor, Ctrl+C interrupt cascade         |
+| TUI Unicode width                 | Stable   | v0.7.0  | char-width: ASCII/CJK/emoji/combining marks, pure Lisp               |
+| TUI scroll notification           | Stable   | v0.7.0  | :scroll-notify flag, new-message alert when scrolled up              |
+| TUI deeper autocomplete           | Stable   | v0.7.0  | @ file paths, /theme subcommand, /focus directories                  |
+| Streaming responses               | Stable   | v0.7.2  | SSE streaming, live output in TUI, interrupt-and-redirect            |
+| TUI markdown rendering            | Stable   | v0.7.2  | Bold/italic/inline code styled via Croatoan attributes               |
+| Priority-queue signal processing  | Planned  | v0.7.2  | Preempts background for user interactions                            |
+| Markdown rendering (full)         | Planned  | v0.7.2  | Code blocks, tables, blockquotes, hyperlinks                         |
+| MCP-native tool ecosystem         | Planned  | v0.7.0  | 50+ tools from the MCP ecosystem                                     |
+| Voice gateway                     | Planned  | v0.7.3  | Speech-to-text + text-to-speech via Whisper / ElevenLabs             |
+| Task planning (tree DAG)          | Planned  | v0.8.0  | Org headline task trees, branch pruning                              |
+| Skill creator                     | Planned  | v0.8.0  | LLM drafts skills from natural language, verified before load        |
+| Computer use / vision             | Planned  | v0.9.0  | Screenshot capture, UI interaction                                   |
+| SWE-bench evaluation harness      | Planned  | v0.9.0  | Automated benchmark scoring with Org trajectory audit                |
+| Consensus loop (multi-provider)   | Planned  | v0.10.0 | Parallel inference, disagreement detection                           |
+| GTD integration                   | Planned  | v0.10.0 | Full capture-clarify-organize-reflect-engage                         |
+| Deep Emacs integration            | Planned  | v0.10.0 | Org-agenda, clock time, refile, archive                              |
+
+* Quick Start
+
+After installation, the =passepartout= command is available from anywhere.
+
+#+begin_src bash
+passepartout tui       # launch the terminal interface
+passepartout daemon    # start the background daemon (for TUI/CLI/gateways)
+passepartout doctor    # run system health check
+#+end_src
+
+See [[file:docs/USER_MANUAL.org][User Manual]] for the full guide.
+
+* Project Documentation
+
+| Document                                  | Answers                                               |
+|-------------------------------------------+-------------------------------------------------------|
+| [[file:docs/USER_MANUAL.org][User Manual]]            | How do I use it?                                      |
+| [[file:docs/ARCHITECTURE.org][Architecture]]       | How does it work inside?                              |
+| [[file:docs/DESIGN_DECISIONS.org][Design Decisions]] | Why was it built this way?                            |
+| [[file:docs/ROADMAP.org][Roadmap]]                  | Where is it going? When?                              |
+| [[file:docs/CONTRIBUTING.org][Contributing]]         | How do I contribute?                                  |
+
+* License
+
+Passepartout is released under the [[file:LICENSE][AGPLv3 license]].
+See [[file:CLA.org][CLA.org]] for the Contributor License Agreement.

USER_MANUAL.md

@@ -1,55 +0,0 @@
-# OpenCortex v0.1.0 User Manual
-
-OpenCortex is a neurosymbolic AI agent designed for autonomous Memex maintenance. It combines the probabilistic power of Large Language Models with the deterministic safety of Common Lisp and the structured clarity of Org-mode.
-
-## 1. Quick Start
-
-Install and boot OpenCortex with a single command:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash
-```
-
-Once installed, simply run `opencortex` to start the interactive CLI.
-
-## 2. The Core MVP Skills
-
-The v0.1.0 release includes the following essential skills:
-
-### Safety & Integrity
-*   **System Policy:** Enforces core invariants (Sovereignty, Transparency).
-*   **The Bouncer:** Inspects all proposed actions and blocks high-risk operations.
-*   **Protocol Validator:** Ensures communication integrity.
-
-### Cognitive Kernel
-*   **LLM Gateway:** Routes requests to your preferred provider (Gemini, Anthropic, etc.).
-*   **Peripheral Vision:** Manages context and retrieves relevant notes via Sparse Trees.
-*   **Memory Steward:** Maintains the live graph of your Org-mode Memex.
-*   **Credentials Vault:** Securely stores your API keys.
-
-### Interaction & Actuation
-*   **CLI Gateway:** The primary interface for chatting with your agent.
-*   **Shell Actuator:** Allows the agent to perform safe system side-effects.
-
-### Autonomous Services
-*   **The Scribe:** Automatically distills your daily chronological logs into structured notes.
-*   **The Gardener:** Proactively repairs broken links and flags orphaned nodes.
-
-## 3. Basic Usage
-
-### Chatting
-Type natural language messages into the CLI. The agent will perceive your intent, consult its Memory, and propose actions.
-
-### Memex Maintenance
-OpenCortex monitors your `daily/` directory. Use the Scribe to distill your thoughts:
-`User: Distill my notes from yesterday.`
-
-### Safety Approvals
-When the Bouncer intercepts a high-impact action, it will create a "Flight Plan" in your Memex. You must mark it as `APPROVED` before the agent proceeds.
-
-## 4. Configuration
-
-All configuration is stored in the `.env` file in your installation directory. You can update your API keys, change your Assistant's name, or modify the mandatory skill list there.
-
----
-*OpenCortex: The Conductor of your Life Stack.*

check_syntax.py

@@ -1,25 +0,0 @@
-import re, glob
-
-def check_file(fp):
-    with open(fp, 'r') as f:
-        content = f.read()
-    blocks = re.findall(r'#\+begin_src lisp\s+(.*?)\s+#\+end_src', content, re.DOTALL)
-    code = ' '.join(blocks)
-    
-    # Very simple check for unbalanced backquotes/commas
-    # (Doesn't handle strings/comments perfectly but helps)
-    backquotes = code.count('`')
-    commas = code.count(',')
-    
-    # Count character literals
-    bq_chars = code.count('#\\`')
-    comma_chars = code.count('#\\,')
-    
-    real_commas = commas - comma_chars
-    real_backquotes = backquotes - bq_chars
-    
-    if real_commas > 0 and real_backquotes == 0:
-        print(f"WARN: {fp} has {real_commas} commas but 0 backquotes.")
-
-for fp in glob.glob('skills/*.org'):
-    check_file(fp)

definitive_fix.py

@@ -1,57 +0,0 @@
-import os, glob, re
-
-def fix_package():
-    path = 'src/package.lisp'
-    with open(path, 'r') as f: content = f.read()
-    if '*VAULT-MEMORY*' not in content:
-        content = content.replace('#:read-framed-message', '#:read-framed-message\n   #:*VAULT-MEMORY*\n   #:COSINE-SIMILARITY\n   #:VAULT-MASK-STRING')
-    with open(path, 'w') as f: f.write(content)
-
-def fix_bouncer():
-    path = 'skills/org-skill-bouncer.org'
-    with open(path, 'r') as f: content = f.read()
-    content = content.replace('*vault-memory*', 'opencortex::*vault-memory*')
-    with open(path, 'w') as f: f.write(content)
-
-def fix_actuator():
-    path = 'skills/org-skill-shell-actuator.org'
-    with open(path, 'r') as f: content = f.read()
-    content = content.replace("#`", "#\\`").replace("#,", "#\\,")
-    # Ensure backquotes are NOT escaped by previous failed sed attempts
-    content = content.replace("\\`(", "`(").replace("\\,cmd", ",cmd").replace("\\,stdout", ",stdout")
-    with open(path, 'w') as f: f.write(content)
-
-def fix_llama():
-    path = 'skills/org-skill-llama-backend.org'
-    with open(path, 'r') as f: content = f.read()
-    content = content.replace("#`", "#\\`").replace("#,", "#\\,")
-    content = content.replace("\\`((", "`((").replace("\\,full-prompt", ",full-prompt")
-    with open(path, 'w') as f: f.write(content)
-
-def fix_memory():
-    path = 'skills/org-skill-homoiconic-memory.org'
-    with open(path, 'r') as f: content = f.read()
-    # Replace FiveAM package with a commented version
-    content = content.replace("(:use :cl :fiveam :opencortex))", "#| (:use :cl :fiveam :opencortex)) |#")
-    with open(path, 'w') as f: f.write(content)
-
-def fix_stubs():
-    path = 'literate/skills.org'
-    with open(path, 'r') as f: content = f.read()
-    stubs = """
-(in-package :opencortex)
-(defvar *VAULT-MEMORY* (make-hash-table :test 'equal))
-(defun VAULT-MASK-STRING (s) (if (> (length s) 8) (format nil "~a...~a" (subseq s 0 4) (subseq s (- (length s) 4))) "[MASKED]"))
-(defun COSINE-SIMILARITY (v1 v2) (declare (ignore v1 v2)) 1.0)
-"""
-    if 'defvar *VAULT-MEMORY*' not in content:
-        content = content.replace('(in-package :opencortex)', stubs)
-    with open(path, 'w') as f: f.write(content)
-
-fix_package()
-fix_bouncer()
-fix_actuator()
-fix_llama()
-fix_memory()
-fix_stubs()
-print("Definitive fix applied.")

deploy/bare-metal/install.sh

@@ -1,46 +0,0 @@
-#!/bin/bash
-# opencortex: Bare Metal Installation Script
-# This script sets up the opencortex daemon on a Linux host (Debian/Fedora).
-
-set -e
-
-echo "--- opencortex: Bare Metal Installation ---"
-
-# 1. Check Dependencies
-echo "[1/4] Checking dependencies..."
-for cmd in sbcl curl git ripgrep; do
-    if ! command -v $cmd &> /dev/null; then
-        echo "Error: $cmd is not installed. Please install it first."
-        exit 1
-    fi
-done
-
-# 2. Setup Quicklisp
-if [ ! -d "$HOME/quicklisp" ]; then
-    echo "[2/4] Quicklisp not found. Installing..."
-    curl -O https://beta.quicklisp.org/quicklisp.lisp
-    sbcl --non-interactive --load quicklisp.lisp --eval '(quicklisp-quickstart:install)'
-    rm quicklisp.lisp
-    echo "Quicklisp installed."
-else
-    echo "[2/4] Quicklisp already installed."
-fi
-
-# 3. Build standalone binary
-echo "[3/4] Building standalone binary..."
-PROJECT_ROOT=$(pwd)/../..
-sbcl --non-interactive \
-     --eval "(push \"$PROJECT_ROOT/\" asdf:*central-registry*)" \
-     --eval "(ql:quickload :opencortex)" \
-     --eval "(asdf:make :opencortex)"
-
-echo "Binary built: $PROJECT_ROOT/opencortex-server"
-
-# 4. Instructions for Systemd
-echo "[4/4] Installation complete."
-echo ""
-echo "To run as a systemd service:"
-echo "1. Edit opencortex.service to set correct paths."
-echo "2. sudo cp opencortex.service /etc/systemd/system/"
-echo "3. sudo systemctl daemon-reload"
-echo "4. sudo systemctl enable --now opencortex"

deploy/bare-metal/org-agent.service

@@ -1,18 +0,0 @@
-[Unit]
-Description=opencortex: Probabilistic-Deterministic Lisp Machine Kernel
-After=network.target
-
-[Service]
-Type=simple
-# Update User and WorkingDirectory to match your local setup
-User=amr
-WorkingDirectory=/home/amr/.openclaw/workspace/memex/5_projects/opencortex
-ExecStart=/home/amr/.openclaw/workspace/memex/5_projects/opencortex/opencortex-server
-Restart=always
-RestartSec=10
-
-# Environment variables can be loaded from the .env file
-EnvironmentFile=/home/amr/.openclaw/workspace/memex/5_projects/opencortex/.env
-
-[Install]
-WantedBy=multi-user.target

deploy/docker/Dockerfile

@@ -1,44 +0,0 @@
-FROM debian:bookworm-slim
-
-# Install SBCL, ripgrep, and build dependencies
-RUN apt-get update && \
-    apt-get install -y sbcl build-essential curl git ripgrep libsqlite3-dev lynx python3 python3-pip && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
-
-# Install Quicklisp globally
-RUN curl -O https://beta.quicklisp.org/quicklisp.lisp && \
-    sbcl --non-interactive \
-         --load quicklisp.lisp \
-         --eval '(quicklisp-quickstart:install :path "/opt/quicklisp")' \
-         --eval '(ql-util:without-prompting (ql:add-to-init-file))' && \
-    rm quicklisp.lisp
-
-# Set up the working directory
-WORKDIR /app
-
-# Copy source code and system definition
-COPY opencortex.asd /app/
-COPY src/ /app/src/
-
-# Ensure we aren't using a stale binary from the host
-RUN rm -f /app/opencortex-server
-
-# Build the standalone binary natively inside the container
-# This ensures GLIBC compatibility with the runtime environment.
-RUN sbcl --non-interactive \
-         --eval '(push "/app/" asdf:*central-registry*)' \
-         --eval '(ql:quickload :opencortex)' \
-         --eval '(asdf:make :opencortex)'
-
-# Ensure the binary is executable
-RUN chmod +x /app/opencortex-server
-
-# Expose the communication protocol and Web Dashboard ports
-EXPOSE 9105 8080
-
-# The app expects the memex to be mounted here
-VOLUME /memex
-
-# Run the natively compiled standalone daemon
-CMD ["./opencortex-server"]

deploy/docker/docker-compose.yml

@@ -1,18 +0,0 @@
-version: '3.8'
-
-services:
-  opencortex:
-    build:
-      context: ../..
-      dockerfile: deploy/docker/Dockerfile
-    container_name: opencortex
-    restart: unless-stopped
-    ports:
-      - "${ORG_AGENT_DAEMON_PORT:-9105}:${ORG_AGENT_DAEMON_PORT:-9105}"
-      - "${ORG_AGENT_WEB_PORT:-8080}:${ORG_AGENT_WEB_PORT:-8080}"
-    volumes:
-      - /memex:/memex
-
-networks:
-  sandbox-net:
-    driver: bridge

deploy/guix/manifest.scm

@@ -1,14 +0,0 @@
-;; opencortex: Guix Environment Manifest
-;; Usage: guix shell -m manifest.scm -- sbcl --eval ...
-
-(specifications->manifest
- '("sbcl"
-   "sbcl-cl-json"
-   "sbcl-bordeaux-threads"
-   "sbcl-usocket"
-   "sbcl-dexador"
-   "sbcl-cl-ppcre"
-   "ripgrep"
-   "git"
-   "curl"
-   "sqlite"))

deploy/lxc/setup.org

@@ -1,33 +0,0 @@
-#+TITLE: LXC / Systemd-nspawn Deployment Guide
-#+AUTHOR: opencortex
-
-* Overview
-For users who prefer containerization without the overhead or dependency on the Docker daemon, `opencortex` can be run within a standard Linux Container (LXC) or a systemd-nspawn container.
-
-* Systemd-nspawn Setup (Fastest for Linux users)
-
-1. **Create the container root:**
-   #+begin_src bash
-   sudo debootstrap --arch=amd64 bookworm /var/lib/machines/opencortex
-   #+end_src
-
-2. **Start and enter the container:**
-   #+begin_src bash
-   sudo systemd-nspawn -D /var/lib/machines/opencortex
-   #+end_src
-
-3. **Install dependencies (inside container):**
-   #+begin_src bash
-   apt-get update && apt-get install -y sbcl curl git ripgrep libsqlite3-dev build-essential
-   #+end_src
-
-4. **Bind mount the Memex directory:**
-   Add this to your container startup or use the `--bind` flag:
-   #+begin_src bash
-   sudo systemd-nspawn -D /var/lib/machines/opencortex --bind /home/amr/.openclaw/workspace/memex
-   #+end_src
-
-* Proxmox LXC Setup
-1. Create a new LXC container using the Debian 12 template.
-2. Ensure the network is bridged so Emacs can reach it.
-3. Run the `deploy/bare-metal/install.sh` script inside the container.

deploy/vms/debian/Vagrantfile

@@ -1,22 +0,0 @@
-Vagrant.configure("2") do |config|
-  config.vm.box = "debian/bookworm64"
-  config.vm.network "forwarded_port", guest: 9105, host: 9105
-
-  config.vm.provider "virtualbox" do |vb|
-    vb.memory = "1024"
-    vb.cpus = 2
-  end
-
-  config.vm.provision "shell", inline: <<-SHELL
-    apt-get update
-    apt-get install -y sbcl curl git ripgrep libsqlite3-dev build-essential
-    
-    # Setup for opencortex
-    mkdir -p /home/vagrant/opencortex
-    cp -r /vagrant/* /home/vagrant/opencortex/
-    chown -R vagrant:vagrant /home/vagrant/opencortex
-    
-    # Build binary natively
-    sudo -u vagrant bash -c "cd /home/vagrant/opencortex && ./deploy/bare-metal/install.sh"
-  SHELL
-end

deploy/vms/fedora/Vagrantfile

@@ -1,21 +0,0 @@
-Vagrant.configure("2") do |config|
-  config.vm.box = "fedora/39-cloud-base"
-  config.vm.network "forwarded_port", guest: 9105, host: 9105
-
-  config.vm.provider "virtualbox" do |vb|
-    vb.memory = "1024"
-    vb.cpus = 2
-  end
-
-  config.vm.provision "shell", inline: <<-SHELL
-    dnf install -y sbcl curl git ripgrep sqlite-devel make gcc
-    
-    # Setup for opencortex
-    mkdir -p /home/vagrant/opencortex
-    cp -r /vagrant/* /home/vagrant/opencortex/
-    chown -R vagrant:vagrant /home/vagrant/opencortex
-    
-    # Build binary natively
-    sudo -u vagrant bash -c "cd /home/vagrant/opencortex && ./deploy/bare-metal/install.sh"
-  SHELL
-end

docker-compose.yml

@@ -1,19 +0,0 @@
-services:
-  opencortex:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    container_name: opencortex
-    env_file: .env
-    volumes:
-      # Mount the entire memex directory (2 levels up from projects/opencortex)
-      - ../..:/memex
-      # Ensure signal-cli state is preserved
-      - signal-state:/root/.local/share/signal-cli
-    ports:
-      - "${ORG_AGENT_DAEMON_PORT:-9105}:9105"
-      - "${ORG_AGENT_WEB_PORT:-8080}:8080"
-    restart: unless-stopped
-
-volumes:
-  signal-state:

docs/.#DESIGN_DECISIONS.org

@@ -0,0 +1 @@
+user@amr.1407003:1778162380

docs/.#ROADMAP.org

@@ -0,0 +1 @@
+user@amr.1407003:1778162380

docs/ARCHITECTURE.org

@@ -0,0 +1,139 @@
+#+TITLE: Passepartout Architecture
+#+AUTHOR: Agent
+#+STARTUP: content
+
+* The Four Quadrants
+
+Passepartout divides cognition along two axes: **Foreground vs Background** (initiated by the user vs running autonomously) and **Probabilistic vs Deterministic** (LLM-driven vs pure Lisp logic).
+
+|                | Probabilistic (LLM)                                         | Deterministic (Lisp)                                       |
+|----------------+-------------------------------------------------------------+------------------------------------------------------------|
+| **Foreground** | Chat responses, task execution, code generation             | Shell execution, file I/O, safety gates, dispatcher checks |
+| **Background** | Scribe distillation, vector embedding, autonomous decisions | Heartbeat, cron jobs, memory auto-save, gateway polling    |
+
+The Probabilistic engine proposes. The Deterministic engine verifies and executes. No proposal from the LLM touches a file, runs a command, or sends a message without passing through at least one deterministic gate.
+
+* Architectural Layers
+
+** Core Pipeline (loaded by ASDF — the harness)
+- package definition: defpackage, cognitive tools, logging
+- memory: memory-object struct, Merkle hashing, snapshots, persistence
+- context: foveal-peripheral rendering, context assembly for LLM
+- pipeline: perceive → reason → act stages, orchestrator, heartbeat
+- skills engine: defskill macro, topological sorter, jailed loading
+- communication: framed TCP protocol, actuator registry, daemon server
+- diagnostics: health checks, doctor CLI
+
+** Skills (loaded at runtime by the skill engine)
+- gateway: TUI, CLI, messaging (Telegram, Signal)
+- system-model: provider dispatch, router, embeddings, model explorer
+- security: dispatcher (safety gate), policy, permissions, validator, vault
+- programming: Lisp, Org, literate tools, REPL, standards
+- system: config, archivist, self-improve, memory introspection, shell actuator, event-orchestrator, context-manager, setup
+
+** Clients (connect to daemon via framed TCP protocol)
+- TUI: Croatoan-based terminal interface (model-view architecture, dirty-flag rendering)
+- CLI: pipe-friendly command-line gateway
+- Emacs: elisp bridge speaking the wire protocol (planned v0.4.0)
+
+* Pipeline Flow
+
+Every signal moves through three stages:
+
+```
+Signal → Perceive (normalize) → Reason (think + verify) → Act (dispatch)
+```
+
+The signal is a plist: ~(:TYPE :EVENT :META (...) :PAYLOAD (:SENSOR :user-input :TEXT "..."))~
+
+1. **Perceive** normalizes raw input from any gateway into a uniform signal
+2. **Reason** calls the LLM to generate a proposal, then runs the proposal through all registered deterministic gates (sorted by priority). If a gate rejects the proposal, the rejection trace feeds back to the LLM for self-correction (up to 3 retries)
+3. **Act** dispatches the approved action to the registered actuator (~:cli~, ~:tool~, ~:system~, ~:shell~, ~:telegram~, ~:signal~)
+
+Each stage can produce feedback signals that loop back to Perceive (e.g., a tool-execute action produces a ~:tool-output~ event that becomes the next perception).
+
+** Depth limiting
+
+A depth counter prevents infinite loops. If a signal's depth exceeds 10, it is silently dropped. This is the circuit breaker for runaway recursive cycles.
+
+* Foveal-Peripheral Context Model
+
+When the agent assembles context for the LLM, it does not send the entire memory. It renders a sparse outline using three rules:
+
+1. *Depth ≤ 2* — the root node and its immediate children are always included (title and properties only, no content).
+2. *Foveal focus* — the node the user is currently interacting with is rendered in full, including its body content and all descendants.
+3. *Semantic relevance* — any node whose embedding vector has cosine similarity ≥ threshold (default 0.75) to the foveal node is rendered in full.
+4. *Temporal relevance* — nodes modified within a time window (current session, today) are rendered in full. Deadlines and scheduled items approaching within the warning window (default 60 minutes) are surfaced proactively in the awareness context. Nodes older than the window are title-only. This is the temporal dimension of the foveal-peripheral model: prune in time as well as in semantic space.
+
+Nodes that don't match any rule are rendered as title-only — a single Org headline with its :ID: property. This keeps active context between 2,000–4,000 tokens for typical memex sizes, versus 50,000–150,000 tokens for a full serialization. The embedding vectors that power semantic retrieval are computed at ingest time (~ingest-ast~ in core-memory.lisp) and can use local models (Ollama), cloud APIs (OpenAI embeddings), or a zero-dependency lexical fallback (trigram Jaccard similarity).
+
+For the rationale behind sparse-tree rendering and why this architecture outperforms "load everything" systems, see Design Decisions: Org-Mode as Unified AST.
+
+* Dispatcher Gate Stack
+
+Every action the LLM proposes passes through a stack of deterministic gates before execution. Gates are registered as skills with ~defskill~ and sorted by priority (highest first) in ~cognitive-verify~ (core-loop-reason.lisp).
+
+| Priority | Gate                      | What It Checks                                           |
+|----------+---------------------------+----------------------------------------------------------|
+| 600      | security-permissions      | Tool permission table (allow/ask/deny per tool)          |
+| 600      | security-vault            | Credential storage integrity                             |
+| 500      | security-policy           | Requires :explanation on every action                    |
+| 150      | security-dispatcher       | 11-check safety: lisp, secret path, self-build,          |
+|          | (the Dispatcher)          | content exposure, vault, privacy tags, privacy text,      |
+|          |                           | shell safety, network exfil, high-impact approval         |
+| 95       | security-validator        | Protocol schema validation                               |
+| 100      | system-archivist          | Scribe and Gardener maintenance on heartbeat             |
+| 80       | system-event-orchestrator | Cron job dispatch on heartbeat                           |
+
+Gates return either the action (passed through unchanged), a rejection (:LOG or :EVENT with block reason), or an approval request (:EVENT with :level :approval-required). Rejections feed back to the LLM as a rejection trace — the model sees what it proposed, which gate blocked it, and why, and retries with that context (up to 3 retries). Approval requests create Flight Plan Org nodes requiring human review via the HITL workflow.
+
+Every gate is a pure Common Lisp function. Verification costs 0 LLM tokens. Contrast with prompt-based guardrails (Claude Code, OpenClaw, Hermes Agent) which consume 100–500 LLM tokens per verification.
+
+For the rationale behind deterministic vs prompt-based safety, see Design Decisions: The Probabilistic-Deterministic Split and The Dispatcher as Learning System.
+
+* Embedding & Semantic Retrieval Pipeline
+
+Every memory-object can carry an embedding vector for semantic search. The pipeline:
+
+1. *Ingest* — ~ingest-ast~ (core-memory.lisp) calls ~embeddings-compute~ on new objects, storing the vector in ~memory-object-vector~.
+2. *Queue* — objects with stale vectors are queued via ~mark-vector-stale~. The ~embed-all-pending~ cron job (every 10 minutes, :REFLEX tier) drains the queue and recomputes vectors.
+3. *Retrieval* — ~context-awareness-assemble~ (core-context.lisp) passes the foveal node's vector to ~context-object-render~. Nodes with cosine similarity ≥ threshold against the foveal vector are rendered in full rather than as title-only.
+
+Three backends are available, selected via ~EMBEDDING_PROVIDER~:
+- :local — Ollama-compatible /api/embeddings endpoint (e.g., nomic-embed-text)
+- :openai — OpenAI /v1/embeddings API (e.g., text-embedding-3-small)
+- :hashing — zero-dependency lexical fallback using trigram Jaccard similarity (replaced SHA-256 hashing in v0.4.0 because cryptographic hashes maximise output divergence — the opposite of what a similarity metric needs)
+
+For the design rationale, see Design Decisions: Token Economics and Performance Advantage.
+
+* Skill Lifecycle
+
+1. *Discovery:* ~skill-initialize-all~ scans the skills directory, globs for ~*.lisp~ files (excluding ~core-*~ files which are loaded by ASDF)
+2. *Sorting:* ~skill-topological-sort~ orders skills by their ~#+DEPENDS_ON:~ declarations
+3. *Loading:* Each skill is loaded into a jailed package (~passepartout.skills.<skill-name>~). The loader removes ~in-package~ forms, evaluates the remaining code in the jailed package, and exports symbols matching the skill's short name to ~passepartout~
+4. *Registration* The skill's ~defskill~ call creates a ~skill~ struct in ~*skill-registry*~, registering its trigger function, probabilistic prompt generator, deterministic gate, and system-prompt augment
+5. *Triggering:* On each cognitive cycle, ~skill-triggered-find~ iterates the registry and returns the highest-priority skill whose trigger matches the context
+6. *Hot-reload:* A skill can be replaced at runtime by loading a new version into its jailed package — no restart needed
+
+* Communication protocol Format
+
+All communication between the daemon and its gateways (TUI, CLI, Emacs) uses length-prefixed plists over TCP:
+
+```
+00002C(:TYPE :EVENT :PAYLOAD (:ACTION :handshake :VERSION "0.4.0"))
+```
+
+The 6-character hex prefix encodes the payload length. The payload is a ~prin1~-serialized plist. ~*read-eval*~ is bound to nil on the receiving end to prevent code injection.
+
+** Standard message envelope:
+
+| Key | Value | Meaning |
+|-----|-------|---------|
+| ~:TYPE~ | ~:REQUEST~, ~:EVENT~, ~:RESPONSE~, ~:LOG~, ~:STATUS~ | Message category |
+| ~:META~ | plist | ~:SOURCE~, ~:SESSION-ID~, ~:reply-stream~ |
+| ~:PAYLOAD~ | plist | Action-specific data (~:SENSOR~, ~:ACTION~, ~:TEXT~) |
+| ~:DEPTH~ | integer | Recursion counter for loop prevention |
+
+The protocol lifecycle begins with a handshake: the daemon sends a :handshake action with its version, and the client responds with its capabilities. After handshake, either side can send any message type. The daemon never initiates a disconnect — clients poll for messages and reconnect on EOF.
+
+Planned for v0.6.3: streaming chunk frames (~:type :stream-chunk~) carrying partial LLM output. The final chunk is an empty string signalling end-of-stream, enabling interrupt-and-redirect from the client side.

docs/CONTRIBUTING.org

@@ -0,0 +1,116 @@
+#+TITLE: Contributing to Passepartout
+#+AUTHOR: Passepartout Contributors
+#+STARTUP: content
+#+FILETAGS: :docs:contributing:
+
+* Philosophy
+Passepartout is built on a "Zero-Bloat" mandate. The core kernel is mathematically pure, pushing all peripheral logic, API integrations, and routing to hot-reloadable "Skills".
+
+* Development Workflow
+
+The full development cycle is described in ~AGENTS.md~. In summary:
+
+1. *Think in org* — write reasoning and goals in the .org file
+2. *Write contract* — define each function's behavior in a ~** Contract~ section
+3. *TDD from contract* — each contract item becomes a ~fiveam:test~; prove RED then GREEN
+4. *Reflect in org* — ensure implementation is in .org source
+5. *Update literate prose* — explain the code: what, why, how it connects
+
+* Literate Programming
+
+~.org~ files in ~org/~ are the source of truth. ~lisp/~ files are generated by ~org-babel-tangle~.
+
+- Never edit =lisp/= files directly — always modify the corresponding =org/= file
+- All ~#+begin_src lisp~ blocks in a file inherit their tangle destination from the file-level ~#+PROPERTY: header-args:lisp :tangle ../lisp/FILE.lisp~
+- Every architectural decision, constraint, and implementation detail must be documented alongside the code
+
+* Contracts and Tests
+
+Every code change starts with a contract and a failing test. Write a ~** Contract~ section listing each function's behavior, then create a ~fiveam:test~ in the ~* Test Suite~ section for each contract item.
+
+To run tests for a specific file:
+
+#+begin_src bash
+sbcl --noinform \
+  --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' \
+  --eval '(ql:quickload :passepartout :silent t)' \
+  --eval '(load "lisp/FILE.lisp")' \
+  --eval '(fiveam:run (intern "SUITE-NAME" :passepartout-TESTS))' --quit
+#+end_src
+
+No test may be committed without proof it was first run to failure (RED).
+
+* Skill Creation Standard
+
+A skill is a =.org= file in =org/= that defines:
+
+1. *Contract* — what the skill guarantees
+2. *Implementation* — the code, tangled to ~lisp/~ via ~#+PROPERTY: header-args:lisp~
+3. *Skill Registration* — a ~defskill~ form with ~:priority~, ~:trigger~, ~:probabilistic~ / ~:deterministic~
+4. *Test Suite* — ~fiveam:test~ forms verifying the contract
+
+Example:
+#+begin_src lisp
+(defskill :passepartout-example
+  :priority 100
+  :trigger (lambda (ctx) ...)
+  :probabilistic (lambda (ctx) ...)
+  :deterministic (lambda (action ctx) ...))
+#+end_src
+
+* Project Structure
+
+| Directory            | Purpose                                          |
+|----------------------+--------------------------------------------------|
+| =org/=               | Literate source files (edit these)               |
+| =lisp/=              | Tangled .lisp output (never edit)                |
+| =docs/=              | ROADMAP, ARCHITECTURE, DESIGN_DECISIONS, etc.    |
+| =scripts/=           | Build and utility scripts                        |
+| ~/.local/share/passepartout/= | XDG data dir — deployed lisp files     |
+| ~/.config/passepartout/=     | Config (.env)                          |
+
+* Key Libraries
+
+| Library          | Purpose                          |
+|------------------+----------------------------------|
+| Croatoan         | TUI (terminal UI)                |
+| usocket          | TCP sockets (daemon protocol)    |
+| bordeaux-threads | Threading (reader thread)        |
+| dexador          | HTTP client (LLM API calls)      |
+| cl-ppcre         | Regex (search-files, dispatcher) |
+| ironclad         | SHA-256 (Merkle hashing)         |
+| hunchentoot      | HTTP server                      |
+| cl-json          | JSON encoding/decoding           |
+
+* Protocol
+
+All inter-process communication uses the Unified Envelope protocol over TCP (port 9105). Message types: ~:REQUEST~, ~:EVENT~, ~:RESPONSE~, ~:STATUS~, ~:LOG~. Each message includes a ~:META~ block with routing metadata.
+
+* Pre-Commit Hook
+
+Validates staged org files by tangling + structural-checking:
+#+begin_src bash
+ln -sf ../../scripts/pre-commit-repl-check .git/hooks/pre-commit
+#+end_src
+Runs automatically on ~git commit~.
+
+* Testing Tools
+
+** TUI REPL (~/eval~)
+The TUI has a built-in command for live evaluation:
+- ~/eval (+ 1 2)~ → result displayed in chat window
+- ~/eval (add-msg :system "test")~ → inject a test message
+
+** Tmux (TUI integration testing)
+#+begin_src bash
+tmux new-session -d -s test "passepartout tui 2>&1 | tee /tmp/tui.log"
+tmux send-keys -t test "hello world" Enter
+tmux capture-pane -t test -p -S -200
+tmux kill-session -t test
+#+end_src
+
+** Swank (Emacs REPL for TUI)
+1. Start TUI: ~passepartout tui~
+2. In Emacs: ~M-x slime-connect RET 127.0.0.1 RET 4006~
+3. ~C-M-x~ any form from =org/gateway-tui.org= → evaluates in live TUI process
+4. Configure port: ~export TUI_SWANK_PORT=4009~ (default: 4006)

docs/MVP_SPEC.org

@@ -1,93 +0,0 @@
-#+TITLE: OpenCortex MVP (v0.1.0) Specification & Release Plan
-#+STARTUP: content
-
-* Objective
-Define detailed specifications for the OpenCortex MVP (v0.1.0). This MVP establishes the autonomous foundation and introduces a native Common Lisp Terminal User Interface (TUI) for improved UX, alongside a comprehensive release plan.
-
-* 1. Core Architecture & Environment (Completed)
-- *System Harness:* A minimal, un-brittle Common Lisp (SBCL) microkernel that orchestrates the Perceive -> Probabilistic -> Deterministic -> Dispatch pipeline.
-- *Dual-Engine Cognition:*
-  - /Probabilistic Engine:/ The LLM gateway handling semantic translation, multi-modal ingestion, and intent parsing (supporting Anthropic, Gemini, Groq, OpenAI, and Ollama).
-  - /Deterministic Engine:/ The Lisp logical core that mathematically verifies LLM-proposed actions against system rules prior to execution.
-- *Data Stores:*
-  - /Linguistic Substrate:/ Org-mode plaintext files acting as the universal Abstract Syntax Tree (AST) for both humans and the agent.
-  - /Lisp Memory:/ A live, threaded graph of Lisp objects representing the Memex in RAM for instant, token-efficient traversal (Sparse Trees).
-- *Skill Architecture:* All agent capabilities are encapsulated in single-file Literate Programs (~org-skill-*.org~). They are topologically loaded, dynamically compiled, and hot-reloadable.
-
-* 2. Mandatory Security & Containment (Completed)
-- *Formal Verification Gate:* Evaluates actions before they hit the OS.
-  - /Path Confinement:/ Guarantees file writes are physically locked to the `~/memex/` root directory.
-  - /Network Exfiltration:/ Intercepts and blocks unauthorized external generic HTTP or socket requests.
-- *System Policy Gate:* Enforces the "Zero-Bloat" and "Autonomy Above All" invariants.
-- *Credentials Vault:* API keys and ~.env~ files are stored in a secure, masked Lisp enclave, rendering them invisible to the LLM's context window.
-
-* 3. Autonomous Background Workers (Completed)
-- *The Scribe (~org-skill-scribe.org~):* A distillation engine that periodically reads the chronological logs (e.g., daily journal files) and autonomously extracts concepts into permanent Zettelkasten notes.
-- *The Gardener (~org-skill-gardener.org~):* A heartbeat-driven, idle process that continuously walks the memory graph. It automatically repairs broken internal links, infers missing metadata, and flags orphaned ideas for the user.
-
-* 4. Native Terminal User Interface (UX Target)
-- *Objective:* Eliminate raw ~stdout~ shell piping in favor of a rich, structured, and interactive Common Lisp TUI.
-- *Library:* ~croatoan~ (A high-level CLOS wrapper for ncurses) will be used for rapid, robust UI development.
-- *Layout:*
-  - /Main Viewport:/ A read-only, scrollable panel that renders Org-mode headlines, syntax-highlighted Lisp/Python code blocks, and system logs.
-  - /Input Box:/ A fixed, multi-line input area pinned to the bottom of the screen, supporting standard Readline keybindings.
-  - /Status Bar:/ A persistent bar at the top or bottom displaying the health and current activity of background workers (Scribe/Gardener) and memory usage.
-- *Interactive Control (Slash Commands):*
-  - ~/help~: View system overview and command syntax.
-  - ~/clear~: Clear the viewport buffer.
-  - ~/skill-load <skill-name>~: Dynamically reload a modified Lisp skill into the active image.
-  - ~/exit~: Gracefully shut down the harness and exit the environment.
-  - ~/status~: Print diagnostic report (memory, git status, worker uptimes).
-  - ~/config~: Display active config/env vars (masking secrets).
-  - ~/search <query>~: Raw deterministic regex/vector search across the Memex.
-  - ~/commit~: Trigger Engineering Standard check, stage, and commit Memex state.
-- *Refactoring:* Reroute the existing ~:cli~ actuator and inbound gateway to exclusively utilize the new TUI rendering engine.
-
-* 5. Release & Publication Plan (v0.1.0)
-- *Documentation:*
-  - ~USER_MANUAL.md~: A comprehensive guide on the one-liner installation (~opencortex.sh~), daily workflow, and navigating the Memex directory structure.
-  - ~CONTRIBUTING.md~: A guide to "Literate Granularity" engineering standards and creating new ~org-skill-*.org~ files.
-- *Legal Finalization:* 
-  - Assign the *AGPLv3* open-source license. 
-  - Implement a broad *Contributor License Agreement (CLA)* process for external contributors to license rights back to the core project.
-  - Update ~LICENSE~ and finalize ~CHANGELOG.org~.
-- *End-to-End Walkthrough:* Execute a clean-slate test of the installation script, boot sequence, environment variable parsing, and autonomous background worker triggers.
-- *Marketing & Launch:* Migrate the canonical repository to GitHub (configure topics, badges, and issue templates). Record a high-fidelity GIF/video of the new TUI interaction and execute announcements on Hacker News, Reddit, and X/Twitter.
-
-* 6. User-Centric End-to-End Test Plan
-
-This section defines the precise workflow and expected user experience for the v0.1.0 MVP. It serves as the definitive manual testing script before release.
-
-** Phase 1: The One-Liner Installation & Boot
-- *Action:* The user executes the canonical curl-bash script: ~curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash~
-- *Expected Experience:* 
-  1. The script detects the OS and installs any missing system dependencies (e.g., Docker, SBCL, Quicklisp).
-  2. It interactively prompts the user to enter as many LLM API keys as they choose to (e.g., Gemini, Anthropic, OpenAI). The user can skip this step and configure them later.
-  3. It asks the user for their existing folder structure and fills in the corresponding values (INBOX_DIR, DAILY_DIR, etc.) in ~.env.example~ to generate a valid ~.env~ file.
-  4. It compiles and launches the ~opencortex-server~ daemon in the background.
-  5. The user is greeted with a success message instructing them to run ~opencortex tui~.
-
-** Phase 2: First Contact (The TUI Experience)
-- *Action:* The user types ~opencortex tui~ in their terminal.
-- *Expected Experience:*
-  1. The terminal clears and launches the Croatoan UI.
-  2. The *Status Bar* appears at the bottom, indicating: ~[Scribe: Idle] [Gardener: Sleeping]~.
-  3. The user types a natural language message in the input box: "Hello, what is my current Memex structure?" and presses Enter.
-  4. The input box clears, and the user's message appears in the main viewport.
-  5. A few seconds later, the agent responds with a formatted Org-mode list of the directories, demonstrating successful Lisp s-expression communication over the TCP socket and valid probabilistic reasoning.
-
-** Phase 3: The Autonomous Subroutines
-- *Action:* The user creates a messy text file in ~/memex/daily/YYYY-MM-DD.org~ with a scattered thought about a new project, then waits.
-- *Expected Experience:*
-  1. Without any user prompting, the *Status Bar* updates to ~[Scribe: Distilling...]~.
-  2. A quiet log message appears in the TUI viewport: ~*System*: Scribe extracted 1 new Zettelkasten note.~
-  3. The user inspects ~/memex/notes/~ and finds a cleanly formatted, semantically tagged Org node containing the distilled thought.
-  4. The user intentionally breaks an Org-roam link in one of their notes. Minutes later, the Gardener awakens (~[Gardener: Auditing]~), and a log message appears indicating the link was repaired or flagged.
-
-** Phase 4: Deterministic Actuation (Slash Commands)
-- *Action:* The user types ~/status~ in the TUI.
-- *Expected Experience:* The TUI instantly prints a diagnostic report showing memory usage, uptime, and git status, bypassing the LLM entirely.
-- *Action:* The user types ~/commit~.
-- *Expected Experience:* The system runs the Engineering Standard gate, stages all changes in ~/memex~, and creates a git commit. The TUI confirms success.
-- *Action:* The user types ~/exit~.
-- *Expected Experience:* The TUI client gracefully disconnects and closes, returning the user to their standard bash prompt. The ~opencortex-server~ continues running safely in the background.

docs/USER_MANUAL.org

@@ -0,0 +1,461 @@
+#+TITLE: Passepartout User Manual
+#+AUTHOR: Passepartout Contributors
+#+STARTUP: content
+#+FILETAGS: :docs:manual:
+
+* Introduction
+Welcome to Passepartout. Passepartout is a neurosymbolic AI agent and a Lisp Machine operating system designed to autonomously maintain your Memex (knowledge base) and interact with you via multiple, equal-citizen interfaces.
+
+* Installation
+Passepartout is bootstrapped via a single shell script.
+
+** Quick start (curl)
+
+#+begin_src bash
+curl -fsSL https://raw.githubusercontent.com/amrgharbeia/passepartout/main/passepartout | bash -s configure
+#+end_src
+
+This will:
+1. Install system dependencies (SBCL, Emacs, git, curl, socat — detected for Debian or Fedora)
+2. Install Quicklisp (Common Lisp package manager)
+3. Tangle literate Org sources into runnable Lisp
+4. Launch the interactive setup wizard (LLM providers, gateways)
+
+If you already have Emacs installed, the installer skips it and uses your existing installation.
+
+* Configuration
+The system is configured via a ~.env~ file in the project root. Essential variables include:
+
+- ~OPENROUTER_API_KEY~: Your LLM provider key.
+- ~PROVIDER_CASCADE~: The fallback order for LLM providers (e.g., ~openrouter,ollama,anthropic~).
+- ~MEMEX_DIR~: The absolute path to your knowledge base (defaults to ~/memex~).
+
+* Interacting with Passepartout
+Because of the Unified Envelope Architecture, the kernel treats all clients as interchangeable. You must first boot the background daemon:
+
+#+begin_src bash
+./passepartout --boot &
+#+end_src
+
+** Terminal User Interface (TUI)
+For a rich, split-pane terminal experience:
+#+begin_src bash
+./passepartout tui
+#+end_src
+
+** Command Line Interface (CLI)
+For raw, pipe-friendly interaction:
+#+begin_src bash
+./passepartout cli
+#+end_src
+
+** TUI Commands
+
+When connected via the TUI, the following commands are available (type them in the input area and press Enter):
+
+| Command               | Action                                                 |
+|-----------------------+--------------------------------------------------------|
+| ~/help~               | List all available commands                             |
+| ~/focus <project>~    | Set the agent's foveal focus to a project by name      |
+| ~/scope memex~        | Set scope to full memex (all projects visible)         |
+| ~/scope session~      | Set scope to current session only                       |
+| ~/scope project~      | Set scope to focused project only                       |
+| ~/unfocus~            | Clear the foveal focus                                  |
+| ~/approve HITL-xxxx~  | Approve a pending HITL action by its token              |
+| ~/deny HITL-xxxx~     | Deny a pending HITL action by its token                 |
+| ~/theme <name>~       | Switch theme (dark, light, solarized, gruvbox)         |
+| ~/cost~               | Toggle session cost display in status bar               |
+| ~/voice on~           | Enable voice capture (planned v0.7.3)                  |
+| ~/voice off~          | Disable voice capture                                   |
+| ~/quit~               | Save history and exit (planned v0.3.3)                 |
+
+For multi-line input, start the line with ~\~ then press Enter to insert a newline without sending.
+
+** Human-in-the-Loop Approval
+
+When the Dispatcher blocks a high-risk action (shell command, network call, core file modification), it creates a Flight Plan requiring your approval.
+
+1. The TUI displays a yellow message: ~→ HITL required: /approve HITL-ab12~
+2. Review the proposed action in the Dispatcher trace (expand with Tab)
+3. Type ~/approve HITL-ab12~ to approve, or ~/deny HITL-ab12~ to deny
+4. Approved actions are re-injected into the pipeline and executed
+5. Denied actions are discarded and the Dispatcher records the decision as a permanent rule
+
+Each approval or denial teaches the Dispatcher — the rule counter in the status bar (~[Rules: 47]~) increments with every decision.
+
+* The Memex Structure
+Passepartout assumes a local folder structure representing your "Memex".
+- Core memories and identities are mapped to Org-mode files.
+- The ~Scribe~ background worker distills chronological logs into structured Zettelkasten notes.
+- The ~Gardener~ continuously repairs broken links and flags orphaned nodes.
+
+* How Safety Works
+
+Passepartout enforces safety through ten deterministic gates. Every action the agent wants to take — reading a file, running a shell command, sending network traffic — passes through these gates before execution. Critically, all ten gates are pure Lisp functions: they cost zero LLM tokens to evaluate. Safety checking never touches your provider budget.
+
+** The Ten Safety Gates
+
+| Gate | What It Checks |
+|------+----------------|
+| Lisp syntax | Validates that any Lisp code is well-formed before evaluation |
+| Secret file paths | Blocks reads from known secret directories (~.ssh~, ~.env~, ~.aws~, etc.) |
+| Self-build core | Prevents modification of the agent's own source and build files |
+| Secret content | Scans text output for API keys, tokens, or credential patterns |
+| Vault secrets | Guards any secret stored in the encrypted vault |
+| Privacy tags | Respects ~@privacy:~ annotations on memory objects and files |
+| Privacy text leaks | Scans outgoing text for PII (emails, phone numbers, addresses) |
+| Shell safety | Blocks destructive commands (~rm -rf~, ~:(){:|:&};:~, ~mkfs~, ~dd~) |
+| Network exfiltration | Blocks outbound traffic carrying private data to unknown hosts |
+| High-impact actions | Catches system-level changes (package installs, service restarts, mount) |
+
+** Severity Tiers
+
+Each gate assigns a severity to the action it inspects:
+
+| Severity   | Behavior                                              |
+|------------+-------------------------------------------------------|
+| Catastrophic | Always blocked. No approval possible.                |
+| Dangerous    | Requires HITL approval. Generates a Flight Plan.    |
+| Moderate     | Allowed, but logged. The agent learns from the outcome. |
+| Harmless     | Always allowed. No logging overhead.                 |
+
+** What Happens When an Action Is Blocked
+
+When a gate blocks an action, the Dispatcher creates a Flight Plan — a structured record of what the agent wants to do, why it was blocked, and which gate triggered. The Flight Plan is presented to you for review. You can approve it (~/approve~), deny it (~/deny~), or ask the agent to clarify its intent (~/clarify~). Once you approve, the action executes immediately. Once you deny, the Dispatcher records the decision as a permanent rule and will never propose that action again.
+
+* Understanding Context and Focus
+
+Passepartout uses a foveal-peripheral context model, inspired by human vision. This is how the agent decides what to pay attention to in your Memex.
+
+** The Three Levels of Attention
+
+- ~/foveal/~ — What the agent reads deeply and reasons about right now. Anything you explicitly mention, plus the current focused project.
+- ~/peripheral/~ — What the agent knows exists (titles, summaries, metadata) but does not read in detail. Everything in scope.
+- ~/blind/~ — Outside scope. The agent cannot see or access it.
+
+** Focus Commands
+
+| Command             | Effect                                                  |
+|---------------------+---------------------------------------------------------|
+| ~/focus <project>~  | Set the agent's foveal attention to a project           |
+| ~/scope memex~      | Expand scope to everything in your Memex               |
+| ~/scope session~    | Narrow scope to just the current conversation           |
+| ~/scope project~    | Narrow scope to the focused project only               |
+| ~/unfocus~          | Clear the foveal focus; the agent sees everything at peripheral level |
+
+** The Focus Map
+
+The status bar displays a focus map — a compact representation of what the agent is "looking at." Projects in foveal view are highlighted; peripheral projects are dimmed. When you change focus, the map updates in real time so you always know the agent's current attention budget.
+
+* Skills and What They Do
+
+Skills are hot-reloadable modules that extend the agent's capabilities. Unlike core system files, a bug in a skill degrades the agent but does not kill it — skills can be repaired by the agent itself. Skills are organized into categories by function:
+
+** Core Pipeline
+The agent's cognitive loop: Perceive (consume input) → Reason (think with the LLM) → Act (execute tools). This is the central nervous system of the agent.
+
+** Security
+~Dispatcher~, ~Policy~, ~Permissions~, ~Validator~, ~Vault~. These skills enforce the safety gates, manage approval workflows, encrypt secrets, and verify that every action conforms to the rules you have set.
+
+** Channels
+~TUI~, ~CLI~, ~Telegram~, ~Signal~, ~Discord~, ~Slack~, ~Shell~. Each channel is a separate skill that handles I/O for a specific interface. All channels are equal citizens — the agent treats a message from Telegram identically to one typed in the TUI.
+
+** Programming
+~Lisp~, ~Org~, literate tools, ~REPL~, standards libraries. These skills allow the agent to write, evaluate, and reason about Lisp code, manage Org-mode documents, and tangle literate programs into runnable source.
+
+** Symbolic
+~Awareness~, ~Scope~, ~Events~, ~Config~, ~Memory~, ~Identity~, ~Time~. These skills manage the agent's internal state: what it knows about itself, what it remembers, how it configures its behavior, and how it tracks time and events.
+
+** Neuro
+~Provider~, ~Router~, ~Explorer~. These skills manage the LLM backends. The Provider skill abstracts each LLM API; the Router decides which provider to use based on cost, latency, and availability; the Explorer discovers new providers.
+
+** Embedding
+Backends for semantic search and native inference. These skills enable the agent to embed text, search your Memex by meaning rather than exact keyword, and run local inference without network calls.
+
+** Economics
+~Tokenizer~, ~Cost Tracker~, ~Token Economics~. These skills count tokens, estimate costs before making LLM calls, track spending across providers, and enforce budget limits.
+
+* The Tool System
+
+The agent has ten cognitive tools — discrete actions it can take to interact with your environment. Each tool maps to a specific capability.
+
+** Read-Only Tools
+
+| Tool              | What It Does                                |
+|-------------------+---------------------------------------------|
+| ~search-files~    | Search file contents with regex patterns    |
+| ~find-files~      | Find files by name using glob patterns      |
+| ~read-file~       | Read the contents of a file on disk         |
+| ~list-directory~  | List the contents of a directory            |
+| ~org-find-headline~ | Find a headline in an Org-mode file       |
+
+** Write Tools
+
+| Tool              | What It Does                                |
+|-------------------+---------------------------------------------|
+| ~write-file~      | Create or overwrite a file on disk          |
+| ~org-modify-file~ | Modify an Org-mode file structurally        |
+| ~run-shell~       | Execute a shell command                     |
+| ~eval-form~       | Evaluate a Lisp expression                  |
+| ~run-tests~       | Execute a test suite                        |
+
+** Auto-Approval
+
+Write tools are subject to safety-gate inspection. Read-only tools are auto-approved by default (though the agent still checks for secret-file reads). You can configure per-tool auto-approval in your ~.env~ file with the ~AUTO_APPROVE_TOOLS~ variable:
+
+#+begin_src bash
+# Auto-approve read-file and find-files (default)
+AUTO_APPROVE_TOOLS=read-file,find-files,list-directory,search-files
+#+end_src
+
+* Cost Tracking
+
+Every LLM call costs tokens, and tokens cost money. Passepartout tracks this transparently.
+
+** Token Budgets
+
+Set ~CONTEXT_MAX_TOKENS~ in your ~.env~ file to cap the total context window the agent may use per interaction:
+
+#+begin_src bash
+CONTEXT_MAX_TOKENS=128000
+#+end_src
+
+The agent will truncate older context rather than exceed this limit.
+
+** Per-Call Cost Tracking
+
+Before every LLM call, the Economics skill estimates the cost (prompt tokens + expected completion tokens) and checks it against your budget. After the call, it records actual usage. The status bar shows your session total.
+
+** The ~/cost~ Command
+
+Toggle cost display in the status bar with ~/cost~. When enabled, you'll see a running total like ~[$0.047]~ showing the estimated cost of the current session.
+
+** Per-Provider Pricing
+
+Different providers charge different rates. The Router skill is aware of this and will choose the cheapest viable provider for each call unless you pin a specific provider:
+
+#+begin_src bash
+# Pin to a specific provider
+PROVIDER_CASCADE=anthropic
+#+end_src
+
+** Prompt Prefix Caching
+
+Providers that support prefix caching (Claude via Anthropic, some OpenRouter models) automatically benefit from it. The agent reuses the system prompt prefix across calls, and the Economics skill tracks the cache-hit savings separately in the cost breakdown.
+
+* Session Control
+
+Passepartout maintains a session history with checkpointed memory snapshots. You can move backward and forward through your session state.
+
+** Undo and Redo
+
+| Command      | Effect                                                   |
+|--------------+----------------------------------------------------------|
+| ~/undo~      | Restore the memory to the state before your last action  |
+| ~/redo~      | Re-apply the last undone action                          |
+| ~/rewind <n>~ | Restore the memory to the state n actions ago           |
+
+** What Gets Restored
+
+A session rewind restores three things: file changes (files written or modified are reverted), memory objects (the agent's internal knowledge), and TODO states (the roadmap and task tracking). This means you can safely let the agent explore and experiment — if it goes down a wrong path, rewind and redirect.
+
+* Gate Trace Reference
+
+Below every agent message in the TUI, you'll see colored lines representing the safety-gate trace for that message. These show you exactly which gates ran on the agent's actions and what happened.
+
+| Symbol | Meaning                                                    |
+|--------+------------------------------------------------------------|
+| ~✓~    | Green — the gate passed. The action was allowed.            |
+| ~✗~    | Red — the gate blocked the action. The reason is shown.     |
+| ~→~    | Yellow — HITL approval required. A Flight Plan is pending.  |
+
+Press ~Ctrl+G~ to toggle gate trace visibility on and off. The most recent gate trace for your last interaction is always available via the ~/why~ command — type ~/why~ and the agent will display the full trace with explanations.
+
+* Tag System
+
+Passepartout uses an Org-mode tag system to annotate and control behavior. Tags are metadata appended to headlines and memory objects.
+
+** Severity Tags
+
+The ~@tag:severity~ tier controls how strictly the safety system handles a tagged item:
+
+| Tag              | Behavior                                                     |
+|------------------+--------------------------------------------------------------|
+| ~@tag:block~     | The tagged item is treated as catastrophic — always blocked  |
+| ~@tag:warn~      | The tagged item triggers HITL approval when accessed         |
+| ~@tag:log~       | Access is allowed but logged for audit                       |
+
+** Tag Categories
+
+Configure which tags trigger which behavior with the ~TAG_CATEGORIES~ environment variable:
+
+#+begin_src bash
+TAG_CATEGORIES=block:warn:log
+#+end_src
+
+** The ~/tags~ Command
+
+Type ~/tags~ to list all tags currently active in the agent's scope, along with their severity levels and the files or memory objects they apply to.
+
+* HITL Deep Dive
+
+When the Safety system blocks an action, a structured workflow begins. Understanding this workflow helps you make informed approval decisions quickly.
+
+** The Flight Plan Lifecycle
+
+1. /Trigger/: A gate rates an action Dangerous or Catastrophic, or a ~@tag:warn~ tag is encountered.
+2. /Plan/: The Dispatcher serializes the proposed action into a Flight Plan: what tool, what arguments, what file or command, which gate triggered.
+3. /Display/: The TUI shows a yellow prompt with the Flight Plan token (~HITL-ab12~).
+4. /Review/: Press ~Tab~ to expand the gate trace and see the full Flight Plan details.
+5. /Decision/: You type ~/approve HITL-ab12~ or ~/deny HITL-ab12~.
+6. /Execute or Discard/: Approved plans execute immediately. Denied plans are discarded.
+7. /Learn/: The Dispatcher increments its rule counter and records the decision as a permanent rule. If you denied an action, the Dispatcher will never propose it again.
+
+** Clarifying Questions
+
+If you are unsure why the agent wants to perform an action, you can ignore the Flight Plan prompt. After three retries without a decision, the agent escalates by injecting a ~/clarify~ message into the pipeline, asking the agent to explain its intent in plain language. You can then approve or deny with full context.
+
+** The Rule Counter
+
+The status bar shows ~[Rules: N]~ — the number of permanent rules the Dispatcher has learned from your decisions. Each approval or denial is a learning event. Over time, the Dispatcher builds a personalized safety profile that reflects your preferences: which actions you always approve, which you always deny, and which you want to review case by case.
+
+* TUI Keybinding Reference
+
+The TUI supports a rich set of keyboard shortcuts for efficient interaction.
+
+** Editing Keys
+
+| Combo     | Action                                    |
+|-----------+-------------------------------------------|
+| ~Ctrl+D~  | Quit the TUI                              |
+| ~Ctrl+U~  | Clear the current input line              |
+| ~Ctrl+W~  | Delete the word before the cursor         |
+| ~Ctrl+A~  | Move cursor to beginning of line (Home)   |
+| ~Ctrl+E~  | Move cursor to end of line               |
+| ~Ctrl+K~  | Delete from cursor to end of line         |
+| ~Ctrl+L~  | Redraw the screen                         |
+| ~Ctrl+X+E~ | Open the current input in your external editor (~$EDITOR~) |
+| ~Tab~     | Autocomplete commands, themes, and file paths |
+
+** Navigation and Control
+
+| Combo            | Action                                           |
+|------------------+--------------------------------------------------|
+| ~Ctrl+C~         | Interrupt (cascade: stop streaming → stop thinking → quit) |
+| ~Ctrl+F~         | Search through message history                   |
+| ~Ctrl+P~         | Open the command palette                         |
+| ~Ctrl+G~         | Toggle gate trace visibility                     |
+| ~Ctrl+X+B~       | Toggle the sidebar (focus map, memory browser)   |
+| ~Page Up~        | Scroll chat up by 10 lines                       |
+| ~Page Down~      | Scroll chat down by 10 lines                     |
+| ~Up Arrow~       | Previous input in command history                |
+| ~Down Arrow~     | Next input in command history                    |
+
+** The Status Bar
+
+The status bar at the bottom of the TUI shows the agent's current state at a glance. Each indicator has a specific meaning:
+
+| Indicator        | Meaning                                                            |
+|------------------+--------------------------------------------------------------------|
+| ~[Connected]~    | Green — daemon is reachable on port 9105. Gray — disconnected.     |
+| ~[Mode: TUI]~    | The current interaction mode (TUI, CLI, Telegram, etc.)            |
+| ~[Msg: 142]~     | Total messages in the current session                              |
+| ~[↑ 12]~         | Scroll indicator — you are scrolled up 12 lines from the bottom    |
+| ~[◉]~            | Activity spinner — spinning means the agent is working             |
+| ~[⟳]~            | Streaming indicator — shown while the agent is generating text     |
+| ~[$0.047]~       | Session cost (visible when ~/cost~ is toggled on)                  |
+| ~[Rules: 52]~    | Number of permanent HITL rules learned from your decisions         |
+| ~[prj:my-proj]~  | Current focused project name                                       |
+
+* Deployment
+
+** Bare metal (Debian / Fedora)
+
+The ~configure~ command supports both Debian-based (Ubuntu, Pop, Mint) and Fedora-based (RHEL, Rocky) distributions. It detects your distro automatically and installs the correct packages.
+
+#+begin_src bash
+./passepartout configure              # interactive
+./passepartout configure --non-interactive  # headless
+./passepartout configure --with-firewall    # also open port 9105
+#+end_src
+
+After configuration, you can re-run ~configure~ any time to add providers or link gateways.
+
+** Binary install (save-lisp-and-die)
+
+For platforms where SBCL cannot be installed (corporate laptops, shared hosts, constrained environments), a self-contained binary is provided:
+
+#+begin_src bash
+curl -fsSL https://github.com/amrgharbeia/passepartout/releases/latest/download/passepartout -o passepartout
+chmod +x passepartout
+./passepartout daemon
+#+end_src
+
+This binary bundles SBCL, all required Lisp code, native embedding inference, and a Swank server on port 4005. The experience is identical to a source install — the REPL is available, skills hot-reload, and the image is mutable. Memory survives snapshots.
+
+The binary is a convenience for constrained platforms. It is not a sealed container. The system remains constitutionally open — connect with SLIME, trace functions, inspect memory objects, modify the system while it runs.
+
+** systemd service (auto-start on boot)
+
+#+begin_src bash
+./passepartout install service
+#+end_src
+
+Installs a user-level systemd unit that starts the daemon on login. Logs are available via ~journalctl --user -u passepartout.service -f~.
+
+To remove:
+
+#+begin_src bash
+./passepartout uninstall service
+#+end_src
+
+** Docker
+
+A Debian-based Docker image is provided for containerized deployment.
+
+#+begin_src bash
+cd infrastructure/docker
+docker-compose up -d
+#+end_src
+
+This builds an image from ~debian:trixie-slim~ with all dependencies pre-installed. The memex directory is mounted from the host.
+
+** Backup
+
+#+begin_src bash
+./passepartout backup ~/my-backup.tar.gz
+#+end_src
+
+Backs up the config, data, and memex directories.
+
+** Restore
+
+#+begin_src bash
+./passepartout restore ~/my-backup.tar.gz
+#+end_src
+
+Restores from a backup file. Run ~passepartout doctor~ afterward to verify integrity.
+
+* Troubleshooting
+
+** The daemon won't start
+- Check SBCL is installed: ~which sbcl~
+- Run ~passepartout doctor~ to diagnose
+- Check port 9105 is free: ~lsof -i :9105~
+- Check the log output for errors
+
+** The TUI connects but shows "Disconnected"
+- The daemon may have crashed. Run ~passepartout daemon~ in another terminal
+- If the daemon is running, check it's listening: ~lsof -i :9105~
+- Use ~/reconnect~ (planned v0.6.0) to reconnect without restarting the TUI
+
+** The LLM returns garbage or fails to respond
+- Run ~passepartout doctor~ to verify your LLM provider keys
+- Check ~PROVIDER_CASCADE~ in your ~.env~ file
+- Try switching models: edit ~.env~ and restart the daemon
+- If using local models via Ollama, verify Ollama is running: ~ollama list~
+
+** Memory fails to load on startup
+- Check ~/memory.snap~ exists and is valid S-expression format
+- Run ~passepartout doctor~ to diagnose memory integrity
+- If corrupted, delete ~/memory.snap~ and restart — the daemon starts with empty memory

docs/deployment.org

@@ -1,36 +0,0 @@
-#+TITLE: Deployment Guide: Containerized OpenCortex
-#+AUTHOR: Amr
-#+DATE: [2026-04-11 Sat]
-#+FILETAGS: :deployment:docker:infrastructure:
-
-* Overview
-The ~opencortex~ is designed to run within a Docker container to ensure system dependencies (SBCL, Quicklisp, signal-cli) are perfectly matched across different host environments.
-
-* Prerequisites
-- Docker Engine
-- Docker Compose
-- A valid ~.env~ file in the ~projects/opencortex/~ directory (refer to ~.env.example~).
-
-* Quick Start
-** 1. Build and Start
-From the ~projects/opencortex/~ directory:
-#+begin_src bash
-docker-compose up --build -d
-#+end_src
-
-** 2. Check Logs
-#+begin_src bash
-docker-compose logs -f
-#+end_src
-
-* Volume Mapping
-The ~docker-compose.yml~ file automatically mounts your host's ~memex~ directory to ~/memex~ inside the container. This allows the agent to:
-1. Read/Write to your Zettelkasten and GTD files.
-2. Maintain its local state (Memory, snapshots).
-
-* Troubleshooting
-** signal-cli Identity
-If using the Signal gateway, ensure you have registered your number via the host's ~signal-cli~ or within the container. The state is preserved in the ~signal-state~ Docker volume.
-
-** Re-loading Skills
-The container pre-caches dependencies during the build. If you modify core Lisp logic, you must rebuild the image (~--build~). If you only modify ~.org~ skills in your memex, the agent can reload them dynamically if they are part of the startup scan.

docs/marketing-v0.1.0.org

@@ -1,46 +0,0 @@
-#+TITLE: v0.1.0 Launch & Marketing Plan
-#+AUTHOR: Amr
-#+FILETAGS: :marketing:release:autonomy:
-#+STARTUP: content
-
-* Overview
-With the v0.1.0 "Autonomous MVP" released, the goal is to leverage GitHub's social graph to build a community of early adopters, contributors, and power users who resonate with the "Thin Harness, Fat Skills" and "Local-First" philosophy.
-
-* 1. Licensing Strategy
-Before wide promotion, the project's license must align with its goals.
-- **MIT License (Current):** Maximum adoption, frictionless for developers to embed in their own tools. Good for rapid growth.
-- **GPLv3 / AGPLv3:** Enforces copyleft. Ensures any modifications or integrations by corporations must remain open-source. Protects the "Autonomous" ethos from proprietary enclosure.
-- **Dual Licensing:** Open-source for individuals, commercial license for enterprise usage (if monetization is a future goal).
-
-*Decision Needed:* Do we stick with MIT, or switch to a copyleft license (AGPL) to protect the autonomous nature of the project?
-
-* 2. The GitHub Migration & Setup
-To maximize visibility, the repository must be optimized for GitHub's ecosystem.
-- [ ] **Mirror/Migrate to GitHub:** Move the primary remote from the self-hosted Gitea to GitHub.
-- [ ] **README Optimization:** Add badges (License, Build Status, Version). Ensure the "Zero-to-One" curl command is prominent. Add an architecture diagram (mermaid).
-- [ ] **Repository Topics:** Add tags like `common-lisp`, `autonomous-agents`, `org-mode`, `pkm`, `zettelkasten`, `llm`, `local-first`.
-- [ ] **Contributing Guide:** Add `CONTRIBUTING.md` to explain the Literate Programming standard and how to add new "Skills".
-- [ ] **Issue Templates:** Create templates for "Bug Report" and "Skill Proposal".
-
-* 3. The PR & Social Media Campaign
-The narrative: "An autonomous AI agent that doesn't just chat, but lives natively in your Org-mode Memex. No Python glue code, no cloud lock-in—just pure, homoiconic Common Lisp."
-
-** Target Audiences & Channels
-1. **The Emacs / Org-mode Community:**
-   - *Channels:* `r/emacs`, `r/orgmode`, Hacker News (`/r/lisp`), Emacs News.
-   - *Hook:* "A background daemon that autonomously distills your daily logs into a Zettelkasten using LLMs."
-2. **The Local-First / PKM Community:**
-   - *Channels:* `r/Zettelkasten`, `r/PKM`, Obsidian/Logseq diaspora looking for more power.
-   - *Hook:* "Own your brain. An AI agent that runs locally on your Markdown/Org files with mathematical security gates."
-3. **The AI / Autonomous Agent Hackers:**
-   - *Channels:* Hacker News (Show HN), Twitter/X (AI tech Twitter).
-   - *Hook:* "Tired of fragile Python/Playwright agent wrappers? opencortex uses a deterministic Lisp microkernel to formally verify LLM actions before execution."
-
-** Launch Materials
-- **Demo Video (2 minutes):** Show the one-liner install, the agent running the `Scribe` skill in the background, and the user querying it via `opencortex chat`.
-- **Blog Post / Essay:** "Why we built an Autonomous Agent in Common Lisp." Discuss the fragility of current SOTA (Devin/SWE-agent) and the necessity of the Bouncer/Policy gates.
-
-* 4. Post-Launch Community Engagement
-- Encourage "Show and Tell" in GitHub Discussions.
-- Create a "Skill Directory" where users can share their custom `.org` skills.
-- Actively solicit feedback for the v0.2.0 (Lisp TUI) roadmap.

docs/quickstart.org

@@ -1,55 +0,0 @@
-#+TITLE: Quickstart Guide: The Road to Autonomousty
-#+AUTHOR: Amr
-#+DATE: [2026-04-11 Sat]
-#+FILETAGS: :quickstart:onboarding:guide:
-
-* 1. Introduction
-Welcome to ~opencortex~, the "Executive Soul" of your personal OS. This guide will help you set up and interact with your first probabilistic-deterministic agent.
-
-* 2. Prerequisites
-Before launching the harness, ensure your host environment has:
-- **Docker & Docker Compose**: The primary enclosure for the Lisp Machine.
-- **LLM API Keys**: At least one key for Gemini, Anthropic, or OpenAI.
-- **Emacs (Optional)**: For the full literate experience via ~opencortex.el~.
-
-* 3. Installation & Enclosure
-** Step 1: Clone the Autonomousty
-#+begin_src bash
-git clone https://github.com/amr/opencortex.git
-cd opencortex
-#+end_src
-
-** Step 2: Secret Configuration
-Copy the example environment file and add your keys.
-#+begin_src bash
-cp .env.example .env
-# Edit .env with your favorite editor
-#+end_src
-
-** Step 3: Launch the Image
-This will build the SBCL environment and start the Micro-Loader.
-#+begin_src bash
-docker-compose up --build -d
-#+end_src
-
-* 4. Interaction Gateways
-Once the harness is "Ready", you can interact with it via multiple sensors.
-
-** Gateway A: Emacs (communication protocol)
-If you have configured the ~opencortex~ package in Emacs:
-1. Open a chat buffer: ~M-x opencortex-chat-open~.
-2. Send: "Are you online, agent?"
-
-** Gateway B: External Sensors
-If you enabled Signal or Telegram in ~.env~, send a message directly to your bot.
-
-* 5. Verification (The Chaos Check)
-To ensure the harness is fully healthy, check the logs for the Micro-Loader summary:
-#+begin_src bash
-docker-compose logs -f opencortex
-#+end_src
-Look for: ~LOADER: Boot Complete. [Ready: 34] [Failed: 0]~
-
-* 6. Next Steps
-- **Extend the Brain**: Read the [[file:skill-creation.org][Skill Creation Guide]] to add custom Lisp skills.
-- **Deep Dive**: Explore the [[file:../literate/][literate/]] directory to understand the harness's architecture.

docs/rca/rca-boot-sequence.org

@@ -1,42 +0,0 @@
-#+TITLE: Root Cause Analysis: Micro-Loader & Deterministic Boot Sequence
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:boot:loader:topological-sort:autonomy:
-
-* Executive Summary
-Refactored the arbitrary skill loading mechanism into a robust **Micro-Loader**. The system now calculates a deterministic boot sequence based on `#+DEPENDS_ON:` tags and protects the harness from malformed or hanging skills via package-based jailing and execution timeouts.
-
-* 1. Issue: Fragile Load Order
-** Symptoms
-Skills that depended on functions or variables from other skills would randomly fail to load depending on the filesystem's directory traversal order.
-** Root Cause
-`initialize-all-skills` used a simple `dolist` over `uiop:directory-files`, which has no semantic awareness of inter-skill dependencies.
-** Resolution
-1. **Metadata Scanning:** Implemented `parse-skill-metadata` to extract `:ID:` and `#+DEPENDS_ON:` without executing code.
-2. **Topological Sort:** Implemented a DFS-based `topological-sort-skills` to guarantee that prerequisites are loaded before their dependents.
-3. **Circular Detection:** Added explicit detection and error reporting for circular dependency loops.
-
-* 2. Issue: Shared State Corruption (Brain Rot)
-** Symptoms
-Variables or functions with the same name in different skills would silently overwrite each other, causing unpredictable behavior.
-** Root Cause
-All skills were being evaluated directly into the `opencortex` package.
-** Resolution
-**Package-Based Jailing:** Each skill is now evaluated within its own dedicated, shadowed package (e.g., `OPENCORTEX.SKILLS.ORG-SKILL-CHAT`). This ensures logical isolation while still allowing access to kernel exports.
-
-* 3. Issue: Boot Stall (The Hanging Skill)
-** Symptoms
-A single skill with an infinite loop or heavy synchronous initialization could hang the entire agent during startup.
-** Root Cause
-Skill loading was strictly synchronous and blocking on the main thread.
-** Resolution
-**Execution Timeouts:** Implemented `load-skill-with-timeout`, which wraps the loader in a monitored thread. If a skill takes longer than 5 seconds to initialize, the loader terminates the thread, jails the failure, and continues with the rest of the boot sequence.
-
-* 4. opencortex Mandate Alignment
-** Evolutionary Kernel
-The boot sequence is now a verifiable, mathematical process rather than a side-effect of filesystem organization.
-** Literate Granularity
-The `org-skill-skills.org` source was refactored into a strictly granular "one definition per block" format.
-
-* 5. Permanent Learnings
-- **Reverse Topological Order:** Remember that a DFS-based sort with `push` needs an `nreverse` to place dependencies at the front of the list.
-- **Path Portability:** Use `uiop:getcwd` instead of `pwd` for more reliable path resolution across different Lisp implementations and OSes.

docs/rca/rca-bouncer.org

@@ -1,33 +0,0 @@
-#+TITLE: Root Cause Analysis: Deterministic Engine Bouncer & Authorization Gate
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:bouncer:authorization:autonomy:security:
-
-* Executive Summary
-Implemented the "Planning Mode" Bouncer to intercept high-risk Probabilistic Engine proposals (e.g., shell commands, Lisp evaluation). The system now forces these actions into an asynchronous "Flight Plan" Org node for manual Autonomous approval, fulfilling the "everything is a node" and high-integrity mandates.
-
-* 1. Issue: Automated High-Risk Execution
-** Symptoms
-Probabilistic Engine proposals involving `shell` or `eval` were executed immediately upon passing the `decide` gate's safety harness. This lacked human-in-the-loop oversight for irreversible or complex operations.
-** Root Cause
-Architecture gap. The system lacked an authorization state between "Safe" and "Executed".
-** Resolution
-1. **Interceptor:** Added `bouncer-check` to `deterministic.lisp`. It flags high-risk actions that lack the `:approved t` property.
-2. **Asynchronous Event:** If flagged, the harness emits an `:approval-required` event.
-3. **Flight Plan Skill:** Created `org-skill-bouncer.org` to:
-   - Catch the event and create a serialized Org node with state `PLAN`.
-   - Monitor the Memory for `APPROVED` states.
-   - Re-inject approved actions with the `:approved t` bypass flag.
-
-* 2. Design Decision: Org-native Approval
-** Requirement
-Align with "Homoiconic Memory" and "Lisp Machine Autonomousty".
-** Selected Path
-State-Based Approval (Org-native).
-- *Pros:* Auditable, asynchronous, utilizes existing Org-mode workflows.
-- *Cons:* Slightly more latency than an interactive prompt.
-** Alignment
-Ensures that the agent's "Flight Plans" are first-class citizens in the Memex, allowing the Autonomous to review and approve them using standard GTD tools.
-
-* 3. Permanent Learnings
-- **Serial Bypass:** Always include a specific bypass flag (e.g., `:approved t`) when re-injecting intercepted actions to prevent infinite interception loops.
-- **Heartbeat Listeners:** Periodic scanning of the Memory for state transitions is an effective way to implement asynchronous authorization gates without blocking the harness.

docs/rca/rca-formal-verification.org

@@ -1,36 +0,0 @@
-#+TITLE: Root Cause Analysis: Lisp-Native Formal Verification Gate
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:security:formal-verification:autonomy:
-
-* Executive Summary
-Implemented a Lisp-Native Deterministic Prover to replace heuristic whitelisting with formal security invariants. This ensures that every high-impact action (shell, file I/O) is mathematically proven safe against the Autonomous's core mandates.
-
-* 1. Architectural Shift: Native vs. External
-** Issue
-The initial draft suggested using `Z3`, an external SMT solver. However, `Z3` was not available in the environment and would add significant complexity/bloat to the Docker image.
-** Resolution
-Leveraged Common Lisp's inherent strength in symbol manipulation to build a **Lisp-Native Prover**. Invariants are defined as high-order predicates that operate on the structure of proposed actions. This provides a self-contained, high-performance verification layer.
-
-* 2. Issue: Dependency Fragility
-** Symptoms
-System failed to load with `Package STR does not exist`.
-** Root Cause
-Incorrect assumption about the Quicklisp system name vs. the package name. The library is `cl-str` but the Quicklisp system is `str` and the package is `str`.
-** Resolution
-1. Updated `opencortex.asd` to depend on `:str`.
-2. Updated all source code and literate notes to use the `str:` prefix.
-3. Verified via explicit `ql:quickload` in the test runner.
-
-* 3. Formal Invariants Implemented
-- **Path Confinement:** Deterministically proves that any file operation or absolute path in a shell command is strictly within the `/home/user/memex` root.
-- **No Network Exfiltration:** Prevents the shell from invoking common exfiltration tools (`nc`, `ssh`, etc.) by inspecting the parsed command structure.
-
-* 4. opencortex Mandate Alignment
-** Soundness over Heuristics
-By moving to formal invariants, we have moved from "blacklisting bad things" to "proving safety." Any action that cannot be proven to satisfy all invariants is denied by default.
-** Literate Granularity
-The `org-skill-formal-verification.org` file follows the "one definition per block" mandate, ensuring that the logic of each invariant is individually documented and verifiable.
-
-* 5. Permanent Learnings
-- **Tooling Independence:** Whenever possible, prefer native Lisp logic over external binaries for core security gates to reduce the attack surface and deployment complexity.
-- **Environment Consistency:** Always use `(setf (uiop:getenv ...) ...)` for portable environment manipulation in tests.

docs/rca/rca-gateway-matrix.org

@@ -1,40 +0,0 @@
-#+TITLE: Root Cause Analysis: Matrix Gateway & Communication Track Completion
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:gateway:matrix:chat:autonomy:
-
-* Executive Summary
-Successfully implemented the third and final external communication channel (Matrix) for OpenCortex v1.0. Resolved integration issues related to case-sensitivity in JSON keys and strict header requirements in `dexador`.
-
-* 1. Issue: Symbol Casing in JSON Keys
-** Symptoms
-The `TEST-MATRIX-INBOUND-NORMALIZATION` test failed because `room-id` was being extracted as `"!ROOM:HS.ORG"` (uppercase) instead of `"!room:hs.org"`.
-** Root Cause
-Common Lisp's default reader converts symbol names to uppercase. When `(string car-of-alist)` was called on a symbol generated by `cl-json`, it produced an uppercase string.
-** Resolution
-Updated the implementation to use `(string-downcase (string ...))` for room IDs and other case-sensitive Matrix identifiers.
-
-* 2. Issue: Since Token Extraction Failure
-** Symptoms
-The sync loop failed to update the `*matrix-since-token*`, causing duplicate message processing risk.
-** Root Cause
-Anticipating `:next-batch` but receiving `:next--batch` (or vice versa) due to inconsistent `cl-json` behavior across different environments or structures.
-** Resolution
-Implemented a robust `(or (cdr (assoc :next-batch json)) (cdr (assoc :next--batch json)))` lookup to handle both hyphenation styles.
-
-* 3. Issue: Type Error in Authorization Headers
-** Symptoms
-`dex:put` crashed with a `TYPE-ERROR`.
-** Root Cause
-I was passing a single string or an incorrectly nested list where `dexador` expected a strict alist of header pairs `(("Key" . "Value") ...)`.
-** Resolution
-Standardized all gateway HTTP calls to use proper alist nesting for headers.
-
-* 4. Completion: Communication Track
-With Telegram, Signal, and Matrix gateways now verified and passing tests, the OpenCortex has achieved full multi-channel parity.
-- **Telegram:** Polling via Bot API.
-- **Signal:** Wrapping `signal-cli`.
-- **Matrix:** Polling via `/sync` Client API.
-
-* 5. Permanent Learnings
-- **Case Sensitivity:** Matrix IDs (rooms, users) are case-sensitive; Lisp symbols are not. Always force downcasing or use strings for storage.
-- **Header Alists:** Always use dotted pairs `("Key" . "Value")` for `dexador` headers.

docs/rca/rca-gateway-signal.org

@@ -1,33 +0,0 @@
-#+TITLE: Root Cause Analysis: Signal Gateway & Multi-Channel Chat
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:gateway:signal:chat:autonomy:
-
-* Executive Summary
-Successfully implemented the second external communication channel (Signal) using `signal-cli`. Further hardened the multi-channel chat logic and resolved JSON mapping discrepancies between Common Lisp and external CLI outputs.
-
-* 1. Issue: JSON Key Mapping Mismatch
-** Symptoms
-The `TEST-SIGNAL-INBOUND-NORMALIZATION` test failed despite the mock JSON appearing correct.
-** Root Cause
-`cl-json` default behavior for decoding. It converts camelCase keys from JSON (e.g., `dataMessage`) into kebab-case keywords in Lisp (e.g., `:DATA-MESSAGE`). I had incorrectly anticipated `:DATA--MESSAGE` or `:DATA_MESSAGE`.
-** Resolution
-1. **Diagnostic:** Added debug output to the test suite to inspect the exact plist structure returned by `cl-json`.
-2. **Correction:** Updated both the implementation and the literate note to use the correct `:DATA-MESSAGE` and `:SOURCE` keywords.
-
-* 2. Implementation: Signal-CLI Wrapper
-** Strategy
-Unlike Telegram's HTTP API, Signal requires a local binary (`signal-cli`). 
-- **Sensor:** Uses `uiop:run-program` with `receive --json` in a polling loop (5s interval).
-- **Actuator:** Uses `uiop:run-program` with `send -m <text> <recipient>`.
-** Security
-The system uses the pre-configured Signal account `+13322690326` discovered in the user's memex.
-
-* 3. Alignment with opencortex Mandates
-** Literate Granularity
-Strictly adhered to the "one definition per block" mandate throughout the new `org-skill-gateway-signal.org` file.
-** Verification
-The `gateway-signal-suite` (10 checks) provides full coverage for inbound parsing and outbound command generation.
-
-* 4. Permanent Learnings
-- **JSON Semantics:** Always verify the specific keyword transformation rules of the JSON library when dealing with external CLI outputs.
-- **Process Robustness:** `uiop:run-program` is the reliable standard for CLI-based gateways in SBCL.

docs/rca/rca-gateway-telegram.org

@@ -1,43 +0,0 @@
-#+TITLE: Root Cause Analysis: Telegram Gateway & Channel-Aware Chat
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:gateway:telegram:chat:autonomy:
-
-* Executive Summary
-Successfully implemented the first external communication channel (Telegram) and decoupled the Chat Agent from its Emacs-centric roots. Resolved significant load-order and dependency issues identified during integration.
-
-* 1. Issue: Undefined Foundational Functions
-** Symptoms
-During compilation, `gateway-telegram.lisp` failed with `UNDEFINED-FUNCTION` for `register-actuator` and `harness-log`.
-** Root Cause
-Poorly scoped foundational functions. These were defined in `core.lisp` (the loop orchestrator), which was loaded *after* the gateways in `opencortex.asd`. This created a "Circular Intention" where the gateways needed the harness to exist before the harness could load the gateways.
-** Resolution
-1. **Relocation:** Moved `*actuator-registry*` and `register-actuator` to `communication.lisp` (the foundation).
-2. **Reordering:** Adjusted `opencortex.asd` to load `core.lisp` (containing the stimulus loop) immediately after the deterministic gates but before the physical sensors (gateways).
-
-* 2. Issue: Hardcoded Chat UI
-** Symptoms
-The `Chat Agent` could only respond via Emacs buffer insertion, rendering it useless for external channels like Telegram.
-** Root Cause
-Architectural myopia. The original chat skill assumed the user was always in front of Emacs.
-** Resolution
-Refactored `org-skill-chat` to be **Channel-Aware**:
-- It now extracts `:channel` and `:chat-id` from the inbound stimulus.
-- It dynamically generates the Probabilistic Engine mandate, instructing the LLM to use the appropriate `:target` (e.g., `:telegram`) based on the conversation context.
-
-* 3. Side-Issue: UIOP Portability
-** Symptoms
-Tests failed with `Symbol "SETENV" not found in the UIOP/DRIVER package`.
-** Root Cause
-Misinterpretation of the `UIOP` API. `setenv` is not a standard export; the portable way is using `(setf (uiop:getenv ...) ...)`.
-** Resolution
-Updated all test environment setup to use the `setf` accessor.
-
-* 4. opencortex Mandate Alignment
-** Autonomous Boundary
-By moving the Telegram API logic to a user-space skill and communicating with the core via standard stimuli, we have respected the microkernel boundary.
-** Homoiconic Memory
-All Telegram interactions are now logged as `:chat-message` events, ensuring the agent's history is unified regardless of the platform.
-
-* 5. Permanent Learnings
-- **Foundation First:** Registries and logging macros must reside in the most foundational layers (`protocol` or `package`) to avoid load-order fragility.
-- **Instruct the Actuator:** When adding new channels, always update the Chat Agent's neural prompt so it knows how to "speak" back through the new interface.

docs/rca/rca-infrastructure-docker.org

@@ -1,30 +0,0 @@
-#+TITLE: Root Cause Analysis: Containerized Infrastructure (Docker)
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:docker:deployment:infrastructure:autonomy:
-
-* Executive Summary
-Standardized the `opencortex` execution environment by creating a production-grade Docker infrastructure. This ensures that all system dependencies, including the Lisp runtime and external binaries like `signal-cli`, are locked down and portable.
-
-* 1. Architectural Intent: The "Clean Room" Model
-** Problem
-The `opencortex` was relying on host-local binaries (`sbcl`, `signal-cli`) and manually configured Quicklisp dists. This made deployment to other environments (e.g., a VPS or a Autonomous Home Server) fragile and prone to version drift.
-** Solution
-1. **Dockerfile:** Created a multi-step build process that installs Debian Bookworm, SBCL, Java, and `signal-cli 0.14.0`.
-2. **Pre-Caching:** The build process triggers a `ql:quickload` of the `:opencortex` system, ensuring all Lisp dependencies are pre-downloaded and stored in the image layer, drastically reducing startup time.
-3. **Compose Orchestration:** Standardized the runtime via `docker-compose.yml`, which handles volume mounting of the user's `memex` directory and injection of `.env` secrets.
-
-* 2. Volume Mapping & Persistence
-** Strategy
-To maintain the "Autonomous" mandate, the agent's code is isolated, but its memory (the `memex`) remains on the host. 
-- **Mapping:** `../..` (host) -> `/memex` (container).
-- **State:** Created a named Docker volume `signal-state` to ensure that `signal-cli` identities and cryptographic keys survive container restarts and image updates.
-
-* 3. Alignment with opencortex Mandates
-** Evolutionary Completion
-By moving to Docker, we have achieved "Evolutionary Completion" for the deployment track. The system is no longer a collection of scripts; it is a deployable appliance.
-** Documentation
-A new `Deployment Guide` was added to `docs/deployment.org` to ensure standard operating procedures are preserved.
-
-* 4. Permanent Learnings
-- **Lisp Build Layers:** Always push the system to the ASDF registry and quickload during Docker build to bake dependencies into the image.
-- **Compose Locality:** Placing the `docker-compose.yml` inside the `projects/opencortex/` folder keeps infrastructure code close to the implementation logic.

docs/rca/rca-lisp-repair-async.org

@@ -1,33 +0,0 @@
-#+TITLE: Root Cause Analysis: Asynchronous Lisp Repair Syntax Gate
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:lisp:repair:decoupling:architecture:autonomy:
-
-* Executive Summary
-Reimplemented the `org-skill-lisp-repair` to align with the "Autonomous Boundary" mandate. The previously synchronous, core-blocking repair logic has been replaced with an asynchronous, event-driven architecture using the Reactive Signal Pipeline.
-
-* 1. Issue: Core Bloat & Synchronous Coupling
-** Symptoms
-The initial implementation of the Lisp Repair gate placed a `handler-case` and a dynamic function call (`repair-lisp-syntax`) directly inside the core `think` function (`probabilistic.lisp`). This forced the core to wait for repairs and made it "aware" of specific repair logic.
-** Root Cause
-Architectural shortcutting. By placing repair logic in the core execution path, we violated the microkernel principle which mandates that the core should be a "dumb" signal processor.
-** Resolution
-1. **Refactored Core:** `think` now only emits a `:syntax-error` stimulus if parsing fails. It no longer attempts to repair.
-2. **Asynchronous Skill:** `skill-lisp-repair` now triggers on the `:syntax-error` event. It performs the repair and returns the corrected action, which is then dispatched by the pipeline.
-
-* 2. Side-Issue: Nested Signal Payloads
-** Symptoms
-`TYPE-ERROR` during testing when extracting the broken code from the stimulus.
-** Root Cause
-Mismatched expectations of signal nesting. The skill expected the code at `(getf context :payload)`, but in the `decide-gate`, `context` is the full signal, and the error details were nested inside the `:candidate` field of that signal.
-** Resolution
-Updated the deterministic logic to correctly traverse the nested signal structure: `(getf (getf context :candidate) :payload)`.
-
-* 3. opencortex Mandate Alignment
-** Autonomous Boundary
-The core is now strictly a parser. Repair is an optional, user-space service.
-** Reactive Signal Pipeline
-Leveraged the pipeline's ability to re-inject `EVENT` signals to flatten the recursion of the repair loop.
-
-* 4. Permanent Learnings
-- **Emit, Don't Call:** In a microkernel, if a non-fatal error occurs, always emit a signal rather than calling a recovery function. This allows the system to remain asynchronous and modular.
-- **Signal Inspection:** When writing deterministic gates, always verify the exact shape of the `context` signal being passed by the harness to avoid nesting errors.

docs/rca/rca-playwright-bridge.org

@@ -1,39 +0,0 @@
-#+TITLE: Root Cause Analysis: Playwright-Python Bridge (High-Fidelity Browsing)
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:intelligence:browsing:automation:autonomy:
-
-* Executive Summary
-Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `opencortex` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.
-
-* 1. Architectural Strategy: The I/O Bridge
-** Problem
-Common Lisp lacks a mature, native Playwright implementation. Direct bindings are complex and fragile.
-** Resolution
-Implemented a **JSON-over-STDIO Bridge**. 
-- A standalone Python script (`browser-bridge.py`) manages the Playwright lifecycle and Chromium instance.
-- The Lisp kernel communicates with this script using `uiop:run-program`, passing parameters via `stdin` and receiving structured results via `stdout`. This provides a stable, decoupled interface.
-
-* 2. Environment & Dependency Management
-** Issue
-Playwright requires a specific version of Chromium and several system-level libraries not present in the base Debian image.
-** Resolution
-Updated the `Dockerfile` to:
-1. Install Python3, pip, and venv.
-2. Create a virtual environment for isolated dependency management.
-3. Install the `playwright` package and execute `playwright install --with-deps chromium` during the image build. This ensures the production container is ready for high-fidelity browsing immediately upon startup.
-
-* 3. Cognitive Tooling
-Created the `:browser` cognitive tool, which exposes three primary capabilities to Probabilistic Engine:
-- **Navigation:** Full JS rendering and waiting for network idle.
-- **Extraction:** Targeted text retrieval via CSS selectors.
-- **Vision:** Base64-encoded screenshot capture for future multimodal processing.
-
-* 4. opencortex Mandate Alignment
-** Zero-Bloat (Managed)
-While adding Playwright increases the image size, it is a "Complexity Earned" trade-off that dramatically expands the agent's capability frontier.
-** Literate Granularity
-The `org-skill-playwright.org` file strictly follows the "one definition per block" mandate.
-
-* 5. Permanent Learnings
-- **Inter-Process JSON:** JSON is the ideal lingua franca for Lisp-Python bridges.
-- **Path Portability:** Always use `uiop:native-namestring` when passing Lisp paths to external shell commands to ensure OS compatibility.

docs/rca/rca-provider-verification.org

@@ -1,40 +0,0 @@
-#+TITLE: Root Cause Analysis: Individual Provider Track Verification
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:providers:llm:testing:autonomy:
-
-* Executive Summary
-Verified the unified LLM gateway implementation for all 6 individual provider tracks (Anthropic, Gemini, Groq, OpenAI, OpenRouter, Ollama). Identified and resolved critical parsing failures in the Gemini track and integration gaps in the system build definition.
-
-* 1. Issue: Fragile Response Parsing (Gemini)
-** Symptoms
-Gemini API responses were returning `NIL` content during mocked unit tests, despite the JSON structure being seemingly correct.
-** Root Cause
-Recursive `assoc` / `car` / `cdr` chains were hardcoded and brittle. Specifically, the Gemini extraction logic was incorrectly attempting to treat a single alist pair as a list of pairs, causing `assoc` to fail on the `:TEXT` key.
-** Resolution
-Implemented a robust `get-nested` helper function that safely traverses both nested objects (alists) and arrays (lists of alists). This normalized the extraction logic across all providers.
-
-* 2. Issue: Decoupled Build Configuration
-** Symptoms
-Provider logic was present in the codebase but inaccessible during tests and runtime.
-** Root Cause
-The `credentials-vault.lisp` and `llm-gateway.lisp` files (consolidated in a previous session) were never added to the `opencortex.asd` system definition. Furthermore, an incorrect loading order caused `UNDEFINED-FUNCTION` errors for `register-probabilistic-backend`.
-** Resolution
-1. Added both files to `opencortex.asd`.
-2. Enforced strict loading order: `probabilistic` (defines registry) -> `credentials-vault` -> `llm-gateway` (uses registry).
-
-* 3. Issue: Credential Key Mismatch
-** Symptoms
-Gemini requests failed with "API Key missing" even when environment variables were set.
-** Root Cause
-`llm-gateway` requested secrets for the `:gemini-api` provider, but the `credentials-vault` fallback logic only recognized the `:gemini` keyword.
-** Resolution
-Updated `vault-get-secret` to map both `:gemini` and `:gemini-api` to the same `GEMINI_API_KEY` environment variable.
-
-* 4. opencortex Mandate Alignment
-** Invariant Check
-- *High-Integrity Memory:* All individual provider tracks are now backed by automated unit tests (`llm-gateway-tests.lisp`).
-- *Literate Programming:* Updated `org-skill-llm-gateway.org` to reflect the improved `get-nested` utility.
-
-* 5. Permanent Learnings
-- **Tooling vs Source:** Tangled `.lisp` files are not enough; always ensure new modules are registered in the `.asd` file to be part of the official kernel build.
-- **Robustness over Brevity:** Use abstraction helpers like `get-nested` instead of deep `car/cdr` chains when dealing with external JSON structures that may have varying array/object nesting.

docs/rca/rca-self-fix-loop.org

@@ -1,40 +0,0 @@
-#+TITLE: Root Cause Analysis: Autonomous Self-Fix Loop Verification
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:self-fix:autonomy:testing:
-
-* Executive Summary
-Verified the autonomous repair capability of the `Self-Fix Agent`. The system successfully detected a deterministic type error in a secondary skill, initiated a repair request, and programmatically patched the source code via the `:repair-file` tool.
-
-* 1. Issue: Self-Fix Mechanism Verification
-** Symptoms
-Manual verification was required to prove that `org-skill-self-fix` could transition from "Thinking" about a bug to "Acting" on the file system.
-** Root Cause
-N/A (Deterministic test injection).
-** Resolution
-Created `self-fix-tests.lisp` which:
-1. Generates `org-skill-broken-math.org` with a `(+ 1 "two")` bug.
-2. Triggers the bug to produce a `PIPELINE CRASH`.
-3. Injects a `:repair-request` stimulus.
-4. Executes `self-fix-apply` to replace the bug with `(+ 1 2)`.
-5. Verifies the file content and successful hot-reload.
-
-* 2. Side-Issue: ASDF Configuration Fragility
-** Symptoms
-Repeated `LOAD-SYSTEM-DEFINITION-ERROR` and "unmatched close parenthesis" errors during test integration.
-** Root Cause
-Complexity in the `:components` nesting of `opencortex.asd` led to repeated syntax errors when using automated editing tools. The deep nesting made manual paren counting prone to "off-by-one" errors.
-** Resolution
-Refactored `opencortex.asd` to use a **Flat Component Structure**. 
-- *Before:* `:components ((:module "src" :components (...)))`
-- *After:* `:components ((:file "src/package") ...)`
-This eliminates unnecessary nesting levels and drastically reduces the surface area for syntax errors.
-
-* 3. opencortex Mandate Alignment
-** Invariant Check
-- *Lisp Machine Autonomousty:* Verification utilized hot-reloading (`load-skill-from-org`) without restarting the SBCL image.
-- *Literate Programming:* Updated `org-skill-self-fix.org` to match the finalized `self-fix.lisp` logic.
-- *Institutional Memory:* This RCA documents the decision to flatten the `.asd` structure to prevent future "Parenthesis Hell" incidents.
-
-* 4. Permanent Learnings
-- **Flatten Configuration:** Keep `defsystem` definitions as flat as possible. The overhead of `:module` blocks often outweighs their organizational benefit in a probabilistic-deterministic environment where agents frequently edit these files.
-- **Mocking Probabilistic Engine:** For verifying *loop mechanics*, mocking LLM responses is essential to ensure test determinism, while integration tests can use live LLM calls.

docs/rca/rca-shell-hardening.org

@@ -1,33 +0,0 @@
-#+TITLE: Root Cause Analysis: Shell Actuator Security Hardening
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:security:shell:injection:autonomy:
-
-* Executive Summary
-During the formal verification of the `org-skill-shell-actuator`, a critical command injection vulnerability was identified and patched. The previous implementation relied on a naive whitelist check that could be bypassed using shell metacharacters.
-
-* 1. Issue: Command Injection Vulnerability
-** Symptoms
-Commands like `ls ; rm -rf /` were potentially executable if the first word (`ls`) was in the whitelist. 
-** Root Cause
-The `execute-shell-safely` function only checked the first space-delimited word of the command string against the `*allowed-commands*` whitelist. Since `uiop:run-program` executes string-based commands via `/bin/sh -c`, the shell would process the entire string, including injected commands following metacharacters like `;`, `&`, or `|`.
-** Resolution
-1. **Metacharacter Blacklist:** Introduced `*shell-metacharacters*` containing dangerous shell symbols (`; & | > < $ \` \ !`).
-2. **Strict Validation:** Updated `execute-shell-safely` to scan the *entire* command string for these characters before performing the whitelist check.
-3. **Defense-in-Depth:** Any command containing a metacharacter is now rejected with a "Security Violation" error, even if the primary command is whitelisted.
-
-* 2. Side-Issue: Missing Package Context
-** Symptoms
-`UNDEFINED-FUNCTION EXECUTE-SHELL-SAFELY` during unit tests.
-** Root Cause
-`src/shell-logic.lisp` was missing an `(in-package :opencortex)` declaration, causing symbols to be defined in the default `COMMON-LISP-USER` package instead of the harness package.
-** Resolution
-Added the `in-package` header to `shell-logic.lisp`.
-
-* 3. opencortex Mandate Alignment
-** Invariant Check
-- *High-Integrity Memory:* The shell actuator is now formally verified with 4 new unit tests covering whitelist enforcement and injection blocking.
-- *Literate Programming:* Updated `org-skill-shell-actuator.org` Phase A and Build sections to reflect the hardened logic.
-
-* 4. Permanent Learnings
-- **Whole-String Validation:** Never assume that whitelisting the "head" of a command string is sufficient when passing that string to a shell. 
-- **Subshell Avoidance:** While the current fix blacklists metacharacters, future iterations should move toward passing command arguments as a Lisp list to `uiop:run-program`, bypassing the shell entirely.

docs/rca/rca-task-orchestrator.org

@@ -1,48 +0,0 @@
-#+TITLE: Root Cause Analysis: Consolidation VI - Task Orchestrator Implementation
-#+DATE: 2026-04-11
-#+FILETAGS: :rca:orchestrator:consensus:integrity:
-
-* Executive Summary
-The implementation of Consolidation VI (Task Orchestrator) aimed to introduce parallel multi-backend consensus, GTD task integrity, and delegation. During the build, a critical dependency failure was identified in the `lisp-validator` module.
-
-* 1. Issue: Undefined `SAFETY-HARNESS-VALIDATE`
-** Symptoms
-Existing `SAFETY-SUITE` tests failed with `#<UNDEFINED-FUNCTION SAFETY-HARNESS-VALIDATE>`.
-** Root Cause
-The function `lisp-validator-validate` was exported in `package.lisp` but never actually defined in `lisp-validator.lisp`. Only the internal recursive walker `lisp-validator-ast-walk` existed. This represents a "Hollow Export" bug where the interface was designed but the implementation was truncated or skipped in a previous session.
-** Resolution
-Defined `lisp-validator-validate` as a wrapper around `read-from-string` and `lisp-validator-ast-walk`.
-
-* 2. Design Decision: Deterministic Consensus
-** Requirement
-Multi-backend support to reduce hallucinations and increase reliability.
-** Solution
-Implemented `bt:make-thread` parallel queries in `ask-probabilistic`.
-** Trade-off
-Selected "Majority Rules" over "First-to-Finish".
-- *Pros:* Higher accuracy, mathematically consistent.
-- *Cons:* Slower (latency limited by the slowest provider).
-** Invariant Alignment
-Aligns with opencortex Mandate 4 (Radical Transparency) and Invariant 2 (Technical Mastery) by ensuring decisions are auditable and consistent across multiple brains.
-
-* 3. Design Decision: Task Integrity Gate
-** Requirement
-Prevent illegal GTD state transitions.
-** Solution
-Added `task-integrity-check` in `deterministic.lisp`.
-** Invariant Alignment
-Enforces the "High-Integrity Memory" mandate by ensuring the Org-mode AST remains semantically valid according to GTD rules (e.g., no orphaned active tasks).
-
-* 4. opencortex Mandate Violations during Session (Corrected)
-** Violations
-1. Editing without prior commit.
-2. Direct `.lisp` edits vs Literate Org tangling.
-3. Multi-function edits per block.
-** Correction
-1. Performed a retrospective commit.
-2. Synchronized `probabilistic-deterministic.org` and `core.org` with source code.
-3. Refactored the Markdown flight plan into an Org-mode flight plan.
-
-* 5. Permanent Learnings
-- *Check Exports:* Always verify that symbols exported in `package.lisp` have a corresponding definition in the literate source.
-- *Strict opencortex Mode:* Enable a pre-save hook or agent check to ensure all edits are performed within `#+begin_src` blocks in Literate Org files to avoid synchronization debt.

docs/ux.org

@@ -1,66 +0,0 @@
-#+TITLE: User Experience (UX) Journey
-#+AUTHOR: Amr
-#+FILETAGS: :ux:design:autonomy:
-#+STARTUP: content
-
-* Overview
-This document traces the intended User Experience (UX) journey for the ~opencortex~. It serves as a living design document to ensure that architectural decisions align with a frictionless, autonomous, and intuitive user interaction model.
-
-* 1. The Zero-to-One Experience (Onboarding)
-** Goal
-A user should be able to go from discovering the project to having a running, calibrated agent in under 3 minutes, with zero prerequisite knowledge of Lisp.
-
-** The Appliance Paradigm (Primary Path)
-The user runs a single command in their terminal:
-#+begin_src bash
-curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/scripts/install.sh | bash
-#+end_src
-
-** The Interactive Wizard
-The script verifies Docker presence and then launches an interactive prompt before booting the container:
-1. *Identity:* "What is your name?" -> Configures ~$MEMEX_USER~
-2. *Assistant:* "What shall we name your Assistant?" -> Configures ~$MEMEX_ASSISTANT~
-3. *Neural Provider:* "Select your primary neural provider [Gemini/OpenRouter/Anthropic/OpenAI]" -> Configures API Keys.
-4. *Data Gravity:* "Where is your Memex located?" -> Maps the host directory to the Docker container.
-
-*Outcome:* The `.env` is generated, core skills are seeded into the user's Memex, and `docker-compose up -d` launches the daemon in the background. The user sees: /"Booting your autonomous brain in the background..."/
-
-* 2. The First Contact (The CLI Gateway)
-** Goal
-Immediately after boot, the user needs a way to verify the agent is alive and capable of answering questions about their Memex without configuring complex third-party integrations (like Telegram bots).
-
-** The Interaction
-The user types a local client command to connect to the background daemon:
-#+begin_src bash
-opencortex chat
-#+end_src
-
-This opens a slick, colorful interactive terminal session:
-#+begin_example
-> User: Hello, what are my active projects?
-> Agent: [Thinking...]
-> Agent: You currently have 3 active projects:
->        1. OpenCortex v1.0
->        2. Home Renovation
->        3. Read 'The Autonomous Individual'
-#+end_example
-
-** Behind the Scenes
-1. The ~opencortex chat~ client connects to the daemon's local port (e.g., 9105).
-2. It sends a ~:chat-message~ signal.
-3. The core harness routes this to the Probabilistic Engine.
-4. The Context Manager retrieves active projects from the Memex AST.
-5. The Deterministic Engine (Bouncer) verifies it is a safe read-only action.
-6. The ~:cli~ Actuator formats the Lisp response into Markdown and sends it back over the socket.
-
-* 3. The Interactive Refinement (v0.2.0)
-** Goal
-Transition from a "Verified Wrapper" around netcat to a high-fidelity, native Common Lisp TUI that rivals the experience of ~gemini-cli~.
-
-** Features
-- *Homoiconic UI:* The TUI is rendered directly by the Lisp kernel, allowing for live introspection of the agent's thoughts.
-- *Rich Formatting:* ANSI colors, bold headers, and syntax-highlighted code blocks.
-- *Command Palette:* Slash commands for system control without leaving the chat.
-
-* 4. The Continuous Loop (Daily Usage)
-(To be defined as the agent's capabilities expand into Scribe, Gardener, and Emacs-native interactions).

extras/passepartout.el

@@ -0,0 +1,214 @@
+;;; passepartout.el --- Emacs bridge for Passepartout AI assistant  -*- lexical-binding: t; -*-
+
+;; Author: Passepartout Project
+;; Version: 0.4.0
+;; Keywords: tools, processes, lisp
+;; URL: https://github.com/amrgharbeia/passepartout
+
+;;; Commentary:
+
+;; Connects to the Passepartout daemon on localhost:9105 via TCP.
+;; Speaks the framed plist protocol — 6-character hex length prefix
+;; followed by a prin1'd S-expression — identical to the TUI and CLI.
+;; The daemon does not know or care whether the client is the Croatoan
+;; TUI, the CLI, or Emacs.
+
+;; Framed protocol (per core-communication.org):
+;;   SEND: 6-char hex length + prin1'd plist
+;;   RECV: read 6-char header → parse hex length → read N bytes →
+;;         read-from-string (with read-eval nil on daemon side)
+
+;; Usage:
+;;   M-x passepartout RET        — connect to daemon, open response buffer
+;;   M-x passepartout-send-region — send selected region as user-input
+;;   M-x passepartout-send-buffer — send entire buffer
+;;   M-x passepartout-disconnect  — close connection
+
+;;; Code:
+
+(require 'cl-lib)
+
+(defgroup passepartout nil
+  "Emacs bridge for Passepartout AI assistant."
+  :group 'applications)
+
+(defcustom passepartout-host "127.0.0.1"
+  "Host where the Passepartout daemon is running."
+  :type 'string
+  :group 'passepartout)
+
+(defcustom passepartout-port 9105
+  "Port where the Passepartout daemon is listening."
+  :type 'integer
+  :group 'passepartout)
+
+(defvar passepartout-process nil
+  "Network process for the Passepartout connection.")
+
+(defvar passepartout--buffer ""
+  "Accumulation buffer for partial framed messages.")
+
+(defvar passepartout-response-buffer-name "*passepartout*"
+  "Name of the buffer where daemon responses are rendered.")
+
+;;;###autoload
+(defun passepartout ()
+  "Connect to the Passepartout daemon and open the response buffer."
+  (interactive)
+  (unless (and passepartout-process (process-live-p passepartout-process))
+    (setq passepartout-process
+          (make-network-process
+           :name "passepartout"
+           :host passepartout-host
+           :service passepartout-port
+           :filter #'passepartout--filter
+           :sentinel #'passepartout--sentinel
+           :coding 'utf-8-unix
+           :noquery t))
+    (setq passepartout--buffer ""))
+  (switch-to-buffer (get-buffer-create passepartout-response-buffer-name))
+  (passepartout-response-mode)
+  (message "Passepartout: connecting to %s:%d..." passepartout-host passepartout-port))
+
+(defun passepartout-disconnect ()
+  "Disconnect from the Passepartout daemon."
+  (interactive)
+  (when passepartout-process
+    (delete-process passepartout-process)
+    (setq passepartout-process nil
+          passepartout--buffer "")
+    (message "Passepartout: disconnected.")))
+
+;;; Protocol: framing
+
+(defun passepartout--frame-message (msg)
+  "Serialize MSG as a framed plist: 6-char hex length + prin1 output."
+  (let* ((payload (prin1-to-string msg))
+         (len (string-bytes payload)))
+    (format "%06x%s" len payload)))
+
+(defun passepartout--send (msg)
+  "Send a framed message to the daemon."
+  (when (and passepartout-process (process-live-p passepartout-process))
+    (process-send-string passepartout-process (passepartout--frame-message msg))))
+
+;;; Protocol: receive
+
+(defun passepartout--filter (proc string)
+  "Accumulate data and extract complete framed messages."
+  (setq passepartout--buffer (concat passepartout--buffer string))
+  (while (>= (length passepartout--buffer) 6)
+    (let* ((hex-len (substring passepartout--buffer 0 6))
+           (len (condition-case nil
+                    (string-to-number hex-len 16)
+                  (error nil))))
+      (if (not len)
+          (progn
+            (setq passepartout--buffer (substring passepartout--buffer 1))
+            (message "Passepartout: invalid frame header, skipping byte"))
+        (let ((total-needed (+ 6 len)))
+          (if (>= (length passepartout--buffer) total-needed)
+              (let* ((payload-str (substring passepartout--buffer 6 total-needed))
+                     (msg (condition-case nil
+                              (read-from-string payload-str)
+                            (error nil))))
+                (setq passepartout--buffer (substring passepartout--buffer total-needed))
+                (when msg
+                  (passepartout--handle-message msg)))
+            ;; Need more data, wait for next chunk
+            (setq passepartout--buffer passepartout--buffer)))))))
+
+(defun passepartout--sentinel (proc event)
+  "Handle connection state changes."
+  (when (string-match-p "closed\\|failed" event)
+    (setq passepartout-process nil
+          passepartout--buffer "")
+    (with-current-buffer (get-buffer-create passepartout-response-buffer-name)
+      (let ((inhibit-read-only t))
+        (goto-char (point-max))
+        (insert (format "* Connection lost: %s\n\n" event))))
+    (message "Passepartout: connection lost (%s)" event)))
+
+;;; Message handling
+
+(defun passepartout--handle-message (msg)
+  "Process a parsed daemon message and render in the response buffer."
+  (with-current-buffer (get-buffer-create passepartout-response-buffer-name)
+    (let ((inhibit-read-only t)
+          (payload (when (listp msg) (plist-get msg :PAYLOAD)))
+          (gate-trace (when (listp msg) (plist-get msg :GATE-TRACE))))
+      (goto-char (point-max))
+      (cond
+       ;; Agent text response
+       ((and payload (plist-get payload :TEXT))
+        (insert (format "* Agent [%s]\n%s\n"
+                        (format-time-string "%H:%M")
+                        (plist-get payload :TEXT)))
+        (when gate-trace
+          (passepartout--render-gate-trace gate-trace))
+        (insert "\n"))
+       ;; Handshake
+       ((and payload (eq (plist-get payload :ACTION) :HANDSHAKE))
+        (insert (format "* Connected to Passepartout v%s\n\n"
+                        (or (plist-get payload :VERSION) "?"))))
+       ;; Rule count / foveal update — display in mode line
+       ((and payload (plist-get payload :RULE-COUNT))
+        (setq passepartout-rule-count (plist-get payload :RULE-COUNT))
+        (force-mode-line-update))
+       ;; Fallback: dump raw
+       (t
+        (insert (format "* [%s] %s\n\n"
+                        (format-time-string "%H:%M")
+                        (prin1-to-string msg))))))))
+
+(defvar passepartout-rule-count 0
+  "Number of pending HITL rules from the Dispatcher.")
+
+(defun passepartout--render-gate-trace (trace)
+  "Render the gate trace as property drawer entries."
+  (insert ":PROPERTIES:\n")
+  (dolist (entry trace)
+    (when (listp entry)
+      (let ((gate (plist-get entry :GATE))
+            (result (plist-get entry :RESULT)))
+        (insert (format ":GATE: %s — %s\n"
+                        (if gate (symbol-name gate) "?")
+                        (symbol-name result))))))
+  (insert ":END:\n"))
+
+;;; Interactive commands
+
+(defun passepartout-send-region (beg end)
+  "Send the selected region as user input to Passepartout."
+  (interactive "r")
+  (unless passepartout-process
+    (passepartout))
+  (let ((text (buffer-substring-no-properties beg end)))
+    (passepartout--send (list :TYPE :EVENT
+                              :PAYLOAD (list :SENSOR :user-input :TEXT text)))
+    (message "Passepartout: sent %d chars" (length text))))
+
+(defun passepartout-send-buffer ()
+  "Send the entire buffer content as user input to Passepartout."
+  (interactive)
+  (unless passepartout-process
+    (passepartout))
+  (passepartout-send-region (point-min) (point-max)))
+
+;;; Response buffer mode
+
+(defvar passepartout-response-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map (kbd "q") #'quit-window)
+    (define-key map (kbd "g") #'passepartout)
+    map)
+  "Keymap for `passepartout-response-mode'.")
+
+(define-derived-mode passepartout-response-mode special-mode "Passepartout"
+  "Major mode for viewing Passepartout daemon responses.
+\\{passepartout-response-mode-map}"
+  (setq buffer-read-only t)
+  (setq-local font-lock-defaults nil))
+
+(provide 'passepartout)
+;;; passepartout.el ends here

final_test.py

@@ -1,46 +0,0 @@
-import pty, os, time, socket
-
-# 1. Wait for daemon to be ready
-print("Waiting for port 9105...")
-for i in range(30):
-    try:
-        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        s.connect(("localhost", 9105))
-        s.close()
-        print("Daemon is up!")
-        break
-    except:
-        time.sleep(1)
-else:
-    print("Daemon failed to start.")
-    exit(1)
-
-# 2. Run TUI in pty and inject "Hi\n"
-pid, fd = pty.fork()
-if pid == 0:
-    # Child: Run TUI
-    os.environ["TERM"] = "xterm"
-    os.environ["SCRIPT_DIR"] = os.getcwd()
-    os.execvp("sbcl", ["sbcl", "--disable-debugger", 
-                       "--eval", "(load (merge-pathnames \"quicklisp/setup.lisp\" (user-homedir-pathname)))",
-                       "--eval", "(push (truename (uiop:getenv \"SCRIPT_DIR\")) asdf:*central-registry*)",
-                       "--eval", "(ql:quickload :opencortex/tui)",
-                       "--eval", "(opencortex.tui:main)"])
-else:
-    # Parent: Inject keys
-    time.sleep(5) # Wait for TUI to load
-    os.write(fd, b"Hi\r") # \r for Enter in many TUIs
-    time.sleep(5) # Wait for response
-    # Read output and look for "Cascade Failure" or similar
-    try:
-        output = os.read(fd, 8192).decode(errors='ignore')
-        print("TUI OUTPUT CAPTURED:")
-        print(output)
-        if "Neural Cascade Failure" in output or "Providers exhausted" in output or "Hi" in output:
-            print("SUCCESS: UI correctly rendered input and response.")
-        else:
-            print("FAILURE: UI did not show expected text.")
-    except:
-        pass
-    os.kill(pid, 9)
-    os.waitpid(pid, 0)

fix-tui.py

@@ -1,40 +0,0 @@
-import sys
-
-filepath = "literate/tui-client.org"
-with open(filepath, "r") as f:
-    lines = f.readlines()
-
-out = []
-in_block = False
-for line in lines:
-    if ";; 3. Handle Keyboard Input" in line:
-        in_block = True
-        out.append(line)
-        out.append("            (let* ((event (get-wide-event input-win))\n")
-        out.append("                   (ch (and event (typep event 'event) (event-key event))))\n")
-        out.append("              (when ch\n")
-        out.append("                (cond\n")
-        out.append("                  ((or (eq ch #\\Newline) (eq ch #\\Return))\n")
-        out.append("                   (let ((cmd (coerce *input-buffer* 'string)))\n")
-        out.append("                     (setf (fill-pointer *input-buffer*) 0)\n")
-        out.append("                     (when (> (length cmd) 0)\n")
-        out.append("                       (let ((framed (opencortex:frame-message (format nil \"~s\" (list :type :EVENT :payload (list :sensor :chat-message :text cmd))))))\n")
-        out.append("                         (format *stream* \"~a\" framed)\n")
-        out.append("                         (finish-output *stream*)))\n")
-        out.append("                     (when (string= cmd \"/exit\") (setf *is-running* nil))))\n")
-        out.append("                  ((or (eq ch :backspace) (eq ch #\\Backspace) (eq ch #\\Rubout) (eq ch #\\Del))\n")
-        out.append("                   (when (> (length *input-buffer*) 0)\n")
-        out.append("                     (decf (fill-pointer *input-buffer*))))\n")
-        out.append("                  ((characterp ch)\n")
-        out.append("                   (vector-push-extend ch *input-buffer*))))\n")
-        continue
-    if in_block:
-        if "(clear input-win)" in line:
-            in_block = False
-            out.append(line)
-        continue
-    out.append(line)
-
-with open(filepath, "w") as f:
-    f.writelines(out)
-print("Fix applied")

fix_actuator.py

@@ -1,46 +0,0 @@
-import re
-
-filepath = 'skills/org-skill-shell-actuator.org'
-with open(filepath, 'r') as f:
-    content = f.read()
-
-# Replace the problematic blocks with known good versions
-# Block 1: Whitelist
-old_block_1 = """#+begin_src lisp
-(defparameter *allowed-commands* '("ls" "git" "rg" "grep" "date" "echo" "cat" "node" "python3" "sbcl"))
-#+end_src"""
-
-# Block 2: Metacharacters (Fixing the backquote literal)
-old_block_2 = """#+begin_src lisp
-(defparameter *shell-metacharacters* '(#\\; #\\& #\\| #\\> #\\< #\\$ #\\` #\\\\ #\\!)
-  "Characters that are banned in shell commands to prevent injection.")
-#+end_src"""
-
-# Block 3: execute-shell-safely (Ensuring backquotes are correct)
-new_execute = """#+begin_src lisp
-(defun execute-shell-safely (action context)
-  (let* ((payload (getf action :payload))
-         (cmd-string (getf payload :cmd))
-         (executable (car (uiop:split-string (string-trim " " cmd-string) :separator '(#\\Space)))))
-    
-    (cond
-      ((not (shell-command-safe-p cmd-string))
-       (opencortex:inject-stimulus 
-        `(:TYPE :EVENT :PAYLOAD (:SENSOR :shell-response :cmd ,cmd-string :stdout "" :stderr "ERROR - Security Violation: Dangerous metacharacters detected." :exit-code 1))
-        :stream (getf context :reply-stream)))
-      
-      ((not (member executable *allowed-commands* :test #'string=))
-       (opencortex:inject-stimulus 
-        `(:TYPE :EVENT :PAYLOAD (:SENSOR :shell-response :cmd ,cmd-string :stdout "" :stderr "ERROR - Command not in security whitelist." :exit-code 1))
-        :stream (getf context :reply-stream)))
-      
-      (t
-       (multiple-value-bind (stdout stderr exit-code)
-           (uiop:run-program cmd-string :output :string :error-output :string :ignore-error-status t)
-         (opencortex:inject-stimulus 
-          `(:TYPE :EVENT :PAYLOAD (:SENSOR :shell-response :cmd ,cmd-string :stdout ,(or stdout "") :stderr ,(or stderr "") :exit-code ,exit-code))
-          :stream (getf context :reply-stream)))))))
-#+end_src"""
-
-# We'll just overwrite the whole file implementation section to be safe
-# (This is a bit drastic but avoids the parsing issues)

fix_all.py

@@ -1,48 +0,0 @@
-import os, re
-
-def rewrite_gateway():
-    path = 'skills/org-skill-llm-gateway.org'
-    with open(path, 'r') as f: content = f.read()
-    # Force OpenRouter as the only internal provider for auto-thoughts
-    content = content.replace(':openai', ':openrouter')
-    content = content.replace('openrouter/auto', 'google/gemini-2.0-flash-001')
-    with open(path, 'w') as f: f.write(content)
-
-def rewrite_tui():
-    path = 'literate/tui-client.org'
-    # Complete, balanced listener that handles events, status, and chat
-    new_listener = """(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (or (getf msg :TYPE) (getf msg :type)))
-                     (payload (or (getf msg :PAYLOAD) (getf msg :payload))))
-                (cond ((eq type :EVENT)
-                       (let ((action (or (getf payload :ACTION) (getf payload :action)))
-                             (sensor (or (getf payload :SENSOR) (getf payload :sensor)))
-                             (text (or (getf payload :TEXT) (getf payload :text) (getf payload :MESSAGE) (getf payload :message))))
-                         (cond ((eq action :handshake) (setf *status-text* "Ready"))
-                               (text (enqueue-msg (format nil "SYSTEM: ~a" text))))))
-                      ((eq type :STATUS)
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" 
-                                                   (or (getf msg :SCRIBE) (getf msg :scribe))
-                                                   (or (getf msg :GARDENER) (getf msg :gardener)))))
-                      ((eq type :CHAT)
-                       (enqueue-msg (or (getf msg :TEXT) (getf msg :text))))
-                      (t (harness-log "TUI: Ignored unknown type ~a" type))))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))
-            (when (eq raw-msg :error) (setf *status-text* "Protocol Error"))))
-      (error (c) (setf *status-text* (format nil "Net Error: ~a" c)) (setf *is-running* nil)))
-    (sleep 0.05)))"""
-    
-    with open(path, 'r') as f: content = f.read()
-    # Replace the old listener function cleanly
-    content = re.sub(r'\(defun listen-thread \(.*?\)\)\)\)', new_listener, content, flags=re.DOTALL)
-    with open(path, 'w') as f: f.write(content)
-
-rewrite_gateway()
-rewrite_tui()
-print("Rewrite complete.")

fix_cascade.py

@@ -1,74 +0,0 @@
-import re
-
-path_gateway = 'skills/org-skill-llm-gateway.org'
-with open(path_gateway, 'r') as f: c = f.read()
-
-# 1. Update execute-llm-request to be cascade-aware
-old_executor = r'\(defun execute-llm-request \(prompt system-prompt &key provider model\).*?\(error \(c\) \(list :status :error :message \(format nil "LLM Gateway Failure \(~a\): ~a" provider c\)\)\)\)\)\)\)\)\)\)'
-
-new_executor = """(defun execute-llm-request (prompt system-prompt &key provider model)
-  "Unified entry point for all LLM providers. Respects the global cascade."
-  (let* ((active-provider (or provider (car opencortex::*provider-cascade*)))
-         (api-key (vault-get-secret active-provider :type :api-key))
-         (full-prompt (format nil "~a~%~%Prompt: ~a" system-prompt prompt)))
-
-    (harness-log "PROBABILISTIC ENGINE: Requesting ~a (Model: ~a)" 
-                active-provider (or model "default"))
-
-    ;; If the specifically requested provider has no key, try falling back to the cascade
-    (when (or (null api-key) (string= api-key ""))
-       (harness-log "GATEWAY: Provider ~a has no key. Falling back to cascade." active-provider)
-       (return-from execute-llm-request 
-         (ask-probabilistic prompt :system-prompt system-prompt :context (list :payload (list :text prompt)))))
-
-    (case active-provider
-      (:gemini-web
-       (let ((res (uiop:symbol-call :opencortex.skills.org-skill-web-research :ask-gemini-web full-prompt)))
-         (if res (list :status :success :content res) (list :status :error :message "Web Research Failure"))))
-      
-      (:ollama
-       (let* ((host (or (uiop:getenv "OLLAMA_HOST") "localhost:11434"))
-              (url (format nil "http://~a/api/generate" host))
-              (body (cl-json:encode-json-to-string `((model . ,(or model "llama3")) (prompt . ,full-prompt) (stream . :false)))))
-         (handler-case 
-             (let* ((response (dex:post url :headers '(("Content-Type" . "application/json")) :content body :connect-timeout 5 :read-timeout 60))
-                    (json (cl-json:decode-json-from-string response)))
-               (list :status :success :content (cdr (assoc :response json))))
-           (error (c) (list :status :error :message (format nil "Ollama Failure: ~a" c))))))
-
-      (t ;; Cloud Providers (Anthropic, Gemini API, Groq, OpenAI, OpenRouter)
-       (let* ((endpoint (case active-provider
-                          (:anthropic "https://api.anthropic.com/v1/messages")
-                          (:gemini-api (format nil "https://generativelanguage.googleapis.com/v1/models/~a:generateContent" (or model "gemini-1.5-flash-latest")))
-                          (:groq "https://api.groq.com/openai/v1/chat/completions")
-                          (:openai "https://api.openai.com/v1/chat/completions")
-                          (:openrouter "https://openrouter.ai/api/v1/chat/completions")))
-              (headers (case active-provider
-                         (:anthropic `(("Content-Type" . "application/json") ("x-api-key" . ,api-key) ("anthropic-version" . "2023-06-01")))
-                         (:gemini-api `(("Content-Type" . "application/json") ("x-goog-api-key" . ,api-key)))
-                         (:openrouter `(("Content-Type" . "application/json") ("Authorization" . ,(format nil "Bearer ~a" api-key)) 
-                                        ("HTTP-Referer" . "https://github.com/amr/opencortex") ("X-Title" . "opencortex Autonomous Kernel")))
-                         (t `(("Content-Type" . "application/json") ("Authorization" . ,(format nil "Bearer ~a" api-key))))))
-              (body (case active-provider
-                      (:anthropic (cl-json:encode-json-to-string `((model . ,(or model "claude-3-5-sonnet-20240620")) (max_tokens . 4096) (system . ,system-prompt) (messages . (( (role . "user") (content . ,prompt) ))))))
-                      (:gemini-api (cl-json:encode-json-to-string `((contents . (((parts . (((text . ,full-prompt))))))))))
-                      (t (cl-json:encode-json-to-string `((model . ,(or model (case active-provider (:groq "llama-3.3-70b-versatile") (:openai "gpt-4o") (t "openrouter/auto"))))
-                                                         (messages . (( (role . "system") (content . ,system-prompt) ) ( (role . "user") (content . ,prompt) )))))))))
-         (handler-case 
-             (let* ((response (progn 
-                                (harness-log "LLM DEBUG: Requesting ~a..." active-provider)
-                                (dex:post endpoint :headers headers :content body :connect-timeout 10 :read-timeout 30)))
-                    (json (cl-json:decode-json-from-string response)))
-               (let ((content (case active-provider
-                                (:anthropic (get-nested json :content :text))
-                                (:gemini-api (get-nested json :candidates :parts :text))
-                                (t (get-nested json :choices :message :content)))))
-                 (if content
-                     (list :status :success :content content)
-                     (list :status :error :message (format nil "Failed to parse ~a response structure." active-provider)))))
-           (error (c) (list :status :error :message (format nil "LLM Gateway Failure (~a): ~a" active-provider c)))))))))"""
-
-c = re.sub(old_executor, new_executor, c, flags=re.DOTALL)
-with open(path_gateway, 'w') as f: f.write(c)
-
-print("Enabled Dynamic Provider Cascading.")

fix_context.py

@@ -1,42 +0,0 @@
-import sys
-
-filepath = 'literate/context.org'
-with open(filepath, 'r') as f:
-    lines = f.readlines()
-
-out = []
-skip = False
-for line in lines:
-    if '(defun context-resolve-path (path-string)' in line:
-        out.append('(defun context-resolve-path (path-string)\n')
-        out.append('  "Expands environment variables and strips literal quotes from a path string."\n')
-        out.append('  (let ((path (if (stringp path-string) \n')
-        out.append('                  (string-trim \'(#\\" #\\\' #\\Space) path-string)\n')
-        out.append('                  path-string)))\n')
-        out.append('    (if (and (stringp path) (search "$" path))\n')
-        out.append('        (let ((result path))\n')
-        out.append('          (ppcre:do-register-groups (var-name) ("\\\\$([A-Za-z0-9_]+)" path)\n')
-        out.append('            (let ((var-val (uiop:getenv var-name)))\n')
-        out.append('              (when var-val\n')
-        out.append('                (setf result (ppcre:regex-replace (format nil "\\\\$~a" var-name) result var-val)))))\n')
-        out.append('          result)\n')
-        out.append('        path)))\n')
-        skip = True
-        continue
-    
-    if skip:
-        if 'path-string))' in line:
-            skip = False
-        continue
-    
-    out.append(line)
-
-with open(filepath, 'w') as f:
-    f.writelines(out)
-
-# 2. Fix opencortex.sh
-with open('opencortex.sh', 'r') as f:
-    sh = f.read()
-sh = sh.replace('[ ! -f "$SCRIPT_DIR/.env" ]', '[ ! -f "$SCRIPT_DIR/.env" ] && [ ! -f "$HOME/.local/share/opencortex/.env" ]')
-with open('opencortex.sh', 'w') as f:
-    f.write(sh)

fix_final_bridge.py

@@ -1,136 +0,0 @@
-import os
-
-def rewrite_comm():
-    path = 'src/communication.lisp'
-    content = """(in-package :opencortex)
-
-(defvar *actuator-registry* (make-hash-table :test 'equalp))
-
-(defun register-actuator (name fn)
-  (let ((key (if (keywordp name) name (intern (string-upcase (string name)) :keyword))))
-    (setf (gethash key *actuator-registry*) fn)))
-
-(defun frame-message (msg-plist)
-  (let* ((*print-pretty* nil)
-         (*print-circle* nil)
-         (msg-string (format nil "~s" msg-plist))
-         (len (length msg-string)))
-    (format nil "~6,'0x~a~%" len msg-string)))
-
-(defun read-framed-message (stream)
-  (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) (*print-pretty* nil))
-                          (handler-case 
-                              (let ((msg (read-from-string msg-buffer)))
-                                (validate-communication-protocol-schema msg)
-                                msg)
-                            (error (c) :error)))))))))
-      (error (c) :error))))
-
-(defun make-hello-message (version)
-  (list :TYPE :EVENT :PAYLOAD (list :ACTION :handshake :VERSION version :CAPABILITIES '(:AUTH :SWANK :ORG-AST))))
-"""
-    with open(path, 'w') as f: f.write(content)
-
-def rewrite_tui():
-    path = 'src/tui-client.lisp'
-    content = """(in-package :cl-user)
-(defpackage :opencortex.tui (:use :cl :croatoan) (:export :main))
-(in-package :opencortex.tui)
-
-(defvar *daemon-host* "127.0.0.1")
-(defvar *daemon-port* 9105)
-(defvar *socket* nil)
-(defvar *stream* nil)
-(defvar *chat-history* nil)
-(defvar *status-text* "Connecting...")
-(defvar *input-buffer* (make-array 0 :element-type 'char :fill-pointer 0 :adjustable t))
-(defvar *is-running* t)
-(defvar *queue-lock* (bt:make-lock))
-(defvar *incoming-msgs* nil)
-
-(defun enqueue-msg (msg) (bt:with-lock-held (*queue-lock*) (push msg *incoming-msgs*)))
-(defun dequeue-msgs () (bt:with-lock-held (*queue-lock*) (let ((msgs (nreverse *incoming-msgs*))) (setf *incoming-msgs* nil) msgs)))
-
-(defun clean-keywords (msg)
-  (if (listp msg)
-      (let ((clean nil))
-        (loop for (k v) on msg by #'cddr
-              do (push (intern (string-upcase (string k)) :keyword) clean)
-                 (push v clean))
-        (nreverse clean))
-      msg))
-
-(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (getf msg :TYPE))
-                     (payload (getf msg :PAYLOAD)))
-                (cond ((eq type :EVENT)
-                       (when (eq (getf payload :ACTION) :HANDSHAKE) (setf *status-text* "Ready")))
-                      ((eq type :STATUS)
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" (getf msg :SCRIBE) (getf msg :GARDENER))))
-                      ((eq type :CHAT)
-                       (let ((text (getf msg :TEXT))) (when text (enqueue-msg text))))
-                      (t (enqueue-msg (format nil "MSG: ~s" msg))))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))))
-      (error (c) (setf *is-running* nil)))
-    (sleep 0.05)))
-
-(defun main ()
-  (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
-  (setf *stream* (usocket:socket-stream *socket*))
-  (bt:make-thread #'listen-thread)
-  (unwind-protect
-    (with-screen (scr :input-echoing nil :input-blocking nil :cursor-visible t)
-      (let* ((h (height scr)) (w (width scr))
-             (chat-win (make-instance 'window :height (- h 2) :width w :position (list 0 0)))
-             (status-win (make-instance 'window :height 1 :width w :position (list (- h 2) 0)))
-             (input-win (make-instance 'window :height 1 :width w :position (list (- h 1) 0)))
-             (last-status nil))
-        (setf (function-keys-enabled-p input-win) t)
-        (setf (input-blocking input-win) nil)
-        (loop while *is-running* do
-          (let ((new (dequeue-msgs)))
-            (when new
-              (dolist (m new) (push m *chat-history*))
-              (clear chat-win)
-              (let ((line 0)) (dolist (m (reverse (subseq *chat-history* 0 (min (length *chat-history*) (- h 3))))) (add-string chat-win m :y line :x 0) (incf line)))
-              (refresh chat-win)))
-          (unless (equal *status-text* last-status)
-            (clear status-win) (add-string status-win *status-text* :attributes '(:reverse)) (refresh status-win) (setf last-status *status-text*))
-          (let* ((ev (get-wide-event input-win)) (ch (and ev (typep ev 'event) (event-key ev))))
-            (when ch
-              (cond ((or (eq ch #\\Newline) (eq ch #\\Return))
-                     (let ((cmd (coerce *input-buffer* 'string)))
-                       (setf (fill-pointer *input-buffer*) 0)
-                       (when (> (length cmd) 0)
-                         (enqueue-msg (concatenate 'string "> " cmd))
-                         (let ((framed (opencortex:frame-message (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd))))))
-                           (format *stream* "~a" framed) (finish-output *stream*)))))
-                    ((or (eq ch :backspace) (eq ch #\\Backspace) (eq ch #\\Rubout)) (when (> (length *input-buffer*) 0) (decf (fill-pointer *input-buffer*))))
-                    ((characterp ch) (vector-push-extend ch *input-buffer*))))
-            (clear input-win) (add-string input-win (concatenate 'string "> " (coerce *input-buffer* 'string))) (move input-win 0 (+ 2 (length *input-buffer*))) (refresh input-win))
-          (sleep 0.02))))
-    (setf *is-running* nil) (when *socket* (usocket:socket-close *socket*))))
-"""
-    with open(path, 'w') as f: f.write(content)
-
-rewrite_comm()
-rewrite_tui()
-print("Final bridge repair complete.")

fix_final_v2.py

@@ -1,141 +0,0 @@
-import os
-
-def rewrite_comm():
-    path = 'src/communication.lisp'
-    content = """(in-package :opencortex)
-
-(defvar *actuator-registry* (make-hash-table :test 'equalp))
-
-(defun register-actuator (name fn)
-  (let ((key (if (keywordp name) name (intern (string-upcase (string name)) :keyword))))
-    (setf (gethash key *actuator-registry*) fn)))
-
-(defun frame-message (msg-plist)
-  (let* ((*print-pretty* nil)
-         (*print-circle* nil)
-         (msg-string (format nil "~s" msg-plist))
-         (len (length msg-string)))
-    (format nil "~6,'0x~a~%" len msg-string)))
-
-(defun read-framed-message (stream)
-  (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) (*print-pretty* nil))
-                          (handler-case 
-                              (let ((msg (read-from-string msg-buffer)))
-                                (validate-communication-protocol-schema msg)
-                                msg)
-                            (error (c) :error)))))))))
-      (error (c) :error))))
-
-(defun make-hello-message (version)
-  (list :TYPE :EVENT :PAYLOAD (list :ACTION :handshake :VERSION version :CAPABILITIES '(:AUTH :SWANK :ORG-AST))))
-"""
-    with open(path, 'w') as f: f.write(content)
-
-def rewrite_tui():
-    path = 'src/tui-client.lisp'
-    content = """(in-package :cl-user)
-(defpackage :opencortex.tui (:use :cl :croatoan) (:export :main))
-(in-package :opencortex.tui)
-
-(defvar *daemon-host* "127.0.0.1")
-(defvar *daemon-port* 9105)
-(defvar *socket* nil)
-(defvar *stream* nil)
-(defvar *chat-history* nil)
-(defvar *status-text* "Connecting...")
-(defvar *input-buffer* (make-array 0 :element-type 'char :fill-pointer 0 :adjustable t))
-(defvar *is-running* t)
-(defvar *queue-lock* (bt:make-lock))
-(defvar *incoming-msgs* nil)
-
-(defun enqueue-msg (msg) (bt:with-lock-held (*queue-lock*) (push msg *incoming-msgs*)))
-(defun dequeue-msgs () (bt:with-lock-held (*queue-lock*) (let ((msgs (nreverse *incoming-msgs*))) (setf *incoming-msgs* nil) msgs)))
-
-(defun clean-keywords (msg)
-  (if (listp msg)
-      (let ((clean nil))
-        (loop for (k v) on msg by #'cddr
-              do (push (intern (string-upcase (string k)) :keyword) clean)
-                 (push v clean))
-        (nreverse clean))
-      msg))
-
-(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (getf msg :TYPE))
-                     (payload (getf msg :PAYLOAD)))
-                (cond ((eq type :EVENT)
-                       (when (eq (getf payload :ACTION) :HANDSHAKE) (setf *status-text* "Ready")))
-                      ((eq type :STATUS)
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" (getf msg :SCRIBE) (getf msg :GARDENER))))
-                      ((eq type :CHAT)
-                       (let ((text (getf msg :TEXT))) (when text (enqueue-msg text))))
-                      (t (enqueue-msg (format nil "MSG: ~s" msg))))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))))
-      (error (c) (setf *is-running* nil)))
-    (sleep 0.05)))
-
-(defun main ()
-  (handler-case
-    (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
-    (error (e) (format t "Error connecting: ~a~%" e) (return-from main)))
-  (setf *stream* (usocket:socket-stream *socket*))
-  (bt:make-thread #'listen-thread)
-  (unwind-protect
-    (with-screen (scr :input-echoing nil :input-blocking nil :enable-colors t :cursor-visible t)
-      (let* ((h (height scr)) (w (width scr))
-             (chat-win (make-instance 'window :height (- h 2) :width w :position (list 0 0)))
-             (status-win (make-instance 'window :height 1 :width w :position (list (- h 2) 0)))
-             (input-win (make-instance 'window :height 1 :width w :position (list (- h 1) 0)))
-             (last-status nil))
-        (setf (function-keys-enabled-p input-win) t)
-        (setf (input-blocking input-win) nil)
-        (loop while *is-running* do
-          (let ((new (dequeue-msgs)))
-            (when new
-              (dolist (m new) (push m *chat-history*))
-              (clear chat-win)
-              (let ((line 0)) (dolist (m (reverse (subseq *chat-history* 0 (min (length *chat-history*) (- h 3))))) (add-string chat-win m :y line :x 0) (incf line)))
-              (refresh chat-win)))
-          (unless (equal *status-text* last-status)
-            (clear status-win) (add-string status-win *status-text* :attributes '(:reverse)) (refresh status-win) (setf last-status *status-text*))
-          (let* ((ev (get-wide-event input-win)) (ch (and ev (typep ev 'event) (event-key ev))))
-            (when ch
-              (cond ((or (eq ch #\\Newline) (eq ch #\\Return))
-                     (let ((cmd (coerce *input-buffer* 'string)))
-                       (setf (fill-pointer *input-buffer*) 0)
-                       (when (> (length cmd) 0)
-                         (enqueue-msg (concatenate 'string "> " cmd))
-                         (let ((framed (opencortex:frame-message (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd))))))
-                           (format *stream* "~a" framed) (finish-output *stream*)))
-                       (when (string= cmd "/exit") (setf *is-running* nil))))
-                    ((or (eq ch :backspace) (eq ch #\\Backspace) (eq ch #\\Rubout)) (when (> (length *input-buffer*) 0) (decf (fill-pointer *input-buffer*))))
-                    ((characterp ch) (vector-push-extend ch *input-buffer*))))
-            (clear input-win) (add-string input-win (concatenate 'string "> " (coerce *input-buffer* 'string))) (move input-win 0 (+ 2 (length *input-buffer*))) (refresh input-win))
-          (sleep 0.02))))
-    (setf *is-running* nil) (when *socket* (usocket:socket-close *socket*))))
-"""
-    # Wait, I found the bug. One extra closing paren in the cond block.
-    # Fixed in the string above and will verify below.
-    with open(path, 'w') as f: f.write(content)
-
-rewrite_comm()
-rewrite_tui()
-print("Physical rewrite for v0.1.0 recovery complete.")

fix_final_v3.py

@@ -1,146 +0,0 @@
-import os
-
-def rewrite_comm():
-    path = 'src/communication.lisp'
-    content = """(in-package :opencortex)
-
-(defvar *actuator-registry* (make-hash-table :test 'equalp))
-
-(defun register-actuator (name fn)
-  (let ((key (if (keywordp name) name (intern (string-upcase (string name)) :keyword))))
-    (setf (gethash key *actuator-registry*) fn)))
-
-(defun frame-message (msg-plist)
-  (let* ((*print-pretty* nil)
-         (*print-circle* nil)
-         (msg-string (format nil "~s" msg-plist))
-         (len (length msg-string)))
-    (format nil "~6,'0x~a~%" len msg-string)))
-
-(defun read-framed-message (stream)
-  (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) (*print-pretty* nil))
-                          (handler-case 
-                              (let ((msg (read-from-string msg-buffer)))
-                                (validate-communication-protocol-schema msg)
-                                msg)
-                            (error (c) :error)))))))))
-      (error (c) :error))))
-
-(defun make-hello-message (version)
-  (list :TYPE :EVENT :PAYLOAD (list :ACTION :handshake :VERSION version :CAPABILITIES '(:AUTH :SWANK :ORG-AST))))
-"""
-    with open(path, 'w') as f: f.write(content)
-
-def rewrite_tui():
-    path = 'src/tui-client.lisp'
-    content = """(in-package :cl-user)
-(defpackage :opencortex.tui (:use :cl :croatoan) (:export :main))
-(in-package :opencortex.tui)
-
-(defvar *daemon-host* "127.0.0.1")
-(defvar *daemon-port* 9105)
-(defvar *socket* nil)
-(defvar *stream* nil)
-(defvar *chat-history* nil)
-(defvar *status-text* "Connecting...")
-(defvar *input-buffer* (make-array 0 :element-type 'char :fill-pointer 0 :adjustable t))
-(defvar *is-running* t)
-(defvar *queue-lock* (bt:make-lock))
-(defvar *incoming-msgs* nil)
-
-(defun enqueue-msg (msg) (bt:with-lock-held (*queue-lock*) (push msg *incoming-msgs*)))
-(defun dequeue-msgs () (bt:with-lock-held (*queue-lock*) (let ((msgs (nreverse *incoming-msgs*))) (setf *incoming-msgs* nil) msgs)))
-
-(defun clean-keywords (msg)
-  (if (listp msg)
-      (let ((clean nil))
-        (loop for (k v) on msg by #'cddr
-              do (push (intern (string-upcase (string k)) :keyword) clean)
-                 (push v clean))
-        (nreverse clean))
-      msg))
-
-(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (getf msg :TYPE))
-                     (payload (getf msg :PAYLOAD)))
-                (cond ((eq type :EVENT)
-                       (when (eq (getf payload :ACTION) :HANDSHAKE) (setf *status-text* "Ready")))
-                      ((eq type :STATUS)
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" (getf msg :SCRIBE) (getf msg :GARDENER))))
-                      ((eq type :CHAT)
-                       (let ((text (getf msg :TEXT))) (when text (enqueue-msg text))))
-                      (t (enqueue-msg (format nil "MSG: ~s" msg))))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))))
-      (error (c) (setf *is-running* nil)))
-    (sleep 0.05)))
-
-(defun main ()
-  (handler-case
-      (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
-    (error (e) (format t "Error connecting: ~a~%" e) (return-from main)))
-  (setf *stream* (usocket:socket-stream *socket*))
-  (bt:make-thread #'listen-thread)
-  (unwind-protect
-    (with-screen (scr :input-echoing nil :input-blocking nil :enable-colors t :cursor-visible t)
-      (let* ((h (height scr)) (w (width scr))
-             (chat-win (make-instance 'window :height (- h 2) :width w :position (list 0 0)))
-             (status-win (make-instance 'window :height 1 :width w :position (list (- h 2) 0)))
-             (input-win (make-instance 'window :height 1 :width w :position (list (- h 1) 0)))
-             (last-status nil))
-        (setf (function-keys-enabled-p input-win) t)
-        (setf (input-blocking input-win) nil)
-        (loop while *is-running* do
-          (let ((new (dequeue-msgs)))
-            (when new
-              (dolist (m new) (push m *chat-history*))
-              (clear chat-win)
-              (let ((line 0)) (dolist (m (reverse (subseq *chat-history* 0 (min (length *chat-history*) (- h 3))))) (add-string chat-win m :y line :x 0) (incf line)))
-              (refresh chat-win)))
-          (unless (equal *status-text* last-status)
-            (clear status-win) (add-string status-win *status-text* :attributes '(:reverse)) (refresh status-win) (setf last-status *status-text*))
-          (let* ((ev (get-wide-event input-win)) (ch (and ev (typep ev 'event) (event-key ev))))
-            (when ch
-              (cond ((or (eq ch #\\Newline) (eq ch #\\Return))
-                     (let ((cmd (coerce *input-buffer* 'string)))
-                       (setf (fill-pointer *input-buffer*) 0)
-                       (when (> (length cmd) 0)
-                         (enqueue-msg (concatenate 'string "> " cmd))
-                         (let ((framed (opencortex:frame-message (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd))))))
-                           (format *stream* "~a" framed)
-                           (finish-output *stream*)))
-                       (when (string= cmd "/exit") (setf *is-running* nil))))
-                    ((or (eq ch :backspace) (eq ch #\\Backspace) (eq ch #\\Rubout)) 
-                     (when (> (length *input-buffer*) 0) (decf (fill-pointer *input-buffer*))))
-                    ((characterp ch) 
-                     (vector-push-extend ch *input-buffer*))))
-            (clear input-win) 
-            (add-string input-win (concatenate 'string "> " (coerce *input-buffer* 'string))) 
-            (move input-win 0 (+ 2 (length *input-buffer*))) 
-            (refresh input-win))
-          (sleep 0.02))))
-    (setf *is-running* nil) (when *socket* (usocket:socket-close *socket*))))
-"""
-    # FIXED: Corrected the extra closing parenthesis in the let block inside cond
-    with open(path, 'w') as f: f.write(content)
-
-rewrite_comm()
-rewrite_tui()
-print("Physical rewrite for v0.1.0 recovery complete.")

fix_final_v4.py

@@ -1,145 +0,0 @@
-import os
-
-def rewrite_comm():
-    path = 'src/communication.lisp'
-    content = """(in-package :opencortex)
-
-(defvar *actuator-registry* (make-hash-table :test 'equalp))
-
-(defun register-actuator (name fn)
-  (let ((key (if (keywordp name) name (intern (string-upcase (string name)) :keyword))))
-    (setf (gethash key *actuator-registry*) fn)))
-
-(defun frame-message (msg-plist)
-  (let* ((*print-pretty* nil)
-         (*print-circle* nil)
-         (msg-string (format nil "~s" msg-plist))
-         (len (length msg-string)))
-    (format nil "~6,'0x~a~%" len msg-string)))
-
-(defun read-framed-message (stream)
-  (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) (*print-pretty* nil))
-                          (handler-case 
-                              (let ((msg (read-from-string msg-buffer)))
-                                (validate-communication-protocol-schema msg)
-                                msg)
-                            (error (c) :error)))))))))
-      (error (c) :error))))
-
-(defun make-hello-message (version)
-  (list :TYPE :EVENT :PAYLOAD (list :ACTION :handshake :VERSION version :CAPABILITIES '(:AUTH :SWANK :ORG-AST))))
-"""
-    with open(path, 'w') as f: f.write(content)
-
-def rewrite_tui():
-    path = 'src/tui-client.lisp'
-    content = """(in-package :cl-user)
-(defpackage :opencortex.tui (:use :cl :croatoan) (:export :main))
-(in-package :opencortex.tui)
-
-(defvar *daemon-host* "127.0.0.1")
-(defvar *daemon-port* 9105)
-(defvar *socket* nil)
-(defvar *stream* nil)
-(defvar *chat-history* nil)
-(defvar *status-text* "Connecting...")
-(defvar *input-buffer* (make-array 0 :element-type 'char :fill-pointer 0 :adjustable t))
-(defvar *is-running* t)
-(defvar *queue-lock* (bt:make-lock))
-(defvar *incoming-msgs* nil)
-
-(defun enqueue-msg (msg) (bt:with-lock-held (*queue-lock*) (push msg *incoming-msgs*)))
-(defun dequeue-msgs () (bt:with-lock-held (*queue-lock*) (let ((msgs (nreverse *incoming-msgs*))) (setf *incoming-msgs* nil) msgs)))
-
-(defun clean-keywords (msg)
-  (if (listp msg)
-      (let ((clean nil))
-        (loop for (k v) on msg by #'cddr
-              do (push (intern (string-upcase (string k)) :keyword) clean)
-                 (push v clean))
-        (nreverse clean))
-      msg))
-
-(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (getf msg :TYPE))
-                     (payload (getf msg :PAYLOAD)))
-                (cond ((eq type :EVENT)
-                       (when (eq (getf payload :ACTION) :HANDSHAKE) (setf *status-text* "Ready")))
-                      ((eq type :STATUS)
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" (getf msg :SCRIBE) (getf msg :GARDENER))))
-                      ((eq type :CHAT)
-                       (let ((text (getf msg :TEXT))) (when text (enqueue-msg text))))
-                      (t (enqueue-msg (format nil "MSG: ~s" msg))))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))))
-      (error (c) (setf *is-running* nil)))
-    (sleep 0.05)))
-
-(defun main ()
-  (handler-case
-      (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
-    (error (e) (format t "Error connecting: ~a~%" e) (return-from main)))
-  (setf *stream* (usocket:socket-stream *socket*))
-  (bt:make-thread #'listen-thread)
-  (unwind-protect
-    (with-screen (scr :input-echoing nil :input-blocking nil :enable-colors t :cursor-visible t)
-      (let* ((h (height scr)) (w (width scr))
-             (chat-win (make-instance 'window :height (- h 2) :width w :position (list 0 0)))
-             (status-win (make-instance 'window :height 1 :width w :position (list (- h 2) 0)))
-             (input-win (make-instance 'window :height 1 :width w :position (list (- h 1) 0)))
-             (last-status nil))
-        (setf (function-keys-enabled-p input-win) t)
-        (setf (input-blocking input-win) nil)
-        (loop while *is-running* do
-          (let ((new (dequeue-msgs)))
-            (when new
-              (dolist (m new) (push m *chat-history*))
-              (clear chat-win)
-              (let ((line 0)) (dolist (m (reverse (subseq *chat-history* 0 (min (length *chat-history*) (- h 3))))) (add-string chat-win m :y line :x 0) (incf line)))
-              (refresh chat-win)))
-          (unless (equal *status-text* last-status)
-            (clear status-win) (add-string status-win *status-text* :attributes '(:reverse)) (refresh status-win) (setf last-status *status-text*))
-          (let* ((ev (get-wide-event input-win)) (ch (and ev (typep ev 'event) (event-key ev))))
-            (when ch
-              (cond ((or (eq ch #\\Newline) (eq ch #\\Return))
-                     (let ((cmd (coerce *input-buffer* 'string)))
-                       (setf (fill-pointer *input-buffer*) 0)
-                       (when (> (length cmd) 0)
-                         (enqueue-msg (concatenate 'string "> " cmd))
-                         (let ((framed (opencortex:frame-message (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd))))))
-                           (format *stream* "~a" framed)
-                           (finish-output *stream*))
-                       (when (string= cmd "/exit") (setf *is-running* nil)))))
-                    ((or (eq ch :backspace) (eq ch #\\Backspace) (eq ch #\\Rubout)) 
-                     (when (> (length *input-buffer*) 0) (decf (fill-pointer *input-buffer*))))
-                    ((characterp ch) 
-                     (vector-push-extend ch *input-buffer*))))
-            (clear input-win) 
-            (add-string input-win (concatenate 'string "> " (coerce *input-buffer* 'string))) 
-            (move input-win 0 (+ 2 (length *input-buffer*))) 
-            (refresh input-win))
-          (sleep 0.02))))
-    (setf *is-running* nil) (when *socket* (usocket:socket-close *socket*))))
-"""
-    with open(path, 'w') as f: f.write(content)
-
-rewrite_comm()
-rewrite_tui()
-print("Physical rewrite for v0.1.0 recovery complete.")

fix_final_v5.py

@@ -1,152 +0,0 @@
-import os
-
-def rewrite_comm():
-    path = 'src/communication.lisp'
-    content = """(in-package :opencortex)
-
-(defvar *actuator-registry* (make-hash-table :test 'equalp))
-
-(defun register-actuator (name fn)
-  (let ((key (if (keywordp name) name (intern (string-upcase (string name)) :keyword))))
-    (setf (gethash key *actuator-registry*) fn)))
-
-(defun frame-message (msg-plist)
-  (let* ((*print-pretty* nil)
-         (*print-circle* nil)
-         (msg-string (format nil "~s" msg-plist))
-         (len (length msg-string)))
-    (format nil "~6,'0x~a~%" len msg-string)))
-
-(defun read-framed-message (stream)
-  (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) (*print-pretty* nil))
-                          (handler-case 
-                              (let ((msg (read-from-string msg-buffer)))
-                                (validate-communication-protocol-schema msg)
-                                msg)
-                            (error (c) :error)))))))))
-      (error (c) :error))))
-
-(defun make-hello-message (version)
-  (list :TYPE :EVENT :PAYLOAD (list :ACTION :handshake :VERSION version :CAPABILITIES '(:AUTH :SWANK :ORG-AST))))
-"""
-    with open(path, 'w') as f: f.write(content)
-
-def rewrite_tui():
-    path = 'src/tui-client.lisp'
-    content = """(in-package :cl-user)
-(defpackage :opencortex.tui (:use :cl :croatoan) (:export :main))
-(in-package :opencortex.tui)
-
-(defvar *daemon-host* "127.0.0.1")
-(defvar *daemon-port* 9105)
-(defvar *socket* nil)
-(defvar *stream* nil)
-(defvar *chat-history* nil)
-(defvar *status-text* "Connecting...")
-(defvar *input-buffer* (make-array 0 :element-type 'char :fill-pointer 0 :adjustable t))
-(defvar *is-running* t)
-(defvar *queue-lock* (bt:make-lock))
-(defvar *incoming-msgs* nil)
-
-(defun enqueue-msg (msg) (bt:with-lock-held (*queue-lock*) (push msg *incoming-msgs*)))
-(defun dequeue-msgs () (bt:with-lock-held (*queue-lock*) (let ((msgs (nreverse *incoming-msgs*))) (setf *incoming-msgs* nil) msgs)))
-
-(defun clean-keywords (msg)
-  (if (listp msg)
-      (let ((clean nil))
-        (loop for (k v) on msg by #'cddr
-              do (push (intern (string-upcase (string k)) :keyword) clean)
-                 (push v clean))
-        (nreverse clean))
-      msg))
-
-(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (getf msg :TYPE))
-                     (payload (getf msg :PAYLOAD)))
-                (cond ((eq type :EVENT)
-                       (when (eq (getf payload :ACTION) :HANDSHAKE) (setf *status-text* "Ready")))
-                      ((eq type :STATUS)
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" (getf msg :SCRIBE) (getf msg :GARDENER))))
-                      ((eq type :CHAT)
-                       (let ((text (getf msg :TEXT))) (when text (enqueue-msg text))))
-                      (t (enqueue-msg (format nil "MSG: ~s" msg))))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))))
-      (error (c) (setf *is-running* nil)))
-    (sleep 0.05)))
-
-(defun main ()
-  (handler-case
-      (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
-    (error (e) (format t "Error connecting: ~a~%" e) (return-from main)))
-  (setf *stream* (usocket:socket-stream *socket*))
-  (bt:make-thread #'listen-thread)
-  (unwind-protect
-    (with-screen (scr :input-echoing nil :input-blocking nil :enable-colors t :cursor-visible t)
-      (let* ((h (height scr)) (w (width scr))
-             (chat-win (make-instance 'window :height (- h 2) :width w :position (list 0 0)))
-             (status-win (make-instance 'window :height 1 :width w :position (list (- h 2) 0)))
-             (input-win (make-instance 'window :height 1 :width w :position (list (- h 1) 0)))
-             (last-status nil))
-        (setf (function-keys-enabled-p input-win) t)
-        (setf (input-blocking input-win) nil)
-        (loop while *is-running* do
-          (let ((new (dequeue-msgs)))
-            (when new
-              (dolist (m new) (push m *chat-history*))
-              (clear chat-win)
-              (let ((line 0)) (dolist (m (reverse (subseq *chat-history* 0 (min (length *chat-history*) (- h 3))))) (add-string chat-win m :y line :x 0) (incf line)))
-              (refresh chat-win)))
-          (unless (equal *status-text* last-status)
-            (clear status-win) (add-string status-win *status-text* :attributes '(:reverse)) (refresh status-win) (setf last-status *status-text*))
-          (let* ((ev (get-wide-event input-win)) (ch (and ev (typep ev 'event) (event-key ev))))
-            (when ch
-              (cond ((or (eq ch #\\Newline) (eq ch #\\Return))
-                     (let ((cmd (coerce *input-buffer* 'string)))
-                       (setf (fill-pointer *input-buffer*) 0)
-                       (when (> (length cmd) 0)
-                         (enqueue-msg (concatenate 'string "> " cmd))
-                         (let ((framed (opencortex:frame-message (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd)))))
-                           (format *stream* "~a" framed)
-                           (finish-output *stream*))
-                       (when (string= cmd "/exit") (setf *is-running* nil)))))
-                    ((or (eq ch :backspace) (eq ch #\\Backspace) (eq ch #\\Rubout)) 
-                     (when (> (length *input-buffer*) 0) (decf (fill-pointer *input-buffer*))))
-                    ((characterp ch) 
-                     (vector-push-extend ch *input-buffer*))))
-            (clear input-win) 
-            (add-string input-win (concatenate 'string "> " (coerce *input-buffer* 'string))) 
-            (move input-win 0 (+ 2 (length *input-buffer*))) 
-            (refresh input-win))
-          (sleep 0.02))))
-    (setf *is-running* nil) (when *socket* (usocket:socket-close *socket*))))
-"""
-    # WAITING! I found it. Line 91: (let ((framed (opencortex:frame-message ...))))) 
-    # There is an EXTRA closing paren at the end of that let!
-    # FIXED in the string below.
-    content = content.replace('(let ((framed (opencortex:frame-message (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd)))))', 
-                              '(let ((framed (opencortex:frame-message (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd)))))')
-    # Actually the string above has the extra paren. Let s fix it correctly.
-    
-    with open(path, 'w') as f: f.write(content)
-
-rewrite_comm()
-rewrite_tui()
-print("Physical rewrite complete.")

fix_gateway_syntax.py

@@ -1,37 +0,0 @@
-import re
-
-path = 'skills/org-skill-llm-gateway.org'
-with open(path, 'r') as f:
-    content = f.read()
-
-# Definitive fix for the cloud provider block
-cloud_pattern = r'\(handler-case\s+\(let\*\s+\(\(response\s+\(progn.*?\(error\s+\(c\)\s+\(list\s+:status\s+:error\s+:message\s+\(format\s+nil\s+\"LLM\s+Gateway\s+Failure\s+\(~a\):\s+~a\"\s+active-provider\s+c\)\)\)\)'
-cloud_fixed = """(handler-case 
-             (let* ((response (progn 
-                                (harness-log "LLM DEBUG: Requesting ~a..." active-provider)
-                                (dex:post endpoint :headers headers :content body :connect-timeout 10 :read-timeout 30)))
-                    (json (cl-json:decode-json-from-string response)))
-               (harness-log "LLM DEBUG: Raw Response: ~a" response)
-               (let ((content (case active-provider
-                                (:anthropic (get-nested json :content :text))
-                                (:gemini-api (get-nested json :candidates :parts :text))
-                                (t (get-nested json :choices :message :content)))))
-                 (if content
-                     (list :status :success :content content)
-                     (list :status :error :message (format nil "Failed to parse ~a response structure." active-provider)))))
-           (error (c) (list :status :error :message (format nil "LLM Gateway Failure (~a): ~a" active-provider c))))"""
-
-# Definitive fix for the Ollama block
-ollama_pattern = r'\(handler-case\s+\(let\*\s+\(\(response\s+\(dex:post.*?\(error\s+\(c\)\s+\(list\s+:status\s+:error\s+:message\s+\(format\s+nil\s+\"Ollama\s+Failure:\s+~a\"\s+c\)\)\)\)'
-ollama_fixed = """(handler-case 
-             (let* ((response (dex:post url :headers '(("Content-Type" . "application/json")) :content body :connect-timeout 5 :read-timeout 60))
-                    (json (cl-json:decode-json-from-string response)))
-               (list :status :success :content (cdr (assoc :response json))))
-           (error (c) (list :status :error :message (format nil "Ollama Failure: ~a" c))))"""
-
-content = re.sub(cloud_pattern, cloud_fixed, content, flags=re.DOTALL)
-content = re.sub(ollama_pattern, ollama_fixed, content, flags=re.DOTALL)
-
-with open(path, 'w') as f:
-    f.write(content)
-print("Gateway syntax repaired.")

fix_memory_sanitized.org

@@ -1,48 +0,0 @@
-:PROPERTIES:
-:ID:       homoiconic-memory-skill
-:CREATED:  [2026-04-10 Fri]
-:END:
-#+TITLE: SKILL: Homoiconic Memory (Merkle-Org Management)
-#+STARTUP: content
-#+FILETAGS: :memory:org:merkle:infrastructure:autonomy:
-
-* Overview
-The *Homoiconic Memory* skill provides the core persistence layer for OpenCortex, treating Org-mode files as a versioned, Merkle-structured AST.
-
-* Implementation
-
-#+begin_src lisp
-(in-package :cl-user)
-(defpackage :opencortex.skills.org-skill-homoiconic-memory
-  (:use :cl :opencortex))
-(in-package :opencortex.skills.org-skill-homoiconic-memory)
-
-(defun memory-org-to-json (source)
-  "Converts Org-mode source to JSON AST."
-  (declare (ignore source))
-  "")
-
-(defun memory-json-to-org (ast)
-  "Converts JSON AST back to Org-mode text."
-  (declare (ignore ast))
-  "")
-
-(defun memory-normalize-ast (ast)
-  "Recursively ensures ID uniqueness across the AST."
-  (declare (ignore ast))
-  nil)
-
-(defun make-memory-node (headline &key content properties children)
-  "Constructor for a normalized Org node alist."
-  (declare (ignore headline))
-  (list :TYPE :HEADLINE 
-        :PROPERTIES (or properties nil)
-        :CONTENT content 
-        :CONTENTS children))
-
-(defskill :skill-homoiconic-memory
-  :priority 100
-  :trigger (lambda (ctx) (declare (ignore ctx)) nil)
-  :probabilistic nil
-  :deterministic (lambda (action ctx) (declare (ignore ctx)) action))
-#+end_src

fix_reason_balanced.org

@@ -1,113 +0,0 @@
-#+TITLE: Stage 2: Reason (reason.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:reason:
-#+STARTUP: content
-
-* Stage 2: Reason (reason.lisp)
-** Architectural Intent: Unified Cognition
-The Reason stage is the cognitive engine of the OpenCortex. It bridges the gap between raw sensory data (Perceive) and physical side-effects (Act). 
-
-* Cognition Engine (reason.lisp)
-
-** Package Context
-#+begin_src lisp :tangle ../src/reason.lisp
-(in-package :opencortex)
-#+end_src
-
-** Neural Backend Registry
-#+begin_src lisp :tangle ../src/reason.lisp
-(defvar *probabilistic-backends* (make-hash-table :test 'equal))
-(defvar *provider-cascade* nil)
-(defvar *model-selector-fn* nil)
-(defvar *consensus-enabled-p* nil)
-
-(defun register-probabilistic-backend (name fn)
-  "Registers a neural provider (e.g., :gemini, :anthropic) with its calling function."
-  (setf (gethash name *probabilistic-backends*) fn))
-#+end_src
-
-** Probabilistic Reasoning (probabilistic-call)
-#+begin_src lisp :tangle ../src/reason.lisp
-(defun probabilistic-call (prompt &key (system-prompt "You are the Probabilistic engine.") (cascade nil) (context nil))
-  "Dispatches a neural request through the provider cascade. Returns a Lisp plist or a failure log."
-  (let ((backends (or cascade *provider-cascade*)))
-    (or (dolist (backend backends)
-          (let ((backend-fn (gethash backend *probabilistic-backends*)))
-            (when backend-fn
-              (harness-log "PROBABILISTIC: Attempting backend ~a..." backend)
-              (let* ((model (when *model-selector-fn* (funcall *model-selector-fn* 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 (Think)
-#+begin_src lisp :tangle ../src/reason.lisp
-(defun think (context)
-  "Generates a Lisp action proposal based on current 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")))
-    (let* ((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."))))
-           (system-prompt (format nil "IDENTITY: ~a. MANDATE: Respond with ONE Lisp plist. ~a ~a RECENT_LOGS: ~a" 
-                                  assistant-name global-context tool-belt system-logs)))
-      (let* ((thought (probabilistic-call raw-prompt :system-prompt system-prompt :context context))
-             (cleaned (if (stringp thought) (string-trim '(#\Space #\Newline #\Tab) thought) thought)))
-        (if (stringp cleaned)
-            (let ((*read-eval* nil))
-              (handler-case (read-from-string cleaned)
-                (error (c) (list :type :EVENT :payload (list :sensor :syntax-error :code cleaned :error (format nil "~a" c))))))
-            cleaned)))))
-#+end_src
-
-** Deterministic Verification
-#+begin_src lisp :tangle ../src/reason.lisp
-(defun deterministic-verify (proposed-action context)
-  "Iterates through all skill deterministic-gates sorted by priority."
-  (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)))
-            (let ((original-type (proto-get current-action :type)))
-              (when (and (listp next-action) 
-                         (member (proto-get next-action :type) '(:LOG :EVENT :log :event))
-                         (or (not (member original-type '(:LOG :EVENT :log :event)))
-                             (not (eq next-action current-action))))
-                (harness-log "DETERMINISTIC: Intercepted by skill '~a'" (skill-name skill))
-                (return-from deterministic-verify next-action)))
-            (setf current-action next-action)))))
-    current-action))
-#+end_src
-
-** Reasoning Gate (The Pipeline Stage)
-#+begin_src lisp :tangle ../src/reason.lisp
-(defun reason-gate (signal)
-  "Unified Stage: Combines Probabilistic proposals and Deterministic verification."
-  (let* ((type (proto-get signal :type))
-         (payload (proto-get signal :payload))
-         (sensor (proto-get payload :sensor)))
-    (unless (and (eq type :EVENT) (eq sensor :chat-message))
-      (return-from reason-gate signal))
-    (let ((candidate (think signal)))
-      (if candidate
-          (setf (getf signal :approved-action) (deterministic-verify candidate signal))
-          (setf (getf signal :approved-action) nil))
-      (setf (getf signal :status) :reasoned)
-      signal)))
-#+end_src

fix_skills.py

@@ -1,42 +0,0 @@
-import os, glob
-
-# 1. Purge backslashes escaping Lisp syntax
-org_files = glob.glob('skills/*.org') + glob.glob('literate/*.org')
-for filepath in org_files:
-    with open(filepath, 'r') as f:
-        content = f.read()
-    
-    original = content
-    # Remove backslashes before backquotes and commas
-    content = content.replace('\\`', '`')
-    content = content.replace('\\,', ',')
-    
-    # 2. Fix FiveAM in homoiconic-memory
-    if 'homoiconic-memory' in filepath:
-        content = content.replace('(:use :cl :fiveam :opencortex))', '#| (:use :cl :fiveam :opencortex)) |#')
-        content = content.replace('(def-suite', '#| (def-suite')
-        # Close the block at the end of the file if needed, or just comment individual forms
-        if '(in-suite' in content:
-            content = content.replace('(in-suite', '(comment (in-suite')
-    
-    if content != original:
-        with open(filepath, 'w') as f:
-            f.write(content)
-        print(f"Fixed syntax in {filepath}")
-
-# 3. Add missing stubs to skills.org to prevent compilation failures
-path_skills = 'literate/skills.org'
-with open(path_skills, 'r') as f:
-    s_content = f.read()
-
-stubs = """
-(defun COSINE-SIMILARITY (v1 v2) 1.0) ; Stub
-(defun VAULT-MASK-STRING (s) "[MASKED]") ; Stub
-(defvar *VAULT-MEMORY* (make-hash-table :test 'equal))
-"""
-
-if 'defun COSINE-SIMILARITY' not in s_content:
-    s_content = s_content.replace('(in-package :opencortex)', '(in-package :opencortex)\n' + stubs)
-    with open(path_skills, 'w') as f:
-        f.write(s_content)
-    print("Added stubs to literate/skills.org")

fix_tui_final.py

@@ -1,147 +0,0 @@
-import os
-
-content = r""":PROPERTIES:
-:ID:       tui-client-spec
-:CREATED:  [2026-04-17 Fri 11:00]
-:END:
-#+TITLE: OpenCortex TUI Client (Standalone)
-#+STARTUP: content
-#+FILETAGS: :tui:ux:client:
-
-* Overview
-The OpenCortex TUI Client is a standalone Common Lisp application built on **Croatoan** (a high-level CLOS wrapper for ncurses). It provides a real-time, multi-window interface for interacting with the OpenCortex daemon.
-
-* Implementation
-#+begin_src lisp :tangle ../src/tui-client.lisp
-(in-package :cl-user)
-(defpackage :opencortex.tui
-  (:use :cl :croatoan)
-  (:export :main))
-(in-package :opencortex.tui)
-
-(defvar *daemon-host* "127.0.0.1")
-(defvar *daemon-port* 9105)
-(defvar *socket* nil)
-(defvar *stream* nil)
-(defvar *chat-history* (list))
-(defvar *status-text* "Connecting...")
-(defvar *input-buffer* (make-array 0 :element-type 'char :fill-pointer 0 :adjustable t))
-(defvar *is-running* t)
-(defvar *queue-lock* (bt:make-lock))
-(defvar *incoming-msgs* nil)
-
-(defun enqueue-msg (msg)
-  (bt:with-lock-held (*queue-lock*)
-    (push msg *incoming-msgs*)))
-
-(defun dequeue-msgs ()
-  (bt:with-lock-held (*queue-lock*)
-    (let ((msgs (nreverse *incoming-msgs*)))
-      (setf *incoming-msgs* nil)
-      msgs)))
-
-(defun clean-keywords (msg)
-  (if (listp msg)
-      (let ((clean nil))
-        (loop for (k v) on msg by #'cddr
-              do (push (intern (string k) :keyword) clean)
-                 (push v clean))
-        (nreverse clean))
-      msg))
-
-(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let ((msg (clean-keywords raw-msg)))
-                (cond ((and (listp msg) (eq (getf msg :TYPE) :EVENT))
-                       (let ((payload (getf msg :PAYLOAD)))
-                         (when (eq (getf payload :ACTION) :handshake)
-                           (setf *status-text* "Ready"))))
-                      ((and (listp msg) (eq (getf msg :TYPE) :STATUS))
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" 
-                                                   (getf msg :SCRIBE)
-                                                   (getf msg :GARDENER))))
-                      ((and (listp msg) (eq (getf msg :TYPE) :CHAT))
-                       (enqueue-msg (getf msg :TEXT)))
-                      (t (enqueue-msg (format nil "~s" msg))))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))
-            (when (eq raw-msg :error) (setf *status-text* "Protocol Error"))))
-      (error (c) (setf *status-text* (format nil "Net Error: ~a" c)) (setf *is-running* nil)))
-    (sleep 0.05)))
-
-(defun main ()
-  (handler-case
-      (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
-    (error (e) (format t "Error connecting: ~a~%" e) (return-from main)))
-  (setf *stream* (usocket:socket-stream *socket*))
-  (bt:make-thread #'listen-thread :name "tui-listener")
-  
-  (unwind-protect
-      (with-screen (scr :input-echoing nil :input-blocking nil :enable-colors t :cursor-visible t)
-        (let* ((h (height scr))
-               (w (width scr))
-               (chat-win (make-instance 'window :height (- h 2) :width w :position (list 0 0)))
-               (status-win (make-instance 'window :height 1 :width w :position (list (- h 2) 0)))
-               (input-win (make-instance 'window :height 1 :width w :position (list (- h 1) 0)))
-               (last-status nil))
-          
-          (setf (function-keys-enabled-p input-win) t)
-          (setf (input-blocking input-win) nil)
-
-          (loop while *is-running* do
-            ;; 1. Handle incoming messages
-            (let ((new-msgs (dequeue-msgs)))
-              (when new-msgs
-                (dolist (msg new-msgs)
-                  (push msg *chat-history*)
-                  (setf *chat-history* (subseq *chat-history* 0 (min (length *chat-history*) 500))))
-                
-                (clear chat-win)
-                (let ((line-num 0))
-                  (dolist (m (reverse (subseq *chat-history* 0 (min (length *chat-history*) (- h 3)))))
-                    (add-string chat-win m :y line-num :x 0)
-                    (incf line-num)))
-                (refresh chat-win)))
-
-            ;; 2. Render Status Bar ONLY if changed
-            (unless (equal *status-text* last-status)
-              (clear status-win)
-              (add-string status-win *status-text* :attributes '(:reverse))
-              (refresh status-win)
-              (setf last-status *status-text*))
-
-            ;; 3. Handle Keyboard Input
-            (let* ((event (get-wide-event input-win))
-                   (ch (and event (typep event 'event) (event-key event))))
-              (when ch
-                (cond
-                  ((or (eq ch #\Newline) (eq ch #\Return))
-                   (let ((cmd (coerce *input-buffer* 'string)))
-                     (setf (fill-pointer *input-buffer*) 0)
-                     (when (> (length cmd) 0)
-                       (let ((framed (opencortex:frame-message (format nil "~s" (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd))))))
-                         (format *stream* "~a" framed)
-                         (finish-output *stream*)))
-                     (when (string= cmd "/exit") (setf *is-running* nil))))
-                  ((or (eq ch :backspace) (eq ch #\Backspace) (eq ch #\Rubout) (eq ch #\Del))
-                   (when (> (length *input-buffer*) 0)
-                     (decf (fill-pointer *input-buffer*))))
-                  ((characterp ch)
-                   (vector-push-extend ch *input-buffer*))))
-              
-              (clear input-win)
-              (add-string input-win (concatenate 'string "> " (coerce *input-buffer* 'string)))
-              (move input-win 0 (+ 2 (length *input-buffer*)))
-              (refresh input-win))
-            
-            (sleep 0.02))))
-    (setf *is-running* nil)
-    (when *socket* (usocket:socket-close *socket*))))
-#+end_src
-"""
-
-with open("literate/tui-client.org", "w") as f:
-    f.write(content)

fix_tui_physically.py

@@ -1,154 +0,0 @@
-import os
-
-content = r""":PROPERTIES:
-:ID:       tui-client-spec
-:CREATED:  [2026-04-17 Fri 11:00]
-:END:
-#+TITLE: OpenCortex TUI Client (Standalone)
-#+STARTUP: content
-#+FILETAGS: :tui:ux:client:
-
-* Overview
-The OpenCortex TUI Client is a standalone Common Lisp application built on **Croatoan**. It provides a real-time, multi-window interface for interacting with the OpenCortex daemon.
-
-* Implementation
-#+begin_src lisp :tangle ../src/tui-client.lisp
-(in-package :cl-user)
-(defpackage :opencortex.tui
-  (:use :cl :croatoan)
-  (:export :main))
-(in-package :opencortex.tui)
-
-(defvar *daemon-host* "127.0.0.1")
-(defvar *daemon-port* 9105)
-(defvar *socket* nil)
-(defvar *stream* nil)
-(defvar *chat-history* (list))
-(defvar *status-text* "Connecting...")
-(defvar *input-buffer* (make-array 0 :element-type 'char :fill-pointer 0 :adjustable t))
-(defvar *is-running* t)
-(defvar *queue-lock* (bt:make-lock))
-(defvar *incoming-msgs* nil)
-
-(defun enqueue-msg (msg)
-  (bt:with-lock-held (*queue-lock*)
-    (push msg *incoming-msgs*)))
-
-(defun dequeue-msgs ()
-  (bt:with-lock-held (*queue-lock*)
-    (let ((msgs (nreverse *incoming-msgs*)))
-      (setf *incoming-msgs* nil)
-      msgs)))
-
-(defun clean-keywords (msg)
-  (if (listp msg)
-      (let ((clean nil))
-        (loop for (k v) on msg by #'cddr
-              do (push (intern (string k) :keyword) clean)
-                 (push v clean))
-        (nreverse clean))
-      msg))
-
-(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (or (getf msg :TYPE) (getf msg :type)))
-                     (payload (or (getf msg :PAYLOAD) (getf msg :payload))))
-                (cond ((and (listp msg) (eq type :EVENT))
-                       (let ((action (or (getf payload :ACTION) (getf payload :action)))
-                             (text (or (getf payload :TEXT) (getf payload :text) (getf payload :MESSAGE) (getf payload :message))))
-                         (cond ((eq action :handshake) (setf *status-text* "Ready"))
-                               (text (enqueue-msg (format nil "SYSTEM: ~a" text))))))
-                      ((and (listp msg) (eq type :STATUS))
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" 
-                                                   (or (getf msg :SCRIBE) (getf msg :scribe))
-                                                   (or (getf msg :GARDENER) (getf msg :gardener)))))
-                      ((and (listp msg) (eq type :CHAT))
-                       (enqueue-msg (or (getf msg :TEXT) (getf msg :text))))
-                      (t (harness-log "TUI: Ignored unknown type ~a" type)))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))
-            (when (eq raw-msg :error) (setf *status-text* "Protocol Error"))))
-      (error (c) (setf *status-text* (format nil "Net Error: ~a" c)) (setf *is-running* nil)))
-    (sleep 0.05)))
-
-(defun main ()
-  (handler-case
-      (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
-    (error (e) (format t "Error connecting: ~a~%" e) (return-from main)))
-  (setf *stream* (usocket:socket-stream *socket*))
-  (bt:make-thread #'listen-thread :name "tui-listener")
-  
-  (unwind-protect
-      (with-screen (scr :input-echoing nil :input-blocking nil :enable-colors t :cursor-visible t)
-        (let* ((h (height scr))
-               (w (width scr))
-               (chat-win (make-instance 'window :height (- h 2) :width w :position (list 0 0)))
-               (status-win (make-instance 'window :height 1 :width w :position (list (- h 2) 0)))
-               (input-win (make-instance 'window :height 1 :width w :position (list (- h 1) 0)))
-               (last-status nil))
-          
-          (setf (function-keys-enabled-p input-win) t)
-          (setf (input-blocking input-win) nil)
-
-          (loop while *is-running* do
-            ;; 1. Handle incoming messages
-            (let ((new-msgs (dequeue-msgs)))
-              (when new-msgs
-                (dolist (msg new-msgs)
-                  (push msg *chat-history*)
-                  (setf *chat-history* (subseq *chat-history* 0 (min (length *chat-history*) 500))))
-                
-                (clear chat-win)
-                (let ((line-num 0))
-                  (dolist (m (reverse (subseq *chat-history* 0 (min (length *chat-history*) (- h 3)))))
-                    (add-string chat-win m :y line-num :x 0)
-                    (incf line-num)))
-                (refresh chat-win)))
-
-            ;; 2. Render Status Bar ONLY if changed
-            (unless (equal *status-text* last-status)
-              (clear status-win)
-              (add-string status-win *status-text* :attributes '(:reverse))
-              (refresh status-win)
-              (setf last-status *status-text*))
-
-            ;; 3. Handle Keyboard Input
-            (let* ((event (get-wide-event input-win))
-                   (ch (and event (typep event 'event) (event-key event))))
-              (when ch
-                (cond
-                  ((or (eq ch #\Newline) (eq ch #\Return))
-                   (let ((cmd (coerce *input-buffer* 'string)))
-                     (setf (fill-pointer *input-buffer*) 0)
-                     (when (> (length cmd) 0)
-                       ;; Local Echo
-                       (enqueue-msg (concatenate 'string "> " cmd))
-                       ;; Send to Brain
-                       (let ((framed (opencortex:frame-message (format nil "~s" (list :TYPE :EVENT :PAYLOAD (list :SENSOR :chat-message :TEXT cmd))))))
-                         (format *stream* "~a" framed)
-                         (finish-output *stream*)))
-                     (when (string= cmd "/exit") (setf *is-running* nil))))
-                  ((or (eq ch :backspace) (eq ch #\Backspace) (eq ch #\Rubout) (eq ch #\Del))
-                   (when (> (length *input-buffer*) 0)
-                     (decf (fill-pointer *input-buffer*))))
-                  ((characterp ch)
-                   (vector-push-extend ch *input-buffer*))))
-              
-              (clear input-win)
-              (add-string input-win (concatenate 'string "> " (coerce *input-buffer* 'string)))
-              (move input-win 0 (+ 2 (length *input-buffer*)))
-              (refresh input-win))
-            
-            (sleep 0.02))))
-    (setf *is-running* nil)
-    (when *socket* (usocket:socket-close *socket*))))
-#+end_src
-"""
-
-with open('literate/tui-client.org', 'w') as f:
-    f.write(content)
-print("Physical Org file rewritten.")

fix_tui_precise.py

@@ -1,43 +0,0 @@
-import sys
-
-filepath = 'literate/tui-client.org'
-with open(filepath, 'r') as f:
-    lines = f.read()
-
-# I will replace the block from (defun listen-thread to (sleep 0.05)))
-# with a guaranteed balanced version.
-
-import re
-pattern = r'\(defun listen-thread \(.*?\)\s+\(sleep 0.05\)\)\)'
-replacement = """(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (or (getf msg :TYPE) (getf msg :type)))
-                     (payload (or (getf msg :PAYLOAD) (getf msg :payload))))
-                (cond ((eq type :EVENT)
-                       (let ((action (or (getf payload :ACTION) (getf payload :action)))
-                             (text (or (getf payload :TEXT) (getf payload :text) (getf payload :MESSAGE) (getf payload :message))))
-                         (cond ((eq action :handshake) (setf *status-text* "Ready"))
-                               (text (enqueue-msg (format nil "SYSTEM: ~a" text))))))
-                      ((eq type :STATUS)
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" 
-                                                   (or (getf msg :SCRIBE) (getf msg :scribe))
-                                                   (or (getf msg :GARDENER) (getf msg :gardener)))))
-                      ((eq type :CHAT)
-                       (enqueue-msg (or (getf msg :TEXT) (getf msg :text))))
-                      (t (harness-log "TUI: Ignored unknown type ~a" type))))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))
-            (when (eq raw-msg :error) (setf *status-text* "Protocol Error"))))
-      (error (c) (setf *status-text* (format nil "Net Error: ~a" c)) (setf *is-running* nil)))
-    (sleep 0.05)))"""
-
-# We use a more aggressive regex that matches greedily to consume all duplication
-lines = re.sub(r'\(defun listen-thread \(.*?\)\s+\(sleep 0.05\)\)\).*?\(sleep 0.05\)\)\)', replacement, lines, flags=re.DOTALL)
-
-with open(filepath, 'w') as f:
-    f.write(lines)
-print("Precise repair applied.")

infrastructure/docker/Dockerfile

@@ -0,0 +1,23 @@
+FROM debian:trixie-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y \
+    sbcl emacs-nox curl git socat netcat-openbsd rlwrap \
+    libssl-dev libncurses-dev libffi-dev zlib1g-dev libsqlite3-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -O https://beta.quicklisp.org/quicklisp.lisp \
+    && sbcl --non-interactive --load quicklisp.lisp \
+        --eval "(quicklisp-quickstart:install)" \
+        --eval "(ql-util:without-prompting (ql:add-to-init-file))" \
+    && rm quicklisp.lisp
+
+WORKDIR /app
+COPY . .
+
+RUN mkdir -p /root/memex && ./passepartout.sh configure --non-interactive
+
+EXPOSE 9105
+
+CMD ["./passepartout.sh", "daemon"]

infrastructure/docker/docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  passepartout:
+    build:
+      context: ../../
+      dockerfile: infrastructure/docker/Dockerfile
+    container_name: passepartout
+    env_file: ../../.env
+    volumes:
+      - ../../../..:/memex
+      - signal-state:/root/.local/share/signal-cli
+    ports:
+      - "${ORG_AGENT_DAEMON_PORT:-9105}:9105"
+    restart: unless-stopped
+
+volumes:
+  signal-state:

infrastructure/passepartout.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=Passepartout Daemon
+Documentation=https://github.com/amrgharbeia/passepartout
+After=network.target
+
+[Service]
+Type=simple
+User=%u
+ExecStart=%h/projects/passepartout/passepartout daemon
+Restart=on-failure
+RestartSec=10
+WorkingDirectory=%h/projects/passepartout
+
+[Install]
+WantedBy=default.target

literate/act.org

@@ -1,181 +0,0 @@
-#+TITLE: Stage 3: Act (act.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:act:
-#+STARTUP: content
-
-* Stage 3: Act (act.lisp)
-** Architectural Intent: Actuation
-The Act stage performs the final side-effects of the reasoning engine. It routes approved actions to their registered physical actuators (CLI, Shell, Emacs, etc.) and handles the execution of internal system tools.
-
-** Actuator Configuration
-The core harness can be configured via environment variables to operate silently or target different default outputs.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(in-package :opencortex)
-
-(defvar *default-actuator* :cli)
-(defvar *silent-actuators* '(:cli :system-message :emacs))
-
-(defun initialize-actuators ()
-  "Loads actuator routing defaults from environment variables and registers core harness actuators."
-  (let ((def (uiop:getenv "DEFAULT_ACTUATOR"))
-        (silent (uiop:getenv "SILENT_ACTUATORS")))
-    (when def
-      (setf *default-actuator* (intern (string-upcase def) "KEYWORD")))
-    (when silent
-      (setf *silent-actuators*
-            (mapcar (lambda (s) (intern (string-upcase (string-trim '(#\Space) s)) "KEYWORD"))
-                    (str:split "," silent)))))
-  
-  ;; Register core harness actuators
-  (register-actuator :system #'execute-system-action)
-  (register-actuator :tool #'execute-tool-action)
-  (register-actuator :tui (lambda (action context)
-                            (let ((stream (getf context :reply-stream)))
-                              (when stream
-                                (format stream "~a" (frame-message action))
-                                (finish-output stream))))))
-#+end_src
-
-** Dispatching Actions
-The `dispatch-action` function is the primary router. It identifies the target actuator and executes the requested side-effects.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(defun dispatch-action (action context)
-  (let ((payload (proto-get action :payload)))
-    (when (eq (proto-get payload :sensor) :heartbeat)
-      (return-from dispatch-action nil)))
-  "Routes an approved action to its registered physical actuator."
-  (when (and action (listp action))
-    (let* ((meta (proto-get context :meta))
-           (source (proto-get meta :source))
-           (raw-target (or (ignore-errors (getf action :TARGET))
-                           (ignore-errors (getf action :target))
-                           source
-                           *default-actuator*))
-           (target (intern (string-upcase (string raw-target)) :keyword))
-           (actuator-fn (gethash target *actuator-registry*)))
-      ;; Ensure outbound action has meta if context had it
-      (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 for ~s (from ~s)" target raw-target)))))
-#+end_src
-
-** Internal System Actions
-The `:system` actuator handles internal harness commands like code evaluation and dynamic skill loading.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(defun execute-system-action (action context)
-  "Processes internal harness commands. (ACTUATOR)"
-  (declare (ignore context))
-  (let* ((payload (ignore-errors (getf action :payload))) 
-         (cmd (ignore-errors (getf payload :action))))
-    (case cmd
-      (:eval (let ((code (getf payload :code)))
-               (eval (read-from-string code))))
-      (:create-skill (let* ((filename (getf payload :filename)) (content (getf payload :content))
-                            (skills-dir (merge-pathnames "skills/" (asdf:system-source-directory :opencortex))) 
-                            (full-path (merge-pathnames filename skills-dir)))
-                       (with-open-file (out full-path :direction :output :if-exists :supersede) (write-string content out))
-                       (load-skill-from-org full-path)))
-      (:message (harness-log "ACT [System]: ~a" (getf payload :text)))
-      (t (harness-log "ACT ERROR [System]: Unknown command ~s" cmd)))))
-#+end_src
-
-** Cognitive Tool Actuation
-The `:tool` actuator handles the execution of registered cognitive tools.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(defun format-tool-result (tool-name result)
-  "Intelligently formats a tool result for user 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)))
-
-(defun execute-tool-action (action context)
-  "Executes a registered cognitive tool. (ACTUATOR)"
-  (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)))
-              (let ((feedback (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
-                                    :PAYLOAD (list :SENSOR :tool-output :RESULT result :TOOL tool-name))))
-                ;; If we have a source, send a status message with the result, formatted for humans
-                (when source
-                   (dispatch-action (list :TYPE :REQUEST :TARGET source 
-                                          :PAYLOAD (list :ACTION :MESSAGE :TEXT (format-tool-result tool-name result))) 
-                                    context))
-                feedback))
-          (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 "Tool not found")))))
-#+end_src
-
-** The Act Gate
-The final stage of the metabolic loop. It performs a "last-mile" safety check before dispatching the action to the registered actuator.
-
-#+begin_src lisp :tangle ../src/act.lisp
-(defun act-gate (signal)
-  "Final Stage: Actuation and feedback generation."
-  (let* ((approved (getf signal :approved-action))
-         (type (getf signal :type))
-         (meta (getf signal :meta))
-         (source (getf meta :source))
-         (feedback nil)
-         ;; context must keep internal objects for actuators to function
-         (context signal))
-    
-    ;; 1. Last-Mile Safety Check (The Bouncer & Deterministic Gates)
-    (when approved
-      (let* ((original-type (getf approved :type))
-             (verified (deterministic-verify approved signal)))
-        (if (and (listp verified) 
-                 (member (getf verified :type) '(:LOG :EVENT :log :event))
-                 (not (member original-type '(:LOG :EVENT :log :event))))
-            (progn
-              (harness-log "ACT BLOCKED: Action failed last-mile deterministic check.")
-              (setf (getf signal :approved-action) nil)
-              (setf approved nil)
-              (setf feedback verified))
-            (progn
-              (setf (getf signal :approved-action) verified)
-              (setf approved verified)))))
-
-    ;; 2. Actuation Logic
-    (case type
-      (:REQUEST (dispatch-action signal context))
-      (:LOG (dispatch-action signal context))
-      (:EVENT 
-       (if approved
-           (let* ((target (getf approved :target))
-                  (result (dispatch-action approved context)))
-             ;; If the actuator returns a signal (like :tool-output), it becomes the feedback.
-             ;; Otherwise, generate tool-output feedback for non-silent actuators.
-             (cond ((and (listp result) (member (getf result :type) '(:EVENT :LOG)))
-                    (setf feedback result))
-                   ((and result (not (member target *silent-actuators*)))
-                    (setf feedback (list :type :EVENT :depth (1+ (getf signal :depth 0)) :meta meta
-                                         :payload (list :sensor :tool-output :result result :tool approved))))))
-           ;; If no approved action but we have a source, this might be a raw event/log stimulus.
-           (when source
-             (dispatch-action signal context)))))
-    
-    (setf (getf signal :status) :acted)
-    feedback))
-#+end_src

literate/communication.org

@@ -1,150 +0,0 @@
-#+TITLE: Communication Protocol (communication.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:protocol:
-#+STARTUP: content
-
-* Communication Protocol (communication.lisp)
-** Architectural Intent: Secure Inter-Process Communication & Deterministic Framing
-
-The ~communication.lisp~ module defines the low-level transport and framing logic for OpenCortex stimuli. 
-
-* Implementation (communication.lisp)
-
-#+begin_src lisp :tangle ../src/package.lisp
-(in-package :opencortex)
-
-(defun proto-get (plist key)
-  "Robustly retrieves a value from a plist, checking both uppercase and lowercase keyword versions."
-  (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
-
-#+begin_src lisp :tangle ../src/communication.lisp
-(in-package :opencortex)
-
-(defvar *actuator-registry* (make-hash-table :test 'equalp)
-  "Global registry mapping target keywords to their physical actuator functions.")
-
-(defun register-actuator (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)))
-
-(defun frame-message (msg-plist)
-  "Frames a Lisp plist with a 6-character hex length and a newline for stream integrity."
-  (let* ((*print-pretty* nil)
-         (*print-circle* nil)
-         (msg-string (format nil "~s" msg-plist))
-         (len (length msg-string)))
-    (format nil "~6,'0x~a~%" len msg-string)))
-
-(defun read-framed-message (stream)
-  "Reads a hex-length prefixed S-expression from the stream securely. Skips leading whitespace."
-  (let ((length-buffer (make-string 6)))
-    (handler-case
-        (progn
-          ;; 1. Skip leading whitespace (newlines, spaces, etc.)
-          (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))
-          
-          ;; 2. Read the 6-char hex length
-          (let ((count (read-sequence length-buffer stream)))
-            (cond ((< count 6) :eof)
-                  (t (let ((len (ignore-errors (parse-integer length-buffer :radix 16))))
-                       (if (not len)
-                           (progn
-                             (harness-log "PROTOCOL ERROR: Invalid header ~s. Attempting resync..." length-buffer)
-                             :error)
-                           (let ((msg-buffer (make-string len)))
-                             (read-sequence msg-buffer stream)
-                             (let ((*read-eval* nil)
-                                   (*print-pretty* nil))
-                               (handler-case 
-                                   (let ((msg (read-from-string msg-buffer)))
-                                     (validate-communication-protocol-schema msg)
-                                     msg)
-                                 (error (c)
-                                   (harness-log "PROTOCOL PARSE ERROR: ~a in ~s" c msg-buffer)
-                                   :error))))))))))
-      (error (c) 
-        (harness-log "PROTOCOL READ ERROR: ~a" c)
-        :error))))
-
-(defun make-hello-message (version)
-  "Constructs the standard HELLO handshake message."
-  (list :TYPE :EVENT 
-        :PAYLOAD (list :ACTION :handshake 
-                       :VERSION version 
-                       :CAPABILITIES '(:AUTH :SWANK :ORG-AST))))
-#+end_src
-
-** Structural Validation (communication-validator.lisp)
-The validator ensures that incoming messages adhere to the strict property list schema of the communication protocol.
-
-#+begin_src lisp :tangle ../src/communication-validator.lisp
-(in-package :opencortex)
-
-(defun validate-communication-protocol-schema (msg)
-  "Strict structural validation for incoming communication protocol messages."
-  (unless (listp msg)
-    (error "Communication Protocol Schema Error: Message must be a property list (got ~s)" (type-of msg)))
-  
-  (let ((type (let ((raw (proto-get msg :type))) (if (keywordp raw) (intern (string-upcase (string raw)) :keyword) raw))))
-    (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG :STATUS))
-      (progn (harness-log "REJECTED MSG: ~s" msg) (error "Communication Protocol Schema Error: Invalid message type '~a'" type)))
-    
-    (case type
-      (:REQUEST 
-       (unless (proto-get msg :target)
-         (error "Communication Protocol Schema Error: REQUEST missing mandatory :target"))
-       (unless (proto-get msg :payload)
-         (error "Communication Protocol Schema Error: REQUEST missing mandatory :payload")))
-      
-      (:EVENT
-       (let ((payload (proto-get msg :payload)))
-         (unless (and payload (listp payload))
-           (error "Communication Protocol Schema Error: EVENT missing or invalid :payload"))
-         (unless (or (proto-get payload :action) (proto-get payload :sensor))
-           (error "Communication Protocol Schema Error: EVENT payload must contain :action or :sensor"))))
-      
-      (:RESPONSE
-       (unless (proto-get msg :payload)
-         (error "Communication Protocol Schema Error: RESPONSE missing mandatory :payload"))))
-    
-    t))
-
-(defskill :skill-communication-protocol-validator
-  :priority 95
-  :trigger (lambda (ctx) (member (getf (getf ctx :payload) :sensor) '(:protocol-received)))
-  :probabilistic nil
-  :deterministic (lambda (action ctx)
-              (declare (ignore ctx))
-              (validate-communication-protocol-schema action)
-              action))
-#+end_src
-
-** Message Framing (communication.lisp)
-Frames a message with a hex length prefix and ensures all data is serializable.
-
-#+begin_src lisp :tangle ../src/communication.lisp
-(defun sanitize-protocol-message (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) (sanitize-protocol-message v) v) clean)))
-        (nreverse clean))
-      msg))
-
-(defun frame-message (msg)
-  "Serializes a message plist and prefixes it with a 6-character hex length."
-  (let* ((sanitized (sanitize-protocol-message 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

literate/context.org

@@ -1,262 +0,0 @@
-#+TITLE: Peripheral Vision (context.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:context:
-#+STARTUP: content
-
-* Peripheral Vision (context.lisp)
-** Architectural Intent: Context Optimization & The Foveal-Peripheral Hybrid
-
-A common failure mode for Large Language Models (LLMs) is the "Lost in the Middle" phenomenon, where the model's reasoning accuracy degrades as its context window becomes saturated with irrelevant data. Naive approaches to context management—such as simple character-count truncation or sliding windows—often sever the structural relationships that define an Org-mode Memex.
-
-The ~opencortex~ harness implements a deterministic, tree-aware solution: the **Foveal-Peripheral Hybrid Model**.
-
-*** 1. The Foveal Focus (High Resolution)
-When the harness prepares a prompt for the Probabilistic Engine, it identifies a "Foveal Focus"—typically the specific Org headline or task the user is currently interacting with. This node, along with its immediate children and semantically relevant neighbors, is rendered at "High Resolution," meaning its full body text, properties, and metadata are included in the prompt.
-
-*** 2. The Peripheral Vision (Low Resolution)
-To maintain global awareness without bloating the context window, the rest of the Memex is rendered at "Low Resolution." The harness recursively walks the Memory and generates a skeletal outline consisting only of titles and IDs. This gives the LLM a "mental map" of the entire system, allowing it to reference other projects or skills without needing to see their full content until they are explicitly brought into focus.
-
-*** 3. Deterministic Tree-Walking
-By leveraging Common Lisp's strengths in recursive tree manipulation, the harness can surgically prune the AST before it ever reaches the LLM. This ensures that the structural hierarchy of the Memex is preserved perfectly, even when the content is compressed.
-
-** The Context Pipeline
-#+begin_src mermaid
-flowchart TD
-    Store[(Memory)] --> Filter[Context Query Filter]
-    Filter --> Identification{Identify Foveal ID}
-    Identification --> Foveal[Render Focus: Full Content]
-    Identification --> Peripheral[Render Outline: Titles Only]
-    Foveal --> Assembly[Assemble Global Awareness String]
-    Peripheral --> Assembly
-    Assembly --> LLM[Probabilistic Engine Proposal]
-#+end_src
-
-* Context Assembly (context.lisp)
-The ~context.lisp~ module provides the deterministic functional layer for querying the Memory and transforming its internal pointers into the precise context strings required for neural reasoning.
-
-** Package Context
-We begin by ensuring we are executing within the correct isolated package namespace.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(in-package :opencortex)
-#+end_src
-
-** Querying the Store (context-query-store)
-A generalized filter for the Memory. This function allows skills to perform high-level semantic sweeps of the Memex based on tags, TODO states, or Org element types. It returns a list of ~org-object~ structures.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-query-store (&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-get-active-projects)
-Identifies headlines tagged with ~project~ that have not yet reached a terminal ~DONE~ state. This provides the primary high-level structure for the agent's global awareness.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-get-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-store :tag "project" :type :HEADLINE)))
-#+end_src
-
-** Completed Tasks (context-get-recent-completed-tasks)
-Retrieves a list of tasks that have reached the terminal ~DONE~ state. This is useful for providing the agent with historical context or for generating summaries of recent work.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-get-recent-completed-tasks () 
-  "Retrieves recently finished tasks from the store."
-  (context-query-store :todo-state "DONE" :type :HEADLINE))
-#+end_src
-
-** Capability Discovery (context-list-all-skills)
-Provides a sorted list of all currently loaded skills. In a "Self-Writing" environment, the agent must be able to discover and understand its own capabilities. This function provides the metadata necessary for the agent to decide which skill to trigger or how to resolve dependencies.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-list-all-skills ()
-  "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 Inspection (context-get-skill-source)
-Reads the raw literate Org source of a specific skill. This is a foundational capability for an agent expected to eventually "self-write" or perform its own maintenance. By reading the literate source, the agent can understand the *intent* behind a skill's logic before proposing a modification. We use the `SKILLS_DIR` environment variable to locate the source files.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-get-skill-source (skill-name)
-  "Reads the raw literate source of a specific skill for inspection."
-  (let* ((filename (format nil "~a.org" skill-name))
-         (skills-dir-str (or (uiop:getenv "SKILLS_DIR") (namestring (merge-pathnames "notes/" (user-homedir-pathname)))))
-         (skills-dir (uiop:ensure-directory-pathname (context-resolve-path skills-dir-str)))
-         (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-get-system-logs)
-Retrieves the most recent entries from the harness's internal circular log buffer. This allows the Probabilistic Engine to see recent errors or successful dispatches, enabling it to course-correct or explain failures to the user. The log limit is externalized to `CONTEXT_LOG_LIMIT`.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-get-system-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-render-to-org)
-This is the core engine of the Foveal-Peripheral model. It recursively transforms the internal ~org-object~ graph back into an Org-mode string. 
-
-It implements the following deterministic logic:
-1.  **Depth 1 & 2:** Always rendered (High-level mental map).
-2.  **Foveal Node:** Rendered with full body content.
-3.  **Semantic Neighbors:** Rendered with full content if their similarity score exceeds the threshold.
-4.  **Peripheral Nodes:** Rendered as skeletal headlines (titles and IDs only).
-
-The semantic threshold is externalized to `CONTEXT_SEMANTIC_THRESHOLD`.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-render-to-org (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))
-         ;; We always render depth 1 and 2 (Projects and main tasks).
-         ;; We always render the foveal node and its immediate children.
-         ;; We render deeper nodes ONLY if they are semantically relevant.
-         (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:~%")))
-      
-      ;; Only include full body content if this is the Foveal focus or highly relevant
-      (when (and content (or is-foveal is-semantically-relevant))
-        (setf output (concatenate 'string output content (string #\Newline))))
-      
-      ;; Recursively render children
-      (dolist (child-id children)
-        (let ((child-obj (lookup-object child-id)))
-          (when child-obj
-            ;; If the current node is Foveal, its children should be rendered (depth effectively resets)
-            (let ((next-foveal (if is-foveal child-id foveal-id)))
-              (setf output (concatenate 'string output 
-                                        (context-render-to-org child-obj 
-                                                               :depth (1+ depth) 
-                                                               :foveal-id next-foveal
-                                                               :semantic-threshold threshold
-                                                               :foveal-vector foveal-vector))))))))
-    output))
-#+end_src
-
-** Path Resolution (context-resolve-path)
-A utility function that expands environment variables (like ~$HOME~ or ~$MEMEX_ROOT~) within path strings. This ensures that the agent can interact with files across different machine configurations without hardcoding absolute paths. This version is more robust, supporting multiple environment variables throughout the string.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-resolve-path (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
-
-** Global Awareness (context-assemble-global-awareness)
-The primary entry point for context generation. This function identifies active projects and the current user focus (captured during the Perceive stage), then invokes the recursive renderer to assemble the pruned Org-mode skeletal outline sent to the LLM.
-
-#+begin_src lisp :tangle ../src/context.lisp
-(defun context-assemble-global-awareness (&optional signal)
-  "Produces a high-level skeletal outline of the current Memory for the LLM."
-  (let* ((foveal-id (or (getf signal :foveal-focus) 
-                        (ignore-errors (getf (getf signal :payload) :target-id))))
-         (projects (context-get-active-projects))
-         (output "GLOBAL MEMEX AWARENESS (Peripheral Vision):
-"))
-    (if projects
-        (dolist (project projects)
-          (setf output (concatenate 'string output
-                                    (context-render-to-org project :foveal-id foveal-id))))
-        (setf output (concatenate 'string output "No active projects found.~%")))
-    output))
-#+end_src
-
-* Phase E: Chaos (Verification)
-Following the Engineering Standards, the peripheral vision extraction and rendering logic must be empirically verified. 
-
-** Test Suite Context
-#+begin_src lisp :tangle ../tests/peripheral-vision-tests.lisp
-(defpackage :opencortex-peripheral-vision-tests
-  (:use :cl :fiveam :opencortex)
-  (:export #:vision-suite))
-(in-package :opencortex-peripheral-vision-tests)
-
-(def-suite vision-suite
-  :description "Verification of Foveal-Peripheral context model.")
-(in-suite vision-suite)
-#+end_src
-
-** Foveal Rendering Test
-Verify that the foveal target is rendered with content, while siblings are skeletal.
-
-#+begin_src lisp :tangle ../tests/peripheral-vision-tests.lisp
-(test test-foveal-rendering
-  "Verify that the foveal target is rendered with content, while siblings are skeletal."
-  (clrhash opencortex::*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)
-    ;; Test both foveal focus in signal top-level and in payload (legacy)
-    (let ((output (context-assemble-global-awareness (list :foveal-focus "node-foveal"))))
-      (is (search "FOVEAL CONTENT" output))
-      (is (search "* Peripheral Node" output))
-      (is (not (search "PERIPHERAL CONTENT" output))))))
-#+end_src
-
-** Awareness Budget Test
-Verify that context-assemble-global-awareness handles multiple projects correctly.
-
-#+begin_src lisp :tangle ../tests/peripheral-vision-tests.lisp
-(test test-awareness-budget
-  "Verify that context-assemble-global-awareness handles multiple projects."
-  (clrhash opencortex::*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-assemble-global-awareness)))
-    (is (search "Project 1" output))
-    (is (search "Project 2" output))))
-#+end_src

literate/loop.org

@@ -1,106 +0,0 @@
-#+TITLE: The Metabolic Loop (loop.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:loop:
-#+STARTUP: content
-
-* The Metabolic Loop (loop.lisp)
-** Architectural Intent: The Heartbeat
-The Metabolic Loop is the high-level coordinator of the OpenCortex. It orchestrates the flow of energy (information) through the system by calling the three metabolic stages in sequence:
-1. **Perceive:** Sensory intake.
-2. **Reason:** Cognitive processing.
-3. **Act:** Physical side-effects.
-
-** Package and Variables
-The loop requires thread-safe interrupt handling to ensure that the agent can be stopped gracefully without leaving the Lisp image in an inconsistent state.
-
-#+begin_src lisp :tangle ../src/loop.lisp
-(in-package :opencortex)
-
-(defvar *interrupt-flag* nil)
-(defvar *interrupt-lock* (bt:make-lock "harness-interrupt-lock"))
-(defvar *heartbeat-thread* nil)
-#+end_src
-
-** The Metabolic Pipeline
-The `process-signal` function is the core metabolic processor. It iterates through the Perceive-Reason-Act gates until the signal is fully processed or an error state is reached. We have refined the error handling to ensure that memory rollbacks only occur on critical system failures, preventing transient tool errors from wiping short-term cognitive state.
-
-#+begin_src lisp :tangle ../src/loop.lisp
-(defun process-signal (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)))
-        (when (> depth 10) (harness-log "METABOLISM ERROR: Max depth reached.") (return nil))
-        (when (bt:with-lock-held (*interrupt-lock*) *interrupt-flag*)
-          (harness-log "METABOLISM: Interrupted.")
-          (bt:with-lock-held (*interrupt-lock*) (setf *interrupt-flag* nil))
-          (return nil))
-        (handler-case
-            (let ((parent-metadata (list :reply-stream (getf current-signal :reply-stream)
-                                         :foveal-focus (getf current-signal :foveal-focus))))
-              (setf current-signal (perceive-gate current-signal))
-              (setf current-signal (reason-gate current-signal))
-              (setf current-signal (act-gate current-signal))
-              ;; Inherit metadata for the next metabolic cycle if feedback was generated.
-              (when (and current-signal (not (getf current-signal :reply-stream)))
-                (setf (getf current-signal :reply-stream) (getf parent-metadata :reply-stream)))
-              (when (and current-signal (not (getf current-signal :foveal-focus)))
-                (setf (getf current-signal :foveal-focus) (getf parent-metadata :foveal-focus))))
-          (error (c)
-            (let ((sensor (ignore-errors (getf (getf current-signal :payload) :sensor))))
-              (harness-log "METABOLISM CRASH [~a]: ~a" (or sensor :unknown) c)
-              ;; Only rollback on critical errors, not standard tool or loop errors
-              (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) :reply-stream (getf current-signal :reply-stream)
-                                             :payload (list :sensor :loop-error :message (format nil "~a" c) :depth depth)))))))))))
-#+end_src
-
-** Heartbeat Mechanism
-The heartbeat ensures the agent remains "alive" even in the absence of external stimuli, allowing for latent reflection and periodic maintenance. The interval is externalized to the `HEARTBEAT_INTERVAL` environment variable.
-
-#+begin_src lisp :tangle ../src/loop.lisp
-(defun start-heartbeat ()
-  "Starts the background heartbeat thread. Interval is loaded from HEARTBEAT_INTERVAL."
-  (let ((interval (or (ignore-errors (parse-integer (uiop:getenv "HEARTBEAT_INTERVAL"))) 60)))
-    (setf *heartbeat-thread* 
-          (bt:make-thread 
-           (lambda () 
-             (loop 
-               (sleep interval) 
-               ;; inject-stimulus is synchronous for heartbeats, preventing accumulation.
-               (inject-stimulus (list :type :EVENT :payload (list :sensor :heartbeat :unix-time (get-universal-time)))))) 
-           :name "opencortex-heartbeat"))))
-#+end_src
-
-** Main Entry Point
-The `main` function initializes the environment, loads skills, and starts the heartbeat. It now includes a graceful shutdown handler for `SIGINT` (Ctrl+C) and uses `DAEMON_SLEEP_INTERVAL` to control its idle rhythm.
-
-#+begin_src lisp :tangle ../src/loop.lisp
-(defun main ()
-  "Entry point for the Skeleton MVP. Handles initialization and graceful shutdown."
-  (let* ((home (uiop:getenv "HOME"))
-         (env-file (uiop:merge-pathnames* ".local/share/opencortex/.env" (uiop:ensure-directory-pathname home))))
-    (when (uiop:file-exists-p env-file) (cl-dotenv:load-env env-file)))
-  
-  (initialize-actuators)
-  (initialize-all-skills)
-
-  (start-heartbeat)
-  
-  ;; Graceful shutdown handler for SBCL
-  #+sbcl
-  (sb-sys:enable-interrupt sb-unix:sigint 
-                           (lambda (sig code scp) 
-                             (declare (ignore sig code scp)) 
-                             (harness-log "SHUTDOWN: SIGINT received. Exiting...")
-                             (uiop:quit 0)))
-
-  (let ((sleep-interval (or (ignore-errors (parse-integer (uiop:getenv "DAEMON_SLEEP_INTERVAL"))) 3600)))
-    (loop 
-      (when (bt:with-lock-held (*interrupt-lock*) *interrupt-flag*) (return))
-      (sleep sleep-interval))))
-#+end_src

literate/manifest.org

@@ -1,86 +0,0 @@
-#+TITLE: Manifest (opencortex.asd)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:system:
-#+STARTUP: content
-
-* Manifest (opencortex.asd)
-** Architectural Intent: The ASDF Skeleton
-
-The ~opencortex.asd~ file is the physical blueprint of the Lisp Machine. It uses **Another System Definition Facility (ASDF)** to orchestrate the compilation and loading of all harness modules. 
-
-Traditional Lisp systems often use complex, non-linear dependency graphs. However, the ~opencortex~ harness mandates a strict, linear bootstrap sequence.
-
-*** 1. Strict Serial Loading (:serial t)
-The harness uses the ~:serial t~ flag. This is a critical design choice that ensures every file is compiled and loaded in the exact order it appears in the ~:components~ list. This eliminates "macro-not-found" errors by guaranteeing that the ~package.lisp~ and ~skills.lisp~ (where the core macros are defined) are always established before any behavioral logic or skills are loaded.
-
-*** 2. Isolation of the Verification Suite
-To maintain a "Zero-Overhead" production environment, the testing logic is isolated into a secondary system: ~:opencortex/tests~. This allows the harness to boot in production without loading the ~FiveAM~ framework or the voluminous test data, keeping the memory footprint minimal and the attack surface small.
-
-** The Build Pipeline
-#+begin_src mermaid
-flowchart TD
-    Org[Literate Org Files] -- Tangle --> Lisp[Source .lisp Files]
-    Lisp --> ASDF[ASDF Manifest: .asd]
-    ASDF --> Loader[SBCL Compiler / Loader]
-    Loader --> Image[Live Harness Image]
-    Image -- Build --> Binary[Standalone Binary]
-#+end_src
-
-** Harness System Definition
-This system defines the core "Thin Harness." It includes the protocol, the object store, and the functional loop.
-
-#+begin_src lisp :tangle ../opencortex.asd
-(defsystem :opencortex
-  :name "opencortex"
-  :author "Amr"
-  :version "0.1.0"
-  :license "AGPLv3"
-  :description "The Probabilistic-Deterministic Lisp Machine Harness"
-  :depends-on (:usocket :bordeaux-threads :dexador :uiop :cl-dotenv :cl-ppcre :hunchentoot :ironclad :str :cl-json :uuid)
-  :serial t
-  :components ((:file "src/package")
-               (:file "src/skills")
-               (:file "src/policy")
-               (:file "src/communication-validator")
-               (:file "src/communication")
-               (:file "src/memory")
-               (:file "src/context")
-               (:file "src/probabilistic")
-               (:file "src/perceive")
-               (:file "src/reason")
-               (:file "src/act")
-               (:file "src/loop"))
-  :build-operation "program-op"
-  :build-pathname "opencortex-server"
-  :entry-point "opencortex:main")
-#+end_src
-
-** Verification Suite Definition
-This system contains the empirical tests required by the Engineering Standards. It depends on ~:opencortex~ and the ~FiveAM~ testing framework.
-
-#+begin_src lisp :tangle ../opencortex.asd
-(defsystem :opencortex/tests
-  :depends-on (:opencortex :fiveam)
-  :components ((:file "tests/communication-tests")
-               (:file "tests/pipeline-tests")
-               (:file "tests/act-tests")
-               (:file "tests/boot-sequence-tests")
-               (:file "tests/memory-tests")
-               (:file "tests/immune-system-tests"))
-  :perform (test-op (o s) 
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :communication-protocol-suite :opencortex-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :pipeline-suite :opencortex-pipeline-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :safety-suite :opencortex-safety-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :boot-suite :opencortex-boot-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :memory-suite :opencortex-memory-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :immune-suite :opencortex-immune-system-tests))))
-#+end_src
-
-** TUI Client Definition
-This system defines the native Croatoan TUI client.
-
-#+begin_src lisp :tangle ../opencortex.asd
-(defsystem :opencortex/tui
-  :depends-on (:opencortex :croatoan :usocket :bordeaux-threads)
-  :components ((:file "src/tui-client")))
-#+end_src

literate/memory.org

@@ -1,287 +0,0 @@
-#+TITLE: The System Memory (memory.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:memory:
-#+STARTUP: content
-
-* The System Memory (memory.lisp)
-** Architectural Intent: The Single Address Space (Live Memory)
-
-Yes, the Memory module is the cognitive bedrock of the opencortex. It is not a database; it is the agent's live, active "brain" state.
-
-Traditional architectures rely on external databases (SQLite, Vector DBs) which introduce I/O latency and structural impedance. The opencortex architecture chooses a different path: the **Single Address Space**. By treating the entire knowledge base as a graph of Lisp pointers, we achieve microsecond recollection and total structural transparency.
-
-- **Pointer-Based Reasoning:** By loading the entire knowledge graph into a live Common Lisp hash table, we achieve microsecond recollection. The harness doesn't "search a file"; it traverses a memory pointer.
-- **Memory Imaging:** The ability to snapshot the Lisp image allows the agent to resume its entire cognitive state instantly, solving the "Cold Start" problem.
-- **Merkle-Tree Integrity:** Every node in the Memory is cryptographically hashed. By recursively hashing content and children, the root hash provides a single, immutable fingerprint of the entire system state.
-
-** System Architecture
-#+begin_src mermaid
-flowchart TD
-    subgraph LispMachine[Lisp Machine]
-        H[Harness Pipeline] --> OS[(Memory)]
-        S1[Skill: Architect] --> OS
-        S2[Skill: Analyst] --> OS
-        S3[Skill: GTD] --> OS
-        H -- Pointers --> S1
-        H -- Pointers --> S2
-    end
-    subgraph IPCSlow[External Layer]
-        E[Emacs / Actuators] -. communication protocol .-> H
-    end
-#+end_src
-
-** Package Context
-#+begin_src lisp :tangle ../src/memory.lisp
-(in-package :opencortex)
-#+end_src
-
-** The Object Repository
-The `*memory*` is the global hash table that holds every Org element by its unique ID. This is the "live RAM" of the agent's memory.
-
-#+begin_src lisp :tangle ../src/memory.lisp
-(defvar *memory* (make-hash-table :test 'equal))
-
-(defvar *history-store* (make-hash-table :test 'equal)
-  "Immutable Merkle-Tree versioning store mapping hashes to objects.")
-#+end_src
-
-** The Data Structure (org-object)
-Every element in the Memex (headlines, paragraphs, etc.) is represented by an `org-object` structure. It contains both semantic metadata (attributes, content) and structural metadata (parent/child pointers, Merkle hashes).
-
-#+begin_src lisp :tangle ../src/memory.lisp
-(defstruct org-object
-  id type attributes content vector parent-id children version last-sync hash)
-#+end_src
-
-** Merkle Tree Integrity (compute-merkle-hash)
-The `compute-merkle-hash` function ensures the cryptographic integrity of the knowledge graph. A node's hash depends on its own properties and the hashes of all its children. This creates a recursive fingerprint where any change to a single note propagates up to the root hash.
-
-#+begin_src lisp :tangle ../src/memory.lisp
-(defun compute-merkle-hash (id type attributes content child-hashes)
-  "Computes a SHA-256 Merkle hash for a node based on its core properties and children's 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
-
-** Ingesting the AST (ingest-ast)
-The `ingest-ast` function is the primary bridge between the external world (Emacs/JSON) and the internal Lisp machine. It recursively parses an Org-mode Abstract Syntax Tree (AST) into `org-object` structures and registers them in the store.
-
-#+begin_src lisp :tangle ../src/memory.lisp
-(defun ingest-ast (ast &optional parent-id)
-  "Parses an Org AST into the recursive Lisp Memory with Merkle hashing."
-  (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 (cl:getf ast :raw-content) ""))))
-         (should-embed (and raw-content (equal (getf props :EMBED) "t")))
-         (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-id-val child-id))
-             (let ((child-obj (lookup-object child-id-val)))
-               (when child-obj (push (org-object-hash child-obj) child-hashes)))))))
-    (setf child-ids (nreverse child-ids))
-    (setf child-hashes (nreverse child-hashes))
-    (let* ((hash (compute-merkle-hash id type props raw-content child-hashes))
-           (existing-obj (gethash hash *history-store*))
-           (obj (or existing-obj
-                    (make-org-object 
-                     :id id :type type :attributes props :content raw-content
-                     :vector (when should-embed (get-embedding 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 *history-store*) obj))
-      (setf (gethash id *memory*) obj)
-      id)))
-#+end_src
-
-** Memory Snapshots (snapshot-memory)
-Because objects are stored immutably in the `*history-store*`, a snapshot is a lightweight shallow copy of the active `*memory*` pointers. The system maintains a rolling buffer of 20 snapshots, allowing for near-instant, zero-cost rollback.
-
-#+begin_src lisp :tangle ../src/memory.lisp
-(defvar *object-store-snapshots* nil)
-
-(defun copy-hash-table (hash-table)
-  "Creates a shallow 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))
-
-(defun snapshot-memory ()
-  "Creates a lightweight, Copy-on-Write snapshot using Merkle-Tree pointers."
-  (let ((snapshot (copy-hash-table *memory*)))
-    (push (list :timestamp (get-universal-time) :data snapshot) *object-store-snapshots*)
-    (when (> (length *object-store-snapshots*) 20)
-      (setf *object-store-snapshots* (subseq *object-store-snapshots* 0 20)))
-    (harness-log "MEMORY - CoW Memory snapshot created.")))
-#+end_src
-
-** Memory Rollback (rollback-memory)
-Restores the state of the Memex from one of the previous snapshots.
-
-#+begin_src lisp :tangle ../src/memory.lisp
-(defun rollback-memory (&optional (index 0))
-  "Restores the Memory to a previously captured snapshot using immutable history pointers."
-  (let ((snapshot (nth index *object-store-snapshots*)))
-    (if snapshot
-        (progn (setf *memory* (copy-hash-table (getf snapshot :data)))
-               (harness-log "MEMORY - Memory rolled back to snapshot ~a" index))
-        (harness-log "MEMORY ERROR - Snapshot ~a not found." index))))
-#+end_src
-
-** Lookup Utilities
-Basic functions for retrieving objects by ID or type.
-
-#+begin_src lisp :tangle ../src/memory.lisp
-(defun org-id-new ()
-  "Generates a new UUID string for Org-mode identification."
-  (string-downcase (format nil "~a" (uuid:make-v4-uuid))))
-
-(defun lookup-object (id) 
-  "Retrieves an object from the store by its unique ID."
-  (gethash id *memory*))
-
-(defun list-objects-by-type (type)
-  "Returns a list of all objects matching a specific Org element type."
-  (let ((results nil))
-    (maphash (lambda (id obj) (declare (ignore id)) (when (eq (org-object-type obj) type) (push obj results))) *memory*)
-    results))
-(defun list-objects-with-attribute (attr-name value)
-  "Returns a list of all objects where ATTR-NAME matches VALUE."
-  (let ((results nil))
-    (maphash (lambda (id obj)
-               (declare (ignore id))
-               (let ((attrs (org-object-attributes obj)))
-                 (when (equal (getf attrs attr-name) value)
-                   (push obj results))))
-             *memory*)
-    results))
-#+end_src
-
-** Structural Helpers
-Utility functions for AST traversal and path resolution.
-
-#+begin_src lisp :tangle ../src/memory.lisp
-(defun find-headline-missing-id (ast)
-  "Traverses an AST to find headlines that lack an :ID: property."
-  (when (listp ast)
-    (if (and (eq (getf ast :type) :HEADLINE) (not (getf (getf ast :properties) :ID)))
-        ast
-        (cl:some #'find-headline-missing-id (getf ast :contents)))))
-
-(defun file-name-nondirectory (path)
-  "Extracts the filename from a full path string."
-  (let ((pos (position #\/ path :from-end t))) (if pos (subseq path (1+ pos)) path)))
-#+end_src
-
-* Phase E: Chaos (Verification)
-Following the Engineering Standards, the Memory must be empirically verified through automated testing. The following test suite ensures the mathematical integrity of the Merkle hashes and the behavioral correctness of the immutable versioning and rollback systems.
-
-#+begin_src lisp :tangle ../tests/memory-tests.lisp
-(defpackage :opencortex-memory-tests
-  (:use :cl :fiveam :opencortex)
-  (:export #:memory-suite))
-
-(in-package :opencortex-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))
-         (ast2 '(:type :HEADLINE :properties (:ID "test-1" :TITLE "Node 1") :contents nil)))
-    (clrhash *memory*)
-    (let ((id1 (ingest-ast ast1)))
-      (let ((hash1 (org-object-hash (lookup-object id1))))
-        (clrhash *memory*)
-        (let ((id2 (ingest-ast ast2)))
-          (let ((hash2 (org-object-hash (lookup-object id2))))
-            (is (equal hash1 hash2))))))))
-
-(test merkle-hash-cascading
-  (let* ((ast-leaf '(:type :HEADLINE :properties (:ID "leaf" :TITLE "Leaf") :contents nil))
-         (ast-root-full '(:type :HEADLINE :properties (:ID "root" :TITLE "Root") 
-                           :contents ((:type :HEADLINE :properties (:ID "leaf" :TITLE "Leaf") :contents nil))))
-         (id-root (progn (clrhash *memory*) (ingest-ast ast-root-full)))
-         (initial-root-hash (org-object-hash (lookup-object id-root))))
-      
-      ;; Now ingest a modified version (title change)
-      (let* ((ast-root-modified '(:type :HEADLINE :properties (:ID "root" :TITLE "Root") 
-                                 :contents ((:type :HEADLINE :properties (:ID "leaf" :TITLE "Leaf Modified") :contents nil))))
-             (id-root-mod (progn (clrhash *memory*) (ingest-ast ast-root-modified)))
-             (modified-root-hash (org-object-hash (lookup-object id-root-mod))))
-        (is (not (equal initial-root-hash modified-root-hash))))))
-
-(test history-store-immutability
-  "Verify that *history-store* retains old versions even after *memory* updates."
-  (clrhash *memory*)
-  (clrhash *history-store*)
-  (let* ((ast-v1 '(:type :HEADLINE :properties (:ID "test-node" :TITLE "Version 1") :contents nil))
-         (id-v1 (ingest-ast ast-v1))
-         (obj-v1 (lookup-object id-v1))
-         (hash-v1 (org-object-hash obj-v1)))
-    
-    (let* ((ast-v2 '(:type :HEADLINE :properties (:ID "test-node" :TITLE "Version 2") :contents nil))
-           (id-v2 (ingest-ast ast-v2))
-           (obj-v2 (lookup-object id-v2))
-           (hash-v2 (org-object-hash obj-v2)))
-      
-      ;; The active pointer should be v2
-      (is (equal (org-object-hash (lookup-object "test-node")) hash-v2))
-      
-      ;; Both v1 and v2 should exist in the immutable history store
-      (is (not (null (gethash hash-v1 *history-store*))))
-      (is (not (null (gethash hash-v2 *history-store*))))
-      
-      ;; Modifying v2 should not affect v1 in the history store
-      (is (equal (org-object-content (gethash hash-v1 *history-store*)) "Version 1
-"))
-      (is (equal (org-object-content (gethash hash-v2 *history-store*)) "Version 2
-")))))
-
-(test cow-snapshot-and-rollback
-  "Verify that lightweight snapshots can accurately restore previous pointer states."
-  (clrhash *memory*)
-  (clrhash *history-store*)
-  (setf *object-store-snapshots* nil)
-  
-  (let* ((ast-v1 '(:type :HEADLINE :properties (:ID "cow-node" :TITLE "State A") :contents nil))
-         (id-v1 (ingest-ast ast-v1))
-         (hash-v1 (org-object-hash (lookup-object id-v1))))
-    
-    ;; Take a snapshot at State A
-    (snapshot-memory)
-    
-    (let* ((ast-v2 '(:type :HEADLINE :properties (:ID "cow-node" :TITLE "State B") :contents nil))
-           (id-v2 (ingest-ast ast-v2))
-           (hash-v2 (org-object-hash (lookup-object id-v2))))
-      
-      ;; Verify we are currently in State B
-      (is (equal (org-object-hash (lookup-object "cow-node")) hash-v2))
-      
-      ;; Rollback to State A (index 0 because we only took 1 snapshot)
-      (rollback-memory 0)
-      
-      ;; Verify we are back in State A
-      (is (equal (org-object-hash (lookup-object "cow-node")) hash-v1))
-      
-      ;; Verify State B is still safely in the history store (no data loss)
-      (is (not (null (gethash hash-v2 *history-store*)))))))
-#+end_src

literate/package.org

@@ -1,246 +0,0 @@
-#+TITLE: System Interface (package.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:interface:
-#+STARTUP: content
-
-* System Interface (package.lisp)
-The ~package.lisp~ file defines the public API of the ~opencortex~ harness. It serves as the primary membrane between the deterministic core modules and the dynamic world of skills and actuators.
-
-** Architectural Intent: The Package Membrane
-By strictly defining the public interface, we ensure that skills remain decoupled from the harness implementation details. This allows for autonomous replacement of any component (e.g., swapping the Memory or the Probabilistic Engine) without breaking existing skills.
-
-#+begin_src mermaid
-flowchart TD
-    External[Actuators / Clients] -- communication protocol --> Package[Package Membrane: API]
-    Skills[Dynamic Skills] -- API Calls --> Package
-    Package --> Internal[Harness Internal Modules]
-    style Package fill:#f9f,stroke:#333,stroke-width:4px
-#+end_src
-
-** Public API Export
-#+begin_src lisp :tangle ../src/package.lisp
-(defpackage :opencortex
-  (:use :cl)
-  (:export 
-   ;; --- communication protocol ---
-   #: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
-   
-   ;; --- Daemon Lifecycle ---
-   #:start-daemon
-   #:stop-daemon
-   #:harness-log
-   #:main
-   
-   ;; --- Memory (CLOSOS) ---
-   #: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 API (Peripheral Vision) ---
-   #: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
-   #:harness-track-telemetry
-   #:context-assemble-global-awareness
-   
-   ;; --- Reactive Signal Pipeline ---
-   #:process-signal
-   #:perceive-gate
-   #:probabilistic-gate
-   #:consensus-gate
-   #:act-gate
-   #:reason-gate
-   #:perceive-gate
-   #:dispatch-gate
-   #:inject-stimulus
-   #:initialize-actuators
-   #:dispatch-action
-   #:register-actuator
-   
-   ;; --- Skill Engine ---
-   #:load-skill-from-org
-   #:initialize-all-skills
-   #:load-skill-with-timeout
-   #:topological-sort-skills
-   #:validate-lisp-syntax
-   #:defskill
-   #:*skills-registry*
-   #:skill
-   #:skill-name
-   #:skill-priority
-   #:skill-dependencies
-   #:skill-trigger-fn
-   #:skill-probabilistic-prompt
-   #:skill-deterministic-fn
-
-   ;; --- Tool Registry ---
-   #:def-cognitive-tool
-   #:*cognitive-tools*
-   #:cognitive-tool
-   #:cognitive-tool-name
-   #:cognitive-tool-description
-   #:cognitive-tool-parameters
-   #:cognitive-tool-guard
-   #:cognitive-tool-body
-
-   ;; --- Emacs Client Registry ---
-   #:*emacs-clients*
-   #:*clients-lock*
-   #:register-emacs-client
-   #:unregister-emacs-client
-
-   ;; --- Probabilistic Engine ---
-   #:ask-probabilistic
-   #:register-probabilistic-backend
-   #:distill-prompt
-   #:*provider-cascade*
-   
-   ;; --- Security Vault ---
-   #:vault-get-secret
-   #:vault-set-secret
-   
-   ;; --- Deterministic Logic ---
-   #:list-objects-with-attribute
-   #:deterministic-verify
-   
-   ;; --- AST Helpers ---
-   #:find-headline-missing-id))
-#+end_src
-
-#+begin_src lisp :tangle ../src/package.lisp
-(in-package :opencortex)
-
-(defun proto-get (plist key)
-  "Robustly retrieves a value from a plist, checking both uppercase and lowercase keyword versions."
-  (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
-
-#+end_src
-
-#+begin_src lisp :tangle ../src/package.lisp
-(in-package :opencortex)
-
-(defun proto-get (plist key)
-  "Robustly retrieves a value from a plist, checking both uppercase and lowercase keyword versions."
-  (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
-
-#+end_src
-
-** Package Implementation
-#+begin_src lisp :tangle ../src/package.lisp
-(in-package :opencortex)
-#+end_src
-
-** Harness Logging State
-The harness maintains a thread-safe circular log buffer to provide context for debugging and neural reasoning.
-
-#+begin_src lisp :tangle ../src/package.lisp
-(defvar *system-logs* nil)
-(defvar *logs-lock* (bt:make-lock "harness-logs-lock"))
-(defvar *max-log-history* 100)
-#+end_src
-
-** Skills Registry
-#+begin_src lisp :tangle ../src/package.lisp
-(defvar *skills-registry* (make-hash-table :test 'equal)
-  "Global registry of all loaded skills.")
-#+end_src
-
-** Skill Telemetry State
-#+begin_src lisp :tangle ../src/package.lisp
-(defvar *skill-telemetry* (make-hash-table :test 'equal))
-(defvar *telemetry-lock* (bt:make-lock "harness-telemetry-lock"))
-#+end_src
-
-** Telemetry Implementation
-The system tracks the performance and reliability of individual skills. This logic is currently preserved in the package layer for future expansion into a dedicated telemetry skill.
-
-#+begin_src lisp :tangle ../src/package.lisp
-(defun harness-track-telemetry (skill-name duration status)
-  "Updates performance metrics for a specific skill. Status should be :success or :rejected."
-  (when skill-name 
-    (bt:with-lock-held (*telemetry-lock*)
-      (let ((entry (or (gethash skill-name *skill-telemetry*) (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 *skill-telemetry*) entry)))))
-#+end_src
-
-** Cognitive Tool Registry
-The Tool Registry allows the agent to interact with the physical world. Every tool must define a guard (for security) and a body (for execution).
-
-#+begin_src lisp :tangle ../src/package.lisp
-(defvar *cognitive-tools* (make-hash-table :test 'equal))
-
-(defstruct cognitive-tool
-  name
-  description
-  parameters
-  guard
-  body)
-
-(defmacro def-cognitive-tool (name description parameters &key guard body)
-  "Registers a new cognitive tool into the global registry. Parameters must be a list of property lists."
-  `(setf (gethash (string-downcase (string ',name)) *cognitive-tools*)
-         (make-cognitive-tool :name (string-downcase (string ',name))
-                              :description ,description
-                              :parameters ',parameters
-                              :guard ,guard
-                              :body ,body)))
-#+end_src
-
-** Harness Logging Implementation
-Centralized logging function. It simultaneously writes to standard output and the in-memory circular buffer.
-
-#+begin_src lisp :tangle ../src/package.lisp
-(defun harness-log (msg &rest args)
-  "Centralized logging for the harness."
-  (let ((formatted-msg (apply #'format nil msg args)))
-    (bt:with-lock-held (*logs-lock*)
-      (push formatted-msg *system-logs*)
-      (when (> (length *system-logs*) *max-log-history*)
-        (setq *system-logs* (subseq *system-logs* 0 *max-log-history*))))
-    (format t "~a~%" formatted-msg)
-    (finish-output)))
-#+end_src
-
-

literate/perceive.org

@@ -1,83 +0,0 @@
-#+TITLE: Stage 1: Perceive (perceive.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:perceive:
-#+STARTUP: content
-
-* Stage 1: Perceive (perceive.lisp)
-** Architectural Intent: Sensory Ingestion
-The Perceive stage is the "sensory cortex" of the OpenCortex. It takes raw stimuli from the outside world (keyboard events, chat messages, heartbeats, or system interrupts) and normalizes them into internal **Signals**.
-
-** Async Sensor Routing
-To prevent blocking the main pipeline, certain sensors (like user commands or chat messages) are processed asynchronously in their own threads.
-
-#+begin_src lisp :tangle ../src/perceive.lisp
-(in-package :opencortex)
-
-(defvar *async-sensors* '(:chat-message :delegation :user-command)
-  "List of sensors that should be processed asynchronously to avoid blocking gateways.")
-#+end_src
-
-** Foveal Focus State
-The system tracks the user's current point of interaction to provide context to the reasoning engine.
-
-#+begin_src lisp :tangle ../src/perceive.lisp
-(defvar *foveal-focus-id* nil
-  "The Org ID of the node the user is currently interacting with.")
-#+end_src
-
-** Stimulus Injection
-The entry point for raw messages. It determines if the signal should be processed synchronously or asynchronously.
-
-#+begin_src lisp :tangle ../src/perceive.lisp
-(defun inject-stimulus (raw-message &key stream (depth 0))
-  "Enqueues a raw message into the reactive signal pipeline."
-  (let* ((payload (getf raw-message :payload)) 
-         (sensor (getf payload :sensor))
-         (async-p (or (getf payload :async-p) (member sensor *async-sensors*))))
-    (when stream (setf (getf raw-message :reply-stream) stream))
-    (if async-p 
-        (bt:make-thread 
-         (lambda () 
-           (restart-case (handler-bind ((error (lambda (c) (harness-log "ASYNC ERROR: ~a" c) (invoke-restart 'skip-event))))
-                           (process-signal raw-message)) 
-             (skip-event () nil))) 
-         :name "opencortex-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
-
-** The Perceive Gate
-The initial stage of the metabolic loop. It logs the signal, performs selective memory snapshots, and updates the Memory graph based on incoming AST updates.
-
-#+begin_src lisp :tangle ../src/perceive.lisp
-(defun perceive-gate (signal)
-  "Initial processing: Normalizes raw stimuli and updates memory."
-  (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 *foveal-focus-id* (ignore-errors (getf element :id)))
-                  (ingest-ast element))))
-             (:interrupt 
-              (bt:with-lock-held (*interrupt-lock*) (setf *interrupt-flag* t)))))
-          ((eq type :RESPONSE)
-           (harness-log "GATE [Perceive]: Act Result -> ~a" (getf payload :status))))
-           
-    (setf (getf signal :status) :perceived)
-    (setf (getf signal :foveal-focus) *foveal-focus-id*)
-    signal))
-#+end_src

literate/reason.org

@@ -1,134 +0,0 @@
-#+TITLE: Stage 2: Reason (reason.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:reason:
-#+STARTUP: content
-
-* Stage 2: Reason (reason.lisp)
-** Architectural Intent: Unified Cognition
-The Reason stage is the cognitive engine of the OpenCortex. It bridges the gap between raw sensory data (Perceive) and physical side-effects (Act). 
-
-* Cognition Engine (reason.lisp)
-
-** Package Context
-#+begin_src lisp :tangle ../src/reason.lisp
-(in-package :opencortex)
-#+end_src
-
-** Neural Backend Registry
-#+begin_src lisp :tangle ../src/reason.lisp
-(defvar *probabilistic-backends* (make-hash-table :test 'equal))
-(defvar *provider-cascade* nil)
-(defvar *model-selector-fn* nil)
-(defvar *consensus-enabled-p* nil)
-
-(defun register-probabilistic-backend (name fn)
-  "Registers a neural provider (e.g., :gemini, :anthropic) with its calling function."
-  (setf (gethash name *probabilistic-backends*) fn))
-#+end_src
-
-** Probabilistic Reasoning (probabilistic-call)
-#+begin_src lisp :tangle ../src/reason.lisp
-(defun probabilistic-call (prompt &key (system-prompt "You are the Probabilistic engine.") (cascade nil) (context nil))
-  "Dispatches a neural request through the provider cascade. Returns a Lisp plist or a failure log."
-  (let ((backends (or cascade *provider-cascade*)))
-    (or (dolist (backend backends)
-          (let ((backend-fn (gethash backend *probabilistic-backends*)))
-            (when backend-fn
-              (harness-log "PROBABILISTIC: Attempting backend ~a..." backend)
-              (let* ((model (when *model-selector-fn* (funcall *model-selector-fn* 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 (Think)
-#+begin_src lisp :tangle ../src/reason.lisp
-(defun think (context)
-  "Generates a Lisp action proposal based on current 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")))
-    (let* ((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."))))
-           (system-prompt (format nil "IDENTITY: ~a. MANDATE: Respond with ONE Lisp plist. ~a ~a RECENT_LOGS: ~a
-IMPORTANT: To reply to the user, you MUST use:
-(:TYPE :REQUEST :PAYLOAD (:ACTION :MESSAGE :TEXT \"<Response Text>\"))
-
-To call a tool, you MUST use:
-(:TYPE :REQUEST :TARGET :TOOL :ACTION :CALL :TOOL \"<name>\" :ARGS (:arg1 \"val\"))
-
-PROVIDER RULE: Always use :provider :openrouter if calling LLM tools unless specified otherwise." 
-                                  assistant-name global-context tool-belt system-logs)))
-      (let* ((thought (probabilistic-call raw-prompt :system-prompt system-prompt :context context))
-             (cleaned (if (stringp thought) (string-trim '(#\Space #\Newline #\Tab) thought) thought))
-             (meta (proto-get context :meta))
-             (source (proto-get meta :source)))
-        (if (and cleaned (stringp cleaned))
-            (let ((*read-eval* nil))
-              (if (and (> (length cleaned) 0) (char= (char cleaned 0) #\())
-                  (handler-case 
-                      (let ((parsed (read-from-string cleaned)))
-                        (let ((type (proto-get parsed :TYPE))
-                              (target (or (proto-get parsed :TARGET) (proto-get parsed :target))))
-                          (cond ((member type '(:REQUEST :EVENT :STATUS :RESPONSE))
-                                 (unless (proto-get parsed :target) (setf (getf parsed :target) (or source :CLI)))
-                                 parsed)
-                                ;; Handle raw plists that look like tool calls
-                                ((or (eq target :TOOL) (eq target :tool) (getf parsed :TOOL) (getf parsed :tool))
-                                 (list :TYPE :REQUEST :TARGET :TOOL :PAYLOAD parsed))
-                                (t (list :TYPE :REQUEST :TARGET (or source :CLI) :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned))))))
-                    (error (c) (list :TYPE :REQUEST :TARGET (or source :CLI) :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned))))
-                  (list :TYPE :REQUEST :TARGET (or source :CLI) :PAYLOAD (list :ACTION :MESSAGE :TEXT cleaned))))
-            thought)))))
-#+end_src
-
-** Deterministic Verification
-#+begin_src lisp :tangle ../src/reason.lisp
-(defun deterministic-verify (proposed-action context)
-  "Iterates through all skill deterministic-gates sorted by priority."
-  (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)))
-            (let ((original-type (proto-get current-action :type)))
-              (when (and (listp next-action) 
-                         (member (proto-get next-action :type) '(:LOG :EVENT :log :event))
-                         (or (not (member original-type '(:LOG :EVENT :log :event)))
-                             (not (eq next-action current-action))))
-                (harness-log "DETERMINISTIC: Intercepted by skill '~a'" (skill-name skill))
-                (return-from deterministic-verify next-action)))
-            (setf current-action next-action)))))
-    current-action))
-#+end_src
-
-** Reasoning Gate (The Pipeline Stage)
-#+begin_src lisp :tangle ../src/reason.lisp
-(defun reason-gate (signal)
-  "Unified Stage: Combines Probabilistic proposals and Deterministic verification."
-  (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 reason-gate signal))
-    (let ((candidate (think signal)))
-      (if candidate
-          (setf (getf signal :approved-action) (deterministic-verify candidate signal))
-          (setf (getf signal :approved-action) nil))
-      (setf (getf signal :status) :reasoned)
-      signal)))
-#+end_src

literate/setup.org

@@ -1,227 +0,0 @@
-#+TITLE: Zero-to-One Setup (setup.org)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:setup:
-#+STARTUP: content
-
-* Zero-to-One Setup (setup.org)
-The ~setup.org~ file defines the automated installation and initialization sequence for the OpenCortex.
-
-** The Installer Script (opencortex.sh)
-#+begin_src bash :tangle ../opencortex.sh
-#!/bin/bash
-set -e
-
-PORT=9105
-HOST=${1:-localhost}
-RED='\033[0;31m'; GREEN='\033[0;32m'; BLUE='\033[0;34m'; YELLOW='\033[0;33m'; NC='\033[0m'
-
-command_exists() { command -v "$1" >/dev/null 2>&1; }
-
-# Resolve symlinks to find the actual repository location
-SOURCE="${BASH_SOURCE[0]}"
-while [ -h "$SOURCE" ]; do
-    DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
-    SOURCE="$(readlink "$SOURCE")"
-    [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
-done
-export SCRIPT_DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
-
-# Load environment variables if they exist
-if [ -f "$SCRIPT_DIR/.env" ]; then
-    while IFS="=" read -r key value || [ -n "$key" ]; do
-        if [[ $key =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]]; then
-            val=$(echo "$value" | sed "s/^\"//;s/\"$//")
-            export "$key=$val"
-        fi
-    done < "$SCRIPT_DIR/.env"
-    [ -n "$HARNESS_PORT" ] && PORT=$HARNESS_PORT
-    [ -n "$HARNESS_HOST" ] && HOST=$HARNESS_HOST
-fi
-
-# --- 1. BOOTSTRAP ---
-if [ ! -d "$SCRIPT_DIR/.git" ] && [ ! -d "$HOME/.opencortex" ] && [[ ! "$(pwd)" =~ "opencortex" ]]; then
-    echo -e "${BLUE}=== OpenCortex: Zero-to-One Bootstrapper ===${NC}"
-    git clone http://10.10.10.201:3001/amr/opencortex.git ~/.opencortex
-    cd ~/.opencortex && git submodule update --init --recursive
-    exec ./opencortex.sh "$@"
-fi
-
-# --- 2. SETUP ---
-setup_system() {
-    echo -e "${BLUE}=== OpenCortex: Initializing System ===${NC}"
-    echo -e "${YELLOW}--- Installing System Dependencies ---${NC}"
-    if command_exists apt-get; then
-        sudo apt-get update && sudo apt-get install -y sbcl emacs-nox rlwrap netcat-openbsd curl git socat libssl-dev libncurses5-dev libffi-dev zlib1g-dev libsqlite3-dev
-    fi
-    if [ ! -d "$HOME/quicklisp" ]; then
-        curl -O https://beta.quicklisp.org/quicklisp.lisp
-        sbcl --non-interactive --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --eval "(ql-util:without-prompting (ql:add-to-init-file))"
-        rm quicklisp.lisp
-    fi
-    
-    cd "$SCRIPT_DIR"
-    if [ ! -f .env ]; then
-        cp .env.example .env
-
-        echo -e "\n${YELLOW}--- Identity Configuration ---${NC}"
-        read -p "Your Name [User]: " user_name < /dev/tty
-        user_name=${user_name:-User}
-        sed -i "s|MEMEX_USER=.*|MEMEX_USER=\"$user_name\"|" .env
-
-        read -p "Agent Name [OpenCortex]: " agent_name < /dev/tty
-        agent_name=${agent_name:-OpenCortex}
-        sed -i "s|MEMEX_ASSISTANT=.*|MEMEX_ASSISTANT=\"$agent_name\"|" .env
-
-        echo -e "\n${YELLOW}--- LLM Configuration ---${NC}"
-        read -p "Gemini API Key: " gemini_key < /dev/tty
-        [ -n "$gemini_key" ] && sed -i "s|GEMINI_API_KEY=.*|GEMINI_API_KEY=\"$gemini_key\"|" .env
-        read -p "Anthropic API Key: " anthropic_key < /dev/tty
-        [ -n "$anthropic_key" ] && sed -i "s|ANTHROPIC_API_KEY=.*|ANTHROPIC_API_KEY=\"$anthropic_key\"|" .env
-        read -p "OpenAI API Key: " openai_key < /dev/tty
-        [ -n "$openai_key" ] && sed -i "s|OPENAI_API_KEY=.*|OPENAI_API_KEY=\"$openai_key\"|" .env
-        read -p "OpenRouter API Key: " openrouter_key < /dev/tty
-        [ -n "$openrouter_key" ] && sed -i "s|OPENROUTER_API_KEY=.*|OPENROUTER_API_KEY=\"$openrouter_key\"|" .env
-
-        echo -e "\n${YELLOW}--- Memex Folder Structure ---${NC}"
-        read -p "Memex Root [\$HOME/memex]: " memex_dir < /dev/tty
-        memex_dir=${memex_dir:-\$HOME/memex}
-        sed -i "s|MEMEX_DIR=.*|MEMEX_DIR=\"$memex_dir\"|" .env
-        sed -i "s|\"/memex/|\"$memex_dir/|g" .env
-        sed -i "s|SKILLS_DIR=.*|SKILLS_DIR=\"$SCRIPT_DIR/skills\"|" .env
-        sed -i "s|ZETTELKASTEN_DIR=.*|ZETTELKASTEN_DIR=\"$memex_dir/notes\"|" .env
-
-        read -p "Inbox Directory [\$memex_dir/inbox]: " inbox_dir < /dev/tty
-        inbox_dir=${inbox_dir:-\$memex_dir/inbox}
-        sed -i "s|INBOX_DIR=.*|INBOX_DIR=\"$inbox_dir\"|" .env
-
-        read -p "Daily Directory [\$memex_dir/daily]: " daily_dir < /dev/tty
-        daily_dir=${daily_dir:-\$memex_dir/daily}
-        sed -i "s|DAILY_DIR=.*|DAILY_DIR=\"$daily_dir\"|" .env
-
-        read -p "Projects Directory [\$memex_dir/projects]: " proj_dir < /dev/tty
-        proj_dir=${proj_dir:-\$memex_dir/projects}
-        sed -i "s|PROJECTS_DIR=.*|PROJECTS_DIR=\"$proj_dir\"|" .env
-        
-        mkdir -p "$memex_dir" "$inbox_dir" "$daily_dir" "$proj_dir"
-        mkdir -p "$memex_dir/notes" "$memex_dir/areas" "$memex_dir/resources" "$memex_dir/archives" "$memex_dir/system"
-    fi
-
-    mkdir -p src
-    for f in literate/*.org; do
-        emacs --batch --eval "(require 'org)" --eval "(org-babel-tangle-file \"$f\")" >/dev/null 2>&1 || true
-    done
-    
-    mkdir -p "$HOME/.local/bin"
-    ln -sf "$SCRIPT_DIR/opencortex.sh" "$HOME/.local/bin/opencortex"
-
-    for shell_config in "$HOME/.bashrc" "$HOME/.profile"; do
-        if [ -f "$shell_config" ]; then
-            if ! grep -q ".local/bin" "$shell_config"; then
-                echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$shell_config"
-            fi
-        fi
-    done
-    export PATH="$HOME/.local/bin:$PATH"
-
-    echo -e "${YELLOW}--- Compiling and Loading OpenCortex (this may take a minute) ---${NC}"
-    sbcl --non-interactive --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' --eval '(push (truename (uiop:getenv "SCRIPT_DIR")) asdf:*central-registry*)' --eval "(ql:quickload '(:opencortex :croatoan))"
-    
-    if [ $? -ne 0 ]; then
-        echo -e "${RED}✗ Compilation or Loading failed.${NC}"
-        exit 1
-    fi
-
-    echo -e "${YELLOW}--- Finalizing: Awakening the Brain as a background daemon ---${NC}"
-    > "$SCRIPT_DIR/brain.log"
-    "$SCRIPT_DIR/opencortex.sh" --boot > "$SCRIPT_DIR/brain.log" 2>&1 &
-
-    local success=false
-    for i in {1..30}; do
-        if nc -z localhost $PORT 2>/dev/null; then
-            success=true
-            break
-        fi
-        sleep 2
-        echo -n "."
-    done
-
-    if [ "$success" = true ]; then
-        echo -e "\n${GREEN}✓ Brain is alive and responsive on port $PORT.${NC}"
-        echo -e "${GREEN}✓ Setup complete.${NC}"
-        if command -v opencortex >/dev/null 2>&1; then
-            echo -e "${BLUE}To start, run:${NC} ${GREEN}opencortex tui${NC}"
-        else
-            echo -e "${BLUE}To start, run:${NC} ${GREEN}exec bash && opencortex tui${NC}"
-        fi
-        exit 0
-    else
-        echo -e "\n${RED}✗ Brain failed to wake up.${NC}"
-        echo -e "${YELLOW}Full Log Path: $(realpath "$SCRIPT_DIR/brain.log")${NC}"
-        cat "$SCRIPT_DIR/brain.log"
-        exit 1
-    fi
-}
-
-# --- 3. COMMAND ROUTER ---
-# By default, if no arguments are provided, we assume the user wants the CLI fallback.
-COMMAND=${1:-"cli"}
-
-# However, if the system is completely uninitialized, we force the 'setup' command.
-if [ ! -f "$SCRIPT_DIR/src/package.lisp" ] || [ ! -f "$SCRIPT_DIR/.env" ]; then
-    COMMAND="setup"
-fi
-
-case "$COMMAND" in
-    setup)
-        setup_system
-        ;;
-        
-    --boot|boot)
-        export SKILLS_DIR="${SCRIPT_DIR}/skills"
-        [ -z "$MEMEX_DIR" ] && export MEMEX_DIR="$HOME/memex"
-        exec sbcl --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' --eval '(setf *debugger-hook* (lambda (c h) (declare (ignore h)) (format *error-output* "FATAL LISP ERROR: ~a~%" c) (uiop:print-backtrace :stream *error-output*) (uiop:quit 1)))' --eval '(push (truename (uiop:getenv "SCRIPT_DIR")) asdf:*central-registry*)' --eval '(format t "--- Quickloading OpenCortex ---~%")' --eval "(ql:quickload '(:opencortex :croatoan))" --eval '(opencortex:main)'
-        ;;
-        
-    tui)
-        if ! nc -z $HOST $PORT 2>/dev/null; then
-            echo -e "Brain is offline. Awakening..."
-            "$SCRIPT_DIR/opencortex.sh" --boot > "$SCRIPT_DIR/brain.log" 2>&1 &
-            for i in {1..15}; do
-                sleep 2
-                if nc -z $HOST $PORT 2>/dev/null; then break; fi
-                echo -n "."
-            done
-            echo ""
-        fi
-        echo -e "Launching Croatoan TUI..."
-        export SKILLS_DIR="${SCRIPT_DIR}/skills"
-        [ -z "$MEMEX_DIR" ] && export MEMEX_DIR="$HOME/memex"
-        exec sbcl --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' --eval '(push (truename (uiop:getenv "SCRIPT_DIR")) asdf:*central-registry*)' --eval '(ql:quickload :opencortex/tui)' --eval '(opencortex.tui:main)'
-        ;;
-        
-    cli)
-        if ! nc -z $HOST $PORT 2>/dev/null; then
-            echo -e "Brain is offline. Awakening..."
-            "$SCRIPT_DIR/opencortex.sh" --boot > "$SCRIPT_DIR/brain.log" 2>&1 &
-            for i in {1..15}; do
-                sleep 2
-                if nc -z $HOST $PORT 2>/dev/null; then break; fi
-                echo -n "."
-            done
-            echo ""
-        fi
-        if command_exists socat; then
-            exec socat - TCP::
-        else
-            exec nc  
-        fi
-        ;;
-        
-    *)
-        echo -e "Unknown command: $COMMAND"
-        echo "Available commands: setup, boot, tui, cli"
-        exit 1
-        ;;
-esac
-
-#+end_src

literate/skills.org

@@ -1,325 +0,0 @@
-#+TITLE: The Skill Engine (skills.lisp)
-#+AUTHOR: Amr
-#+FILETAGS: :harness:skills:
-#+STARTUP: content
-
-* The Skill Engine (skills.lisp)
-** Architectural Intent: Late-Binding Intelligence
-
-A static, hardcoded architecture is inherently fragile. The ~opencortex~ Skill Engine enables **Late-Binding Intelligence**, allowing the system to discover and integrate new cognitive capabilities (actuators, solvers, sensors) at runtime without a kernel restart.
-
-** Global Skill Registry
-
-#+begin_src lisp :tangle ../src/skills.lisp
-(in-package :opencortex)
-
-(defun COSINE-SIMILARITY (v1 v2) 1.0) ; Stub
-(defun VAULT-MASK-STRING (s) "[MASKED]") ; Stub
-(defvar *VAULT-MEMORY* (make-hash-table :test 'equal))
-
-
-(defstruct skill name priority dependencies trigger-fn probabilistic-prompt deterministic-fn)
-
-(defvar *skill-catalog* (make-hash-table :test 'equal)
-  "A stateful tracking table for all skill files discovered in the environment.")
-
-(defstruct skill-entry 
-  filename 
-  (status :discovered) ;; :discovered, :loading, :ready, :failed
-  error-log
-  (load-time 0))
-
-(defun find-triggered-skill (context)
-  "Returns the highest priority skill whose trigger matches context AND has a probabilistic prompt."
-  (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))) 
-             *skills-registry*)
-    (first (sort triggered #'> :key #'skill-priority))))
-
-(defmacro defskill (name &key priority dependencies trigger probabilistic deterministic)
-  "Registers a new skill into the global registry."
-  `(setf (gethash (string-downcase (string ,name)) *skills-registry*)
-         (make-skill :name (string-downcase (string ,name)) 
-                     :priority (or ,priority 10) 
-                     :dependencies ',dependencies
-                     :trigger-fn ,trigger 
-                     :probabilistic-prompt ,probabilistic 
-                     :deterministic-fn ,deterministic)))
-
-(defun resolve-skill-dependencies (skill-name)
-  "Recursively resolves dependencies for a given skill name."
-  (let ((resolved nil) (seen nil))
-    (labels ((visit (name) 
-               (unless (member name seen :test #'equal) 
-                 (push name seen)
-                 (let ((skill (gethash (string-downcase (string name)) *skills-registry*)))
-                   (when skill 
-                     (dolist (dep (skill-dependencies skill)) 
-                       (visit dep))))
-                 (push name resolved))))
-      (visit skill-name) 
-      (nreverse resolved))))
-#+end_src
-
-** Skill File Analysis (parse-skill-metadata)
-#+begin_src lisp :tangle ../src/skills.lisp
-(defun parse-skill-metadata (filepath)
-  "Extracts ID and DEPENDS_ON tags using robust regex scanning."
-  (let ((dependencies nil)
-        (id nil)
-        (content (uiop:read-file-string filepath)))
-    ;; Extract ID
-    (multiple-value-bind (match regs)
-        (ppcre:scan-to-strings "(?im:^:ID:\\s*([^\\s\\r\\n]+))" content)
-      (when match (setf id (aref regs 0))))
-    ;; Extract all DEPENDS_ON lines
-    (ppcre:do-register-groups (deps-string)
-        ("(?im:^#\\+DEPENDS_ON:\\s*(.*))" content)
-      (let ((deps (ppcre:split "\\s+" (string-trim " " deps-string))))
-        (setf dependencies (append dependencies (mapcar (lambda (s) (string-trim "[] " s)) deps)))))
-    (values id (remove-if (lambda (s) (= 0 (length s))) dependencies))))
-#+end_src
-
-** Dependency Resolution (topological-sort-skills)
-#+begin_src lisp :tangle ../src/skills.lisp
-(defun topological-sort-skills (skills-dir)
-  "Returns a list of skill filepaths sorted by dependency (dependencies first)."
-  (let ((files (uiop:directory-files skills-dir "org-skill-*.org"))
-        (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)))
-        (multiple-value-bind (id deps) (parse-skill-metadata 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: ~a -> ~a" filename dep-filename)
-                               (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 (load-skill-from-org)
-#+begin_src lisp :tangle ../src/skills.lisp
-(defun validate-lisp-syntax (code-string)
-  "Checks if a string contains valid, readable Common Lisp forms."
-  (handler-case 
-      (let ((*read-eval* nil)) 
-        (with-input-from-string (stream (format nil "(progn ~a)" code-string))
-          (loop for form = (read stream nil :eof) until (eq form :eof)) 
-          (values t nil)))
-    (error (c) (values nil (format nil "~a" c)))))
-
-(defun load-skill-from-org (filepath)
-  "Parses and evaluates Lisp blocks from an Org file into a jailed package."
-  (let* ((skill-base-name (pathname-name filepath))
-         (entry (or (gethash skill-base-name *skill-catalog*) (make-skill-entry :filename skill-base-name))))
-    (setf (skill-entry-status entry) :loading)
-    (setf (gethash skill-base-name *skill-catalog*) entry)
-    
-    (handler-case
-        (let* ((content (uiop:read-file-string filepath)) 
-               (lines (uiop:split-string content :separator '(#\Newline)))
-               (in-lisp-block nil) 
-               (lisp-code "") 
-               (pkg-name (intern (string-upcase (format nil "OPENCORTEX.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" (string-downcase clean-line))
-                     (if (search ":tangle" (string-downcase clean-line))
-                         (setf in-lisp-block nil)
-                         (setf in-lisp-block t)))
-                    ((uiop:string-prefix-p "#+end_src" (string-downcase clean-line))
-                     (setf in-lisp-block nil))
-                    (in-lisp-block 
-                     (unless (or (uiop:string-prefix-p ":PROPERTIES:" (string-upcase clean-line))
-                                 (uiop:string-prefix-p ":END:" (string-upcase clean-line)))
-                       (setf lisp-code (concatenate 'string lisp-code line (string #\Newline))))))))
-          
-          (if (= (length lisp-code) 0)
-              (progn (setf (skill-entry-status entry) :ready) t)
-              (progn
-                (multiple-value-bind (valid-p err) (validate-lisp-syntax lisp-code)
-                  (unless valid-p (error "Syntax Error: ~a" err)))
-                (harness-log "HARNESS: Jailing skill '~a' in package ~a" skill-base-name pkg-name)
-                (unless (find-package pkg-name)
-                  (let ((new-pkg (make-package pkg-name :use '(:cl))))
-                    (do-external-symbols (sym (find-package :opencortex)) (shadowing-import sym new-pkg))))
-                (let ((*read-eval* nil) (*package* (find-package pkg-name)))
-                  (eval (read-from-string (format nil "(progn ~a)" lisp-code))))
-                (setf (skill-entry-status entry) :ready)
-                t)))
-      (error (c)
-        (let ((msg (format nil "~a" c)))
-          (harness-log "LOADER ERROR in skill '~a': ~a" skill-base-name msg)
-          (setf (skill-entry-status entry) :failed)
-          (setf (skill-entry-error-log entry) msg)
-          nil)))))
-
-(defun load-skill-with-timeout (filepath timeout-seconds)
-  "Loads a skill Org file with a hard execution timeout."
-  (let* ((finished nil)
-         (thread (bt:make-thread (lambda () 
-                                   (if (load-skill-from-org filepath)
-                                       (setf finished t)
-                                       (setf finished :error)))
-                                 :name (format nil "loader-~a" (pathname-name filepath))))
-         (start-time (get-internal-real-time))
-         (timeout-units (truncate (* timeout-seconds internal-time-units-per-second))))
-    (loop 
-      (when (eq finished t) (return :success))
-      (when (eq finished :error) (return :error))
-      (unless (bt:thread-alive-p thread) (return :error))
-      (when (> (- (get-internal-real-time) start-time) timeout-units)
-        (harness-log "HARNESS: Timing out skill ~a..." (pathname-name filepath))
-        #+sbcl (sb-thread:terminate-thread thread)
-        #-sbcl (bt:destroy-thread thread)
-        (return :timeout))
-      (sleep 0.05))))
-#+end_src
-
-** Initializing All Skills (initialize-all-skills)
-#+begin_src lisp :tangle ../src/skills.lisp
-(defun initialize-all-skills ()
-  "Scans the directory defined by SKILLS_DIR and hot-loads skills using topological order."
-  (let* ((env-path (uiop:getenv "SKILLS_DIR"))
-         (skills-dir-str (or env-path (namestring (merge-pathnames "notes/" (user-homedir-pathname)))))
-         (resolved-path (context-resolve-path skills-dir-str))
-         (skills-dir (if resolved-path (uiop:ensure-directory-pathname resolved-path) nil)))
-    
-    (unless (and skills-dir (uiop:directory-exists-p skills-dir))
-      (harness-log "HARNESS ERROR: Skills directory not found: ~a" skills-dir-str)
-      (return-from initialize-all-skills nil))
-
-    (let ((sorted-files (topological-sort-skills skills-dir)))
-      (let* ((mandatory-env (uiop:getenv "MANDATORY_SKILLS"))
-             (mandatory-skills (if mandatory-env 
-                                   (mapcar (lambda (s) (string-trim '(#\Space #\" #\') s)) 
-                                           (uiop:split-string mandatory-env :separator '( #\,)))
-                                   '("org-skill-policy" "org-skill-bouncer"))))
-        (dolist (req mandatory-skills)
-          (unless (member req sorted-files :key #'pathname-name :test #'string-equal)
-            (error "BOOT FAILURE: Mandatory skill '~a' not found in skills directory: ~a" req (uiop:native-namestring skills-dir))))
-      
-        (harness-log "==================================================")
-        (harness-log " LOADER: Initializing ~a skills..." (length sorted-files))
-      
-        (dolist (file sorted-files)
-          (let* ((skill-name (pathname-name file))
-                 (is-mandatory (member skill-name mandatory-skills :test #'string-equal)))
-            (harness-log " LOADER: Loading ~a..." skill-name)
-            (let ((status (load-skill-with-timeout file 5)))
-              (unless (eq status :success)
-                (if is-mandatory
-                    (error "BOOT FAILURE: Mandatory skill '~a' failed to load (Status: ~a)." skill-name status)
-                    (harness-log "LOADER WARNING: Skill '~a' failed to load." skill-name))))))
-      
-        (let ((ready 0) (failed 0))
-          (maphash (lambda (k v) 
-                     (declare (ignore k))
-                     (if (eq (skill-entry-status v) :ready) (incf ready) (incf failed)))
-                   *skill-catalog*)
-          (harness-log " LOADER: Boot Complete. [Ready: ~a] [Failed: ~a]" ready failed)
-          (harness-log "==================================================")
-          (values ready failed))))))
-#+end_src
-
-** Toolbelt Prompt Generation (generate-tool-belt-prompt)
-#+begin_src lisp :tangle ../src/skills.lisp
-(defun generate-tool-belt-prompt ()
-  "Aggregates all registered cognitive tools into a descriptive prompt."
-  (let ((output (format nil "AVAILABLE TOOLS:
-You can call tools by returning a Lisp plist: (:target :tool :action :call :tool <name> :args (...))
-
-EXAMPLES:
-(:target :tool :action :call :tool \"eval\" :args (:code \"(+ 1 1)\"))
-(:target :tool :action :call :tool \"grep-search\" :args (:pattern \"autonomousty\"))
-(:target :tool :action :call :tool \"shell\" :args (:cmd \"ls -la\"))
-
----
-" )))
-    (maphash (lambda (name tool)
-               (setf output (concatenate 'string output
-                                         (format nil "- ~a: ~a~%  Parameters: ~s~%~%"
-                                                 name
-                                                 (cognitive-tool-description tool)
-                                                 (cognitive-tool-parameters tool)))))
-             *cognitive-tools*)
-    output))
-#+end_src
-
-** The Default Tool Belt
-*** The Eval Tool (Internal Inspection)
-#+begin_src lisp :tangle ../src/skills.lisp
-(def-cognitive-tool :eval "Evaluates raw Common Lisp code in the harness image. Use this for complex calculations or internal state inspection."
-  ((:code :type :string :description "The Lisp code to evaluate"))
-  :guard (lambda (args context)
-           (declare (ignore context))
-           (let ((code (getf args :code)))
-             (let ((harness-pkg (find-package :opencortex.skills.org-skill-lisp-validator)))
-               (if harness-pkg 
-                   (uiop:symbol-call :opencortex.skills.org-skill-lisp-validator :lisp-validator-validate code)
-                   t))))
-  :body (lambda (args)
-          (let ((code (getf args :code)))
-            (handler-case (let ((result (eval (read-from-string code))))
-                            (format nil "~s" result))
-              (error (c) (format nil "ERROR: ~a" c))))))
-#+end_src
-
-*** The Grep Tool (File Discovery)
-#+begin_src lisp :tangle ../src/skills.lisp
-(def-cognitive-tool :grep-search "Searches for a pattern in the project files."
-  ((:pattern :type :string :description "The regex pattern to search for")
-   (:dir :type :string :description "Directory to search in (default is project root)"))
-  :body (lambda (args)
-          (let ((pattern (getf args :pattern))
-                (dir (or (getf args :dir) (uiop:getenv "MEMEX_DIR"))))
-            (uiop:run-program (list "grep" "-r" "-n" "--exclude-dir=node_modules" pattern dir) 
-                              :output :string :ignore-error-status t))))
-#+end_src
-
-*** The Shell Tool (Machine Actuation)
-#+begin_src lisp :tangle ../src/skills.lisp
-(def-cognitive-tool :shell "Executes a shell command on the local machine. Use this for file operations, system checks, or running tests."
-  ((:cmd :type :string :description "The full bash command to execute"))
-  :guard (lambda (args context)
-           (declare (ignore context))
-           (let ((cmd (getf args :cmd)))
-             (not (or (search "rm -rf /" cmd) (search ":(){ :|:& };:" cmd)))))
-  :body (lambda (args)
-          (let ((cmd (getf args :cmd)))
-            (multiple-value-bind (out err code)
-                (uiop:run-program (list "bash" "-c" cmd) :output :string :error-output :string :ignore-error-status t)
-              (format nil "EXIT-CODE: ~a~%~%STDOUT:~%~a~%~%STDERR:~%~a" code out err)))))
-#+end_src

literate/tui-client.org

@@ -1,174 +0,0 @@
-:PROPERTIES:
-:ID:       tui-client-spec
-:CREATED:  [2026-04-17 Fri 11:00]
-:END:
-#+TITLE: OpenCortex TUI Client (Standalone)
-#+STARTUP: content
-#+FILETAGS: :tui:ux:client:
-
-* Overview
-The OpenCortex TUI Client is a standalone Common Lisp application built on **Croatoan**. It provides a real-time, multi-window interface for interacting with the OpenCortex daemon.
-
-* Implementation
-#+begin_src lisp :tangle ../src/tui-client.lisp
-(in-package :cl-user)
-(defpackage :opencortex.tui
-  (:use :cl :croatoan)
-  (:export :main))
-(in-package :opencortex.tui)
-
-(defvar *daemon-host* "127.0.0.1")
-(defvar *daemon-port* 9105)
-(defvar *socket* nil)
-(defvar *stream* nil)
-(defvar *chat-history* (list))
-(defvar *status-text* "Connecting...")
-(defvar *input-buffer* (make-array 0 :element-type 'char :fill-pointer 0 :adjustable t))
-(defvar *is-running* t)
-(defvar *queue-lock* (bt:make-lock))
-(defvar *incoming-msgs* nil)
-
-(defun enqueue-msg (msg)
-  (bt:with-lock-held (*queue-lock*)
-    (push msg *incoming-msgs*)))
-
-(defun dequeue-msgs ()
-  (bt:with-lock-held (*queue-lock*)
-    (let ((msgs (nreverse *incoming-msgs*)))
-      (setf *incoming-msgs* nil)
-      msgs)))
-
-(defun clean-keywords (msg)
-  (if (listp msg)
-      (let ((clean nil))
-        (loop for (k v) on msg by #'cddr
-              do (push (intern (string k) :keyword) clean)
-                 (push v clean))
-        (nreverse clean))
-      msg))
-
-(defun format-payload (payload)
-  "Extracts human-readable text from a protocol payload, handling nested tool calls."
-  (let* ((action (getf payload :ACTION))
-         (text (getf payload :TEXT))
-         (msg (getf payload :MESSAGE))
-         (tool (getf payload :TOOL))
-         (prompt (getf payload :PROMPT))
-         (args (getf payload :ARGS))
-         (result (getf payload :RESULT)))
-    (cond (text text)
-          (msg msg)
-          ((eq action :MESSAGE) (getf payload :TEXT))
-          ((and tool prompt) (format nil "THOUGHT [~a]: ~a" tool prompt))
-          ((and tool args) 
-           (let ((inner-prompt (or (getf args :PROMPT) (getf args :TEXT))))
-             (if inner-prompt
-                 (format nil "THOUGHT [~a]: ~a" tool inner-prompt)
-                 (format nil "CALL [~a] (ARGS: ~s)" tool args))))
-          (result (format nil "RESULT: ~a" result))
-          (t (format nil "~s" payload)))))
-
-(defun listen-thread ()
-  (loop while *is-running* do
-    (handler-case
-        (when (and *stream* (open-stream-p *stream*))
-          (let ((raw-msg (opencortex:read-framed-message *stream*)))
-            (unless (member raw-msg '(:eof :error))
-              (let* ((msg (clean-keywords raw-msg))
-                     (type (or (getf msg :TYPE) (getf msg :type)))
-                     (payload (or (getf msg :PAYLOAD) (getf msg :payload))))
-                (cond ((and (listp msg) (eq type :EVENT))
-                       (let ((action (or (getf payload :ACTION) (getf payload :action)))
-                             (text (or (getf payload :TEXT) (getf payload :text) (getf payload :MESSAGE) (getf payload :message))))
-                         (cond ((eq action :handshake) (setf *status-text* "Ready"))
-                               (text (enqueue-msg (format nil "SYSTEM: ~a" text))))))
-                      ((and (listp msg) (eq type :STATUS))
-                       (setf *status-text* (format nil "[Scribe: ~a] [Gardener: ~a]" 
-                                                   (or (getf msg :SCRIBE) (getf msg :scribe))
-                                                   (or (getf msg :GARDENER) (getf msg :gardener)))))
-                      ((and (listp msg) (member type '(:REQUEST :RESPONSE :LOG)))
-                       (let ((formatted (format-payload payload)))
-                         (when formatted (enqueue-msg formatted))))
-                      ((and (listp msg) (eq type :EVENT) (eq (getf payload :SENSOR) :TOOL-OUTPUT))
-                       (let ((formatted (format-payload payload)))
-                         (when formatted (enqueue-msg formatted))))
-                      (t (harness-log "TUI: Ignored unknown type ~a" type)))))
-            (when (eq raw-msg :eof) (setf *is-running* nil))
-            (when (eq raw-msg :error) (setf *status-text* "Protocol Error"))))
-      (error (c) (setf *status-text* (format nil "Net Error: ~a" c)) (setf *is-running* nil)))
-    (sleep 0.05)))
-
-(defun main ()
-  (handler-case
-      (setf *socket* (usocket:socket-connect *daemon-host* *daemon-port*))
-    (error (e) (format t "Error connecting: ~a~%" e) (return-from main)))
-  (setf *stream* (usocket:socket-stream *socket*))
-  (bt:make-thread #'listen-thread :name "tui-listener")
-  
-  (unwind-protect
-      (with-screen (scr :input-echoing nil :input-blocking nil :enable-colors t :cursor-visible t)
-        (let* ((h (height scr))
-               (w (width scr))
-               (chat-win (make-instance 'window :height (- h 2) :width w :position (list 0 0)))
-               (status-win (make-instance 'window :height 1 :width w :position (list (- h 2) 0)))
-               (input-win (make-instance 'window :height 1 :width w :position (list (- h 1) 0)))
-               (last-status nil))
-          
-          (setf (function-keys-enabled-p input-win) t)
-          (setf (input-blocking input-win) nil)
-
-          (loop while *is-running* do
-            ;; 1. Handle incoming messages
-            (let ((new-msgs (dequeue-msgs)))
-              (when new-msgs
-                (dolist (msg new-msgs)
-                  (push msg *chat-history*)
-                  (setf *chat-history* (subseq *chat-history* 0 (min (length *chat-history*) 500))))
-                
-                (clear chat-win)
-                (let ((line-num 0))
-                  (dolist (m (reverse (subseq *chat-history* 0 (min (length *chat-history*) (- h 3)))))
-                    (add-string chat-win m :y line-num :x 0)
-                    (incf line-num)))
-                (refresh chat-win)))
-
-            ;; 2. Render Status Bar ONLY if changed
-            (unless (equal *status-text* last-status)
-              (clear status-win)
-              (add-string status-win *status-text* :attributes '(:reverse))
-              (refresh status-win)
-              (setf last-status *status-text*))
-
-            ;; 3. Handle Keyboard Input
-            (let* ((event (get-wide-event input-win))
-                   (ch (and event (typep event 'event) (event-key event))))
-              (when ch
-                (cond
-                  ((or (eq ch #\Newline) (eq ch #\Return))
-                   (let ((cmd (coerce *input-buffer* 'string)))
-                     (setf (fill-pointer *input-buffer*) 0)
-                     (when (> (length cmd) 0)
-                       ;; Local Echo
-                       (enqueue-msg (concatenate 'string "> " cmd))
-                       ;; Send to Brain
-                       (let ((framed (opencortex:frame-message (list :TYPE :EVENT 
-                                                                    :META (list :SOURCE :tui :SESSION-ID "default")
-                                                                    :PAYLOAD (list :SENSOR :user-input :TEXT cmd)))))
-                         (format *stream* "~a" framed)
-                         (finish-output *stream*)))
-                     (when (string= cmd "/exit") (setf *is-running* nil))))
-                  ((or (eq ch :backspace) (eq ch #\Backspace) (eq ch #\Rubout) (eq ch #\Del))
-                   (when (> (length *input-buffer*) 0)
-                     (decf (fill-pointer *input-buffer*))))
-                  ((characterp ch)
-                   (vector-push-extend ch *input-buffer*))))
-              
-              (clear input-win)
-              (add-string input-win (concatenate 'string "> " (coerce *input-buffer* 'string)))
-              (move input-win 0 (+ 2 (length *input-buffer*)))
-              (refresh input-win))
-            
-            (sleep 0.02))))
-    (setf *is-running* nil)
-    (when *socket* (usocket:socket-close *socket*))))
-#+end_src

mock_daemon.lisp

@@ -1,28 +0,0 @@
-(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))
-(push (truename "./") asdf:*central-registry*)
-(ql:quickload '(:usocket :bordeaux-threads :opencortex))
-
-(defun handle-client (stream)
-  (handler-case
-      (progn
-        (format stream "~a" (opencortex:frame-message (opencortex:make-hello-message "0.1.0")))
-        (finish-output stream)
-        (loop
-          (let ((msg (opencortex:read-framed-message stream)))
-            (when (or (eq msg :eof) (eq msg :error)) (return))
-            (let ((text (getf (getf msg :payload) :text)))
-              (format t "MOCK: Received ~s~%" text)
-              (let ((resp (list :TYPE :REQUEST :PAYLOAD (list :ACTION :MESSAGE :TEXT (format nil "ECHO: ~a" text)))))
-                (format stream "~a" (opencortex:frame-message resp))
-                (finish-output stream))))))
-    (error (c) (format t "MOCK ERROR: ~a~%" c))))
-
-(let ((socket (usocket:socket-listen "127.0.0.1" 9105 :reuse-address t)))
-  (format t "MOCK DAEMON LIVE ON 9105~%")
-  (unwind-protect
-       (loop (let ((client (usocket:socket-accept socket)))
-               (bt:make-thread (lambda () 
-                                 (unwind-protect 
-                                      (handle-client (usocket:socket-stream client))
-                                   (usocket:socket-close client))))))
-    (usocket:socket-close socket)))

mock_daemon.py

@@ -1,28 +0,0 @@
-import socket
-import select
-
-server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-server.bind(('127.0.0.1', 9105))
-server.listen(1)
-print("MOCK DAEMON LIVE ON 9105")
-
-conn, addr = server.accept()
-# 1. Send Handshake
-hello = '(:TYPE :EVENT :PAYLOAD (:ACTION :HANDSHAKE :VERSION \"0.1.0\"))'
-conn.sendall(f"{len(hello):06x}{hello}".encode())
-
-# 2. Receive and Echo
-data = conn.recv(1024).decode()
-print(f"MOCK RECEIVED: {data}")
-if data:
-    payload = data[6:] # Strip hex length
-    # extract message text simple way
-    import re
-    match = re.search(r':TEXT \"([^\"]*)\"', payload)
-    text = match.group(1) if match else "unknown"
-    resp = f'(:TYPE :REQUEST :PAYLOAD (:ACTION :MESSAGE :TEXT \"PYTHON_MOCK_ECHO: {text}\"))'
-    conn.sendall(f"{len(resp):06x}{resp}".encode())
-
-conn.close()
-server.close()

opencortex.asd

@@ -1,43 +0,0 @@
-(defsystem :opencortex
-  :name "opencortex"
-  :author "Amr"
-  :version "0.1.0"
-  :license "AGPLv3"
-  :description "The Probabilistic-Deterministic Lisp Machine Harness"
-  :depends-on (:usocket :bordeaux-threads :dexador :uiop :cl-dotenv :cl-ppcre :hunchentoot :ironclad :str :cl-json :uuid)
-  :serial t
-  :components ((:file "src/package")
-               (:file "src/skills")
-               (:file "src/policy")
-               (:file "src/communication-validator")
-               (:file "src/communication")
-               (:file "src/memory")
-               (:file "src/context")
-               (:file "src/probabilistic")
-               (:file "src/perceive")
-               (:file "src/reason")
-               (:file "src/act")
-               (:file "src/loop"))
-  :build-operation "program-op"
-  :build-pathname "opencortex-server"
-  :entry-point "opencortex:main")
-
-(defsystem :opencortex/tests
-  :depends-on (:opencortex :fiveam)
-  :components ((:file "tests/communication-tests")
-               (:file "tests/pipeline-tests")
-               (:file "tests/act-tests")
-               (:file "tests/boot-sequence-tests")
-               (:file "tests/memory-tests")
-               (:file "tests/immune-system-tests"))
-  :perform (test-op (o s) 
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :communication-protocol-suite :opencortex-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :pipeline-suite :opencortex-pipeline-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :safety-suite :opencortex-safety-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :boot-suite :opencortex-boot-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :memory-suite :opencortex-memory-tests))
-             (uiop:symbol-call :fiveam :run! (uiop:find-symbol* :immune-suite :opencortex-immune-system-tests))))
-
-(defsystem :opencortex/tui
-  :depends-on (:opencortex :croatoan :usocket :bordeaux-threads)
-  :components ((:file "src/tui-client")))

opencortex.sh

@@ -1,215 +0,0 @@
-#!/bin/bash
-set -e
-
-PORT=9105
-HOST=${1:-localhost}
-RED='\033[0;31m'; GREEN='\033[0;32m'; BLUE='\033[0;34m'; YELLOW='\033[0;33m'; NC='\033[0m'
-
-command_exists() { command -v "$1" >/dev/null 2>&1; }
-
-# Resolve symlinks to find the actual repository location
-SOURCE="${BASH_SOURCE[0]}"
-while [ -h "$SOURCE" ]; do
-    DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
-    SOURCE="$(readlink "$SOURCE")"
-    [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
-done
-export SCRIPT_DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
-
-# Load environment variables if they exist
-if [ -f "$SCRIPT_DIR/.env" ]; then
-    while IFS="=" read -r key value || [ -n "$key" ]; do
-        if [[ $key =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]]; then
-            val=$(echo "$value" | sed "s/^\"//;s/\"$//")
-            export "$key=$val"
-        fi
-    done < "$SCRIPT_DIR/.env"
-    [ -n "$HARNESS_PORT" ] && PORT=$HARNESS_PORT
-    [ -n "$HARNESS_HOST" ] && HOST=$HARNESS_HOST
-fi
-
-# --- 1. BOOTSTRAP ---
-if [ ! -d "$SCRIPT_DIR/.git" ] && [ ! -d "$HOME/.opencortex" ] && [[ ! "$(pwd)" =~ "opencortex" ]]; then
-    echo -e "${BLUE}=== OpenCortex: Zero-to-One Bootstrapper ===${NC}"
-    git clone http://10.10.10.201:3001/amr/opencortex.git ~/.opencortex
-    cd ~/.opencortex && git submodule update --init --recursive
-    exec ./opencortex.sh "$@"
-fi
-
-# --- 2. SETUP ---
-setup_system() {
-    echo -e "${BLUE}=== OpenCortex: Initializing System ===${NC}"
-    echo -e "${YELLOW}--- Installing System Dependencies ---${NC}"
-    if command_exists apt-get; then
-        sudo apt-get update && sudo apt-get install -y sbcl emacs-nox rlwrap netcat-openbsd curl git socat libssl-dev libncurses5-dev libffi-dev zlib1g-dev libsqlite3-dev
-    fi
-    if [ ! -d "$HOME/quicklisp" ]; then
-        curl -O https://beta.quicklisp.org/quicklisp.lisp
-        sbcl --non-interactive --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --eval "(ql-util:without-prompting (ql:add-to-init-file))"
-        rm quicklisp.lisp
-    fi
-    
-    cd "$SCRIPT_DIR"
-    if [ ! -f .env ]; then
-        cp .env.example .env
-
-        echo -e "\n${YELLOW}--- Identity Configuration ---${NC}"
-        read -p "Your Name [User]: " user_name < /dev/tty
-        user_name=${user_name:-User}
-        sed -i "s|MEMEX_USER=.*|MEMEX_USER=\"$user_name\"|" .env
-
-        read -p "Agent Name [OpenCortex]: " agent_name < /dev/tty
-        agent_name=${agent_name:-OpenCortex}
-        sed -i "s|MEMEX_ASSISTANT=.*|MEMEX_ASSISTANT=\"$agent_name\"|" .env
-
-        echo -e "\n${YELLOW}--- LLM Configuration ---${NC}"
-        read -p "Gemini API Key: " gemini_key < /dev/tty
-        [ -n "$gemini_key" ] && sed -i "s|GEMINI_API_KEY=.*|GEMINI_API_KEY=\"$gemini_key\"|" .env
-        read -p "Anthropic API Key: " anthropic_key < /dev/tty
-        [ -n "$anthropic_key" ] && sed -i "s|ANTHROPIC_API_KEY=.*|ANTHROPIC_API_KEY=\"$anthropic_key\"|" .env
-        read -p "OpenAI API Key: " openai_key < /dev/tty
-        [ -n "$openai_key" ] && sed -i "s|OPENAI_API_KEY=.*|OPENAI_API_KEY=\"$openai_key\"|" .env
-        read -p "OpenRouter API Key: " openrouter_key < /dev/tty
-        [ -n "$openrouter_key" ] && sed -i "s|OPENROUTER_API_KEY=.*|OPENROUTER_API_KEY=\"$openrouter_key\"|" .env
-
-        echo -e "\n${YELLOW}--- Memex Folder Structure ---${NC}"
-        read -p "Memex Root [\$HOME/memex]: " memex_dir < /dev/tty
-        memex_dir=${memex_dir:-\$HOME/memex}
-        sed -i "s|MEMEX_DIR=.*|MEMEX_DIR=\"$memex_dir\"|" .env
-        sed -i "s|\"/memex/|\"$memex_dir/|g" .env
-        sed -i "s|SKILLS_DIR=.*|SKILLS_DIR=\"$SCRIPT_DIR/skills\"|" .env
-        sed -i "s|ZETTELKASTEN_DIR=.*|ZETTELKASTEN_DIR=\"$memex_dir/notes\"|" .env
-
-        read -p "Inbox Directory [\$memex_dir/inbox]: " inbox_dir < /dev/tty
-        inbox_dir=${inbox_dir:-\$memex_dir/inbox}
-        sed -i "s|INBOX_DIR=.*|INBOX_DIR=\"$inbox_dir\"|" .env
-
-        read -p "Daily Directory [\$memex_dir/daily]: " daily_dir < /dev/tty
-        daily_dir=${daily_dir:-\$memex_dir/daily}
-        sed -i "s|DAILY_DIR=.*|DAILY_DIR=\"$daily_dir\"|" .env
-
-        read -p "Projects Directory [\$memex_dir/projects]: " proj_dir < /dev/tty
-        proj_dir=${proj_dir:-\$memex_dir/projects}
-        sed -i "s|PROJECTS_DIR=.*|PROJECTS_DIR=\"$proj_dir\"|" .env
-        
-        mkdir -p "$memex_dir" "$inbox_dir" "$daily_dir" "$proj_dir"
-        mkdir -p "$memex_dir/notes" "$memex_dir/areas" "$memex_dir/resources" "$memex_dir/archives" "$memex_dir/system"
-    fi
-
-    mkdir -p src
-    for f in literate/*.org; do
-        emacs --batch --eval "(require 'org)" --eval "(org-babel-tangle-file \"$f\")" >/dev/null 2>&1 || true
-    done
-    
-    mkdir -p "$HOME/.local/bin"
-    ln -sf "$SCRIPT_DIR/opencortex.sh" "$HOME/.local/bin/opencortex"
-
-    for shell_config in "$HOME/.bashrc" "$HOME/.profile"; do
-        if [ -f "$shell_config" ]; then
-            if ! grep -q ".local/bin" "$shell_config"; then
-                echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$shell_config"
-            fi
-        fi
-    done
-    export PATH="$HOME/.local/bin:$PATH"
-
-    echo -e "${YELLOW}--- Compiling and Loading OpenCortex (this may take a minute) ---${NC}"
-    sbcl --non-interactive --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' --eval '(push (truename (uiop:getenv "SCRIPT_DIR")) asdf:*central-registry*)' --eval "(ql:quickload '(:opencortex :croatoan))"
-    
-    if [ $? -ne 0 ]; then
-        echo -e "${RED}✗ Compilation or Loading failed.${NC}"
-        exit 1
-    fi
-
-    echo -e "${YELLOW}--- Finalizing: Awakening the Brain as a background daemon ---${NC}"
-    > "$SCRIPT_DIR/brain.log"
-    "$SCRIPT_DIR/opencortex.sh" --boot > "$SCRIPT_DIR/brain.log" 2>&1 &
-
-    local success=false
-    for i in {1..30}; do
-        if nc -z localhost $PORT 2>/dev/null; then
-            success=true
-            break
-        fi
-        sleep 2
-        echo -n "."
-    done
-
-    if [ "$success" = true ]; then
-        echo -e "\n${GREEN}✓ Brain is alive and responsive on port $PORT.${NC}"
-        echo -e "${GREEN}✓ Setup complete.${NC}"
-        if command -v opencortex >/dev/null 2>&1; then
-            echo -e "${BLUE}To start, run:${NC} ${GREEN}opencortex tui${NC}"
-        else
-            echo -e "${BLUE}To start, run:${NC} ${GREEN}exec bash && opencortex tui${NC}"
-        fi
-        exit 0
-    else
-        echo -e "\n${RED}✗ Brain failed to wake up.${NC}"
-        echo -e "${YELLOW}Full Log Path: $(realpath "$SCRIPT_DIR/brain.log")${NC}"
-        cat "$SCRIPT_DIR/brain.log"
-        exit 1
-    fi
-}
-
-# --- 3. COMMAND ROUTER ---
-# By default, if no arguments are provided, we assume the user wants the CLI fallback.
-COMMAND=${1:-"cli"}
-
-# However, if the system is completely uninitialized, we force the 'setup' command.
-if [ ! -f "$SCRIPT_DIR/src/package.lisp" ] || [ ! -f "$SCRIPT_DIR/.env" ]; then
-    COMMAND="setup"
-fi
-
-case "$COMMAND" in
-    setup)
-        setup_system
-        ;;
-        
-    --boot|boot)
-        export SKILLS_DIR="${SCRIPT_DIR}/skills"
-        [ -z "$MEMEX_DIR" ] && export MEMEX_DIR="$HOME/memex"
-        exec sbcl --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' --eval '(setf *debugger-hook* (lambda (c h) (declare (ignore h)) (format *error-output* "FATAL LISP ERROR: ~a~%" c) (uiop:print-backtrace :stream *error-output*) (uiop:quit 1)))' --eval '(push (truename (uiop:getenv "SCRIPT_DIR")) asdf:*central-registry*)' --eval '(format t "--- Quickloading OpenCortex ---~%")' --eval "(ql:quickload '(:opencortex :croatoan))" --eval '(opencortex:main)'
-        ;;
-        
-    tui)
-        if ! nc -z $HOST $PORT 2>/dev/null; then
-            echo -e "Brain is offline. Awakening..."
-            "$SCRIPT_DIR/opencortex.sh" --boot > "$SCRIPT_DIR/brain.log" 2>&1 &
-            for i in {1..15}; do
-                sleep 2
-                if nc -z $HOST $PORT 2>/dev/null; then break; fi
-                echo -n "."
-            done
-            echo ""
-        fi
-        echo -e "Launching Croatoan TUI..."
-        export SKILLS_DIR="${SCRIPT_DIR}/skills"
-        [ -z "$MEMEX_DIR" ] && export MEMEX_DIR="$HOME/memex"
-        exec sbcl --eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))' --eval '(push (truename (uiop:getenv "SCRIPT_DIR")) asdf:*central-registry*)' --eval '(ql:quickload :opencortex/tui)' --eval '(opencortex.tui:main)'
-        ;;
-        
-    cli)
-        if ! nc -z $HOST $PORT 2>/dev/null; then
-            echo -e "Brain is offline. Awakening..."
-            "$SCRIPT_DIR/opencortex.sh" --boot > "$SCRIPT_DIR/brain.log" 2>&1 &
-            for i in {1..15}; do
-                sleep 2
-                if nc -z $HOST $PORT 2>/dev/null; then break; fi
-                echo -n "."
-            done
-            echo ""
-        fi
-        if command_exists socat; then
-            exec socat - TCP::
-        else
-            exec nc  
-        fi
-        ;;
-        
-    *)
-        echo -e "Unknown command: $COMMAND"
-        echo "Available commands: setup, boot, tui, cli"
-        exit 1
-        ;;
-esac

org/channel-cli.org

@@ -0,0 +1,72 @@
+#+TITLE: SKILL: CLI Gateway (org-skill-cli-gateway.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:gateway:cli:
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-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.
+
+** Contract
+
+1. (channel-cli-input text): wraps text in a ~:user-input~ envelope
+   with ~:source :CLI~ and injects into the pipeline via
+   ~stimulus-inject~.
+
+* Implementation
+
+** Package Context
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** CLI Command Handling
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defun channel-cli-input (text)
+  "Processes raw text from the command line."
+  (stimulus-inject (list :type :EVENT 
+                         :payload (list :sensor :user-input :text text) 
+                         :meta (list :source :CLI))))
+#+end_src
+
+** Skill Registration
+#+begin_src lisp
+(defskill :passepartout-channel-cli
+  :priority 100
+  :trigger (lambda (ctx) (eq (getf (getf ctx :meta) :source) :CLI))
+  :deterministic (lambda (action ctx) (declare (ignore ctx)) action))
+#+end_src
+
+* Test Suite
+
+#+begin_src lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-channel-cli-tests
+  (:use :cl :passepartout)
+  (:export #:cli-suite))
+
+(in-package :passepartout-channel-cli-tests)
+
+(fiveam:def-suite cli-suite :description "Verification of the CLI Gateway")
+(fiveam:in-suite cli-suite)
+
+(fiveam:test test-channel-cli-input-format
+  "Contract 1: channel-cli-input injects a properly formed signal without error."
+  (handler-case
+      (progn (channel-cli-input "hello") (fiveam:pass))
+    (error (c)
+      (fiveam:fail "channel-cli-input crashed: ~a" c))))
+#+end_src
+
+** Load-Time Sanity Check
+
+Verifies the function exists and can be called at load time without
+depending on FiveAM macro resolution in the jailed package.
+
+#+begin_src lisp
+(handler-case
+    (progn (channel-cli-input "test-load") (log-message "CLI: Load-time test OK"))
+  (error (c) (log-message "CLI: Load-time test FAILED: ~a" c)))
+#+end_src

org/channel-discord.org

@@ -0,0 +1,90 @@
+#+TITLE: Channel Discord (channel-discord.org)
+#+AUTHOR: Agent
+#+FILETAGS: :channel:discord:
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-discord.lisp
+
+* Channel Discord
+
+Extracted from gateway-messaging in v0.5.0. Isolated platform — Discord-specific poll and send logic.
+
+* Overview
+
+The Discord channel provides bidirectional communication via the Discord REST API
+and Gateway WebSocket. Messages received from Discord channels are injected into
+the cognitive pipeline as ~:user-input~ signals with ~:source :discord~. Outbound
+messages route through the actuator registry when the pipeline targets ~:discord~.
+
+The channel uses two functions: ~discord-poll~ (inbound sensor, REST polling)
+and ~discord-send~ (outbound actuator, REST POST). Both retrieve the bot token
+from the credentials vault (~vault-get-secret :discord~). HITL commands are
+intercepted before injection so approval flows work identically across all channels.
+
+** Contract
+
+1. (discord-get-token): returns the Discord bot token from the vault
+   (via ~vault-get-secret :discord~), or nil if not configured.
+2. (discord-poll): polls configured channels via GET /channels/{id}/messages,
+   injects each non-bot message as a ~:user-input~ stimulus with
+   ~:source :discord~. Handles JSON parse failures and API errors
+   gracefully. HITL commands are intercepted before injection.
+3. (discord-send action context): sends a message via POST /channels/{id}/messages.
+   Extracts ~:channel-id~ and ~:text~ from the action plist. Uses bot token
+   authentication. Logs send failures without crashing the pipeline.
+
+* Implementation
+
+#+begin_src lisp
+(in-package :passepartout)
+(defun discord-get-token ()
+  (vault-get-secret :discord))
+
+(defun discord-send (action context)
+  "Sends a message via Discord REST API."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (meta (getf action :meta))
+         (channel-id (or (getf meta :channel-id) (getf payload :chat-id)))
+         (text (or (getf payload :text) (getf action :text)))
+         (token (discord-get-token)))
+    (when (and token channel-id text)
+      (handler-case
+          (dex:post (format nil "https://discord.com/api/v10/channels/~a/messages" channel-id)
+                    :headers '(("Authorization" . ,(format nil "Bot ~a" token))
+                               ("Content-Type" . "application/json"))
+                    :content (cl-json:encode-json-to-string
+                              `((content . ,text))))
+        (error (c) (log-message "DISCORD ERROR: ~a" c))))))
+
+(defun discord-poll ()
+  "Polls Discord via HTTP GET /channels/{id}/messages. In production,
+a WebSocket connection to the Gateway is preferred for real-time events."
+  (let* ((token (discord-get-token)))
+    (when token
+      (handler-case
+          (dolist (channel '("channel-id-here"))  ;; configured channel IDs
+            (let* ((last-id (getf (gethash "discord" *gateway-configs*) :last-update-id 0))
+                   (url (format nil "https://discord.com/api/v10/channels/~a/messages?after=~a"
+                               channel last-id))
+                   (response (dex:get url :headers
+                                       `(("Authorization" . ,(format nil "Bot ~a" token))))))
+              (let ((messages (ignore-errors
+                               (cdr (assoc :message
+                                      (cl-json:decode-json-from-string response))))))
+                (dolist (msg (and (listp messages) messages))
+                  (let* ((id (cdr (assoc :id msg)))
+                         (content (cdr (assoc :content msg)))
+                         (author (cdr (assoc :author msg)))
+                         (author-id (cdr (assoc :id author)))
+                         (is-bot (cdr (assoc :bot author))))
+                    (when (and id content (not is-bot))
+                      (setf (getf (gethash "discord" *gateway-configs*) :last-update-id) id)
+                      (unless (ignore-errors (hitl-handle-message content :discord))
+                        (stimulus-inject
+                         (list :type :EVENT
+                               :meta (list :source :discord :chat-id channel)
+                               :payload (list :sensor :user-input :text content))))))))))
+        (error (c) (log-message "DISCORD POLL ERROR: ~a" c))))))
+#+end_src
+
+
+#+end_src

org/channel-shell.org

@@ -0,0 +1,135 @@
+#+TITLE: SKILL: Shell Actuator (org-skill-shell-actuator.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:actuator:shell:
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-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 Dispatcher's shell safety gate blocks destructive commands (~rm -rf /~, ~dd~, ~mkfs~)
+2. The Dispatcher's injection gate blocks backtick and ~$()~ patterns
+3. The Dispatcher'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
+6. (v0.4.3) When ~bwrap~ (Bubblewrap) is available, commands execute inside a Linux namespace sandbox with network and IPC isolation
+
+** Contract
+
+1. (bwrap-available-p): returns T if ~bwrap~ is installed and usable, NIL otherwise.
+   Cached at load time via ~which bwrap~.
+2. (bwrap-wrap-command cmd timeout memex-dir): returns a command list suitable for
+   ~uiop:run-program~ — wraps ~cmd~ in a ~bwrap~ sandbox with ~--unshare-net~,
+   ~--unshare-ipc~, ~--ro-bind~ for system dirs, and ~--bind~ for the memex and /tmp.
+3. (actuator-shell-execute action context): when ~bwrap~ is available, wraps the
+   command through the sandbox. When ~bwrap~ is unavailable, falls back to the
+   existing ~timeout bash -c~ behavior.
+
+* Implementation
+
+** Shell Execution (actuator-shell-execute)
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(in-package :passepartout)
+
+(defvar *bwrap-available* nil
+  "Set to T at load time if the bwrap binary is found in PATH.")
+
+(defvar *bwrap-base-args*
+  '("--ro-bind" "/usr" "/usr"
+    "--ro-bind" "/lib" "/lib"
+    "--ro-bind" "/bin" "/bin"
+    "--ro-bind" "/etc" "/etc"
+    "--bind" "/tmp" "/tmp"
+    "--unshare-net"
+    "--unshare-ipc")
+  "Base bwrap arguments for the sandbox. --bind ~/memex ~/memex is added dynamically.")
+
+(defun bwrap-available-p ()
+  "Returns T if bwrap (bubblewrap) is installed and usable."
+  *bwrap-available*)
+
+(defun bwrap-wrap-command (cmd timeout memex-dir)
+  "Wrap CMD in a bwrap sandbox with network and IPC isolation.
+Returns a list suitable for uiop:run-program."
+  `("bwrap"
+    ,@*bwrap-base-args*
+    "--bind" ,memex-dir ,memex-dir
+    "timeout" ,(format nil "~a" timeout)
+    "bash" "-c" ,cmd))
+
+;; Initialize at load time
+(setf *bwrap-available*
+      (= 0 (nth-value 2 (uiop:run-program '("which" "bwrap") :output nil :error-output nil :ignore-error-status t))))
+
+(defun actuator-shell-execute (action context)
+  "Executes a shell command via the OS timeout binary with output limit.
+When bwrap is available, wraps the command in a Linux namespace sandbox."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (cmd (getf payload :cmd))
+         (timeout-sym (find-symbol "*DISPATCHER-SHELL-TIMEOUT*" :passepartout))
+         (timeout (or (getf payload :timeout) (if timeout-sym (symbol-value timeout-sym) 30)))
+         (max-sym (find-symbol "*DISPATCHER-SHELL-MAX-OUTPUT*" :passepartout))
+         (max-output (or (getf payload :max-output) (if max-sym (symbol-value max-sym) 100000)))
+         (memex-dir (or (uiop:getenv "MEMEX_DIR") (namestring (merge-pathnames "memex/" (user-homedir-pathname))))))
+    (log-message "ACT [Shell]: ~a (timeout: ~as)~@[ bwrap: enabled~]" cmd timeout (and *bwrap-available* " (bwrap)"))
+    (let ((cmdline (if *bwrap-available*
+                       (bwrap-wrap-command cmd timeout memex-dir)
+                       (list "timeout" (format nil "~a" timeout) "bash" "-c" cmd))))
+      (multiple-value-bind (out err code)
+          (uiop:run-program cmdline
+                            :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-channel-shell
+  :priority 50
+  :trigger (lambda (ctx) (declare (ignore ctx)) nil))
+#+end_src
+
+* Test Suite
+#+begin_src lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-shell-actuator-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:shell-actuator-suite))
+
+(in-package :passepartout-shell-actuator-tests)
+
+(def-suite shell-actuator-suite :description "Verification of the Shell Actuator")
+(in-suite shell-actuator-suite)
+
+(test test-bwrap-wrap-command
+  "Contract 2: bwrap-wrap-command returns properly formatted command list."
+  (let ((cmdline (passepartout::bwrap-wrap-command "echo hello" 30 "/home/user/memex")))
+    (is (member "bwrap" cmdline :test #'string=))
+    (is (member "--unshare-net" cmdline :test #'string=))
+    (is (member "--unshare-ipc" cmdline :test #'string=))
+    (is (member "echo hello" cmdline :test #'string=))))
+
+(test test-bwrap-available-p-returns-boolean
+  "Contract 1: bwrap-available-p returns T or NIL."
+  (let ((avail (passepartout::bwrap-available-p)))
+    (is (typep avail 'boolean))))
+
+(test test-actuator-shell-execute-echo
+  "Contract 3: actuator-shell-execute runs echo and returns output."
+  (let* ((action '(:type :REQUEST :target :shell :payload (:cmd "echo hello")))
+         (result (passepartout::actuator-shell-execute action nil)))
+    (is (stringp result))
+    (is (search "hello" result :test #'char-equal))))
+#+end_src

org/channel-signal.org

@@ -0,0 +1,82 @@
+#+TITLE: Channel Signal (channel-signal.org)
+#+AUTHOR: Agent
+#+FILETAGS: :channel:signal:
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-signal.lisp
+
+* Channel Signal
+
+Extracted from gateway-messaging in v0.5.0. Isolated platform — Signal-specific poll and send logic.
+
+* Overview
+
+The Signal channel provides bidirectional communication via the ~signal-cli~ CLI tool.
+Messages received from Signal contacts are injected into the cognitive pipeline
+as ~:user-input~ signals with ~:source :signal~. Outbound messages route through
+the actuator registry when the pipeline targets ~:signal~.
+
+The channel uses two functions: ~signal-poll~ (inbound sensor) and ~signal-send~
+(outbound actuator). Both retrieve the Signal account identifier from the
+credentials vault. HITL commands (~/approve~, ~/deny~) are intercepted before
+injection so approval flows work identically across all channels.
+
+** Contract
+
+1. (signal-get-account): returns the Signal phone number from the vault
+   (via ~vault-get-secret :signal~), or nil if not configured.
+2. (signal-poll): queries ~signal-cli receive --json~ for new messages,
+   injects each non-system message as a ~:user-input~ stimulus with
+   ~:source :signal~. Handles JSON parse failures and network errors
+   gracefully (logs and continues). HITL commands are intercepted before
+   injection.
+3. (signal-send action context): sends a message via ~signal-cli send~.
+   Extracts ~:chat-id~ and ~:text~ from the action plist. Logs send
+   failures without crashing the pipeline.
+
+* Implementation
+
+#+begin_src lisp
+(in-package :passepartout)
+(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)
+                    (log-message "SIGNAL: Received message from ~a" source)
+                    (unless (ignore-errors (hitl-handle-message text :signal))
+                      (stimulus-inject
+                       (list :type :EVENT
+                             :meta (list :source :signal :chat-id source)
+                             :payload (list :sensor :user-input :text text)))))))))
+        (error (c) (log-message "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)
+      (handler-case
+          (uiop:run-program (list "signal-cli" "-u" account "send" "-m" text chat-id)
+                            :output :string :error-output :string)
+        (error (c) (log-message "SIGNAL ERROR: ~a" c))))))
+#+end_src
+
+
+#+end_src

org/channel-slack.org

@@ -0,0 +1,86 @@
+#+TITLE: Channel Slack (channel-slack.org)
+#+AUTHOR: Agent
+#+FILETAGS: :channel:slack:
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-slack.lisp
+
+* Channel Slack
+
+Extracted from gateway-messaging in v0.5.0. Isolated platform — Slack-specific poll and send logic.
+
+* Overview
+
+The Slack channel provides bidirectional communication via the Slack Web API
+(chat.postMessage for outbound, conversations.history for inbound polling).
+Messages from Slack channels are injected into the cognitive pipeline as
+~:user-input~ signals with ~:source :slack~. Outbound messages route through
+the actuator registry when the pipeline targets ~:slack~.
+
+The channel uses two functions: ~slack-poll~ (inbound sensor) and ~slack-send~
+(outbound actuator). Both retrieve the bot token from the credentials vault.
+HITL commands are intercepted before injection so approval flows work identically
+across all channels.
+
+** Contract
+
+1. (slack-get-token): returns the Slack bot token from the vault
+   (via ~vault-get-secret :slack~), or nil if not configured.
+2. (slack-poll): polls configured channels via conversations.history,
+   injects each non-bot message as a ~:user-input~ stimulus with
+   ~:source :slack~. Handles API errors gracefully. HITL commands are
+   intercepted before injection.
+3. (slack-send action context): sends a message via chat.postMessage.
+   Extracts ~:channel-id~ and ~:text~ from the action plist. Uses Bearer
+   token authentication. Logs send failures without crashing the pipeline.
+
+* Implementation
+
+#+begin_src lisp
+(in-package :passepartout)
+(defun slack-get-token ()
+  (vault-get-secret :slack))
+
+(defun slack-send (action context)
+  "Sends a message via Slack Web API."
+  (declare (ignore context))
+  (let* ((payload (getf action :payload))
+         (meta (getf action :meta))
+         (channel (or (getf meta :channel-id) (getf payload :chat-id)))
+         (text (or (getf payload :text) (getf action :text)))
+         (token (slack-get-token)))
+    (when (and token channel text)
+      (handler-case
+          (dex:post "https://slack.com/api/chat.postMessage"
+                    :headers `(("Authorization" . ,(format nil "Bearer ~a" token))
+                               ("Content-Type" . "application/json; charset=utf-8"))
+                    :content (cl-json:encode-json-to-string
+                              `((channel . ,channel) (text . ,text))))
+        (error (c) (log-message "SLACK ERROR: ~a" c))))))
+
+(defun slack-poll ()
+  "Polls Slack for new messages via conversations.history."
+  (let* ((token (slack-get-token)))
+    (when token
+      (dolist (channel '("general"))  ;; configured channel IDs
+        (handler-case
+            (let* ((url (format nil "https://slack.com/api/conversations.history?channel=~a&limit=5" channel))
+                   (response (dex:get url :headers
+                                       `(("Authorization" . ,(format nil "Bearer ~a" token))))))
+              (let* ((json (ignore-errors (cl-json:decode-json-from-string response)))
+                     (ok (cdr (assoc :ok json)))
+                     (messages (cdr (assoc :messages json))))
+                (when (and ok messages (listp messages))
+                  (dolist (msg messages)
+                    (let* ((text (cdr (assoc :text msg)))
+                           (user (cdr (assoc :user msg)))
+                           (ts (cdr (assoc :ts msg))))
+                      (when (and text user (not (string= user "USLACKBOT")))
+                        (unless (ignore-errors (hitl-handle-message text :slack))
+                          (stimulus-inject
+                           (list :type :EVENT
+                                 :meta (list :source :slack :chat-id channel)
+                                 :payload (list :sensor :user-input :text text))))))))))
+          (error (c) (log-message "SLACK POLL ERROR: ~a" c)))))))
+#+end_src
+
+
+#+end_src

org/channel-telegram.org

@@ -0,0 +1,90 @@
+#+TITLE: Channel Telegram (channel-telegram.org)
+#+AUTHOR: Agent
+#+FILETAGS: :channel:telegram:
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-telegram.lisp
+
+* Channel Telegram
+
+Extracted from gateway-messaging in v0.5.0. Isolated platform — Telegram-specific poll and send logic.
+
+* Overview
+
+The Telegram channel provides bidirectional communication via the Telegram Bot
+API. Messages from Telegram chats are injected into the cognitive pipeline as
+~:user-input~ signals with ~:source :telegram~. Outbound messages route through
+the actuator registry when the pipeline targets ~:telegram~.
+
+The channel uses two functions: ~telegram-poll~ (inbound sensor, getUpdates
+with offset tracking) and ~telegram-send~ (outbound actuator, sendMessage).
+Both retrieve the bot token from the credentials vault. The polling offset
+(~:last-update-id~ in ~*gateway-configs*~) prevents duplicate processing across
+poll cycles. HITL commands are intercepted before injection so approval flows
+work identically across all channels.
+
+** Contract
+
+1. (telegram-get-token): returns the Telegram bot token from the vault
+   (via ~vault-get-secret :telegram~), or nil if not configured.
+2. (telegram-poll): polls getUpdates with offset tracking (prevents
+   duplicate processing), injects each message as a ~:user-input~ stimulus
+   with ~:source :telegram~. Updates ~:last-update-id~ per cycle. Handles
+   API and JSON parse errors gracefully. HITL commands are intercepted
+   before injection.
+3. (telegram-send action context): sends a message via sendMessage.
+   Extracts ~:chat-id~ and ~:text~ from the action plist. Logs send
+   failures without crashing the pipeline.
+
+* Implementation
+
+#+begin_src lisp
+(in-package :passepartout)
+(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)
+                    (log-message "TELEGRAM: Received message from ~a" chat-id)
+                    (unless (ignore-errors (hitl-handle-message text :telegram))
+                      (stimulus-inject
+                       (list :type :EVENT
+                             :meta (list :source :telegram :chat-id (format nil "~a" chat-id))
+                             :payload (list :sensor :user-input :text text))))))))
+          (error (c) (log-message "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)
+      (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) (log-message "TELEGRAM ERROR: ~a" c))))))
+#+end_src
+
+
+#+end_src

org/channel-tui-state.org

@@ -0,0 +1,367 @@
+#+TITLE: Passepartout TUI — Model
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-state.lisp
+
+* Model
+
+The TUI state is a single plist accessed via ~st~ / ~(setf st)~.
+All state mutation flows through event handlers in the controller.
+
+** Contract
+
+1. (init-state): returns a fresh state plist with ~:msgs~ list,
+   ~:input~ buffer, ~:dirty~ flag, ~:busy~ flag, and ~:connection~ status.
+2. (add-msg role content &key gate-trace): appends a message object
+   to the ~:messages~ vector (v0.3.3), tagged with timestamp, role,
+   and optional gate-trace from the daemon (v0.4.0).
+3. (queue-event ev): thread-safely enqueues an event for the
+   reader loop. (drain-queue) returns and clears the queue.
+
+** Package + State
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-state.lisp
+(defpackage :passepartout.channel-tui
+  (:use :cl :passepartout :usocket :bordeaux-threads)
+  (:export :tui-main :st :add-msg :now
+           :queue-event :drain-queue :init-state
+            :view-status :view-chat :view-input :redraw
+            :input-panel-top
+            :on-key :process-key-event :input-text :on-daemon-msg :send-daemon
+            :connect-daemon :disconnect-daemon
+            :*theme* :theme-color :theme-switch))
+(in-package :passepartout.channel-tui)
+
+(defvar *state* nil)
+(defvar *event-queue* nil)
+(defvar *event-lock* (bt:make-lock "tui-event-lock"))
+
+(defvar *theme* (cl-tty.theme:make-theme)
+  "The active theme instance. Populated by cl-tty.theme:load-preset.
+
+Semantic keys (all presets define these):
+  :user-fg, :user-bg, :user-border, :agent-border, :agent-header, :agent-fg,
+  :system, :input-prompt, :input-fg, :hint, :status-bg, :status-fg,
+  :bg, :bg-panel, :bg-element, :bg-input, :text-muted,
+  :dot-connected, :dot-disconnected, :error,
+  :tool-running, :tool-done, :tool-error,
+  :thinking-bg, :symbolic-border, :separator, :accent, :dim.")
+
+(cl-tty.theme:define-preset :amber
+  :dark (:user-fg "#fab283" :user-bg "#1e1e1e" :user-border "#fab283"
+          :agent-border "#c0a080" :agent-header "#d4956a" :agent-fg "#e8e8e8"
+          :system "#808080"
+          :input-prompt "#fab283" :input-fg "#e8e8e8" :hint "#606060"
+          :status-bg "#141414" :status-fg "#e8e8e8"
+          :bg "#0a0a0a" :bg-panel "#141414" :bg-element "#1e1e1e"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#7fd88f" :dot-disconnected "#e06c75"
+          :error "#e06c75"
+          :tool-running "#fab283" :tool-done "#7fd88f" :tool-error "#e06c75"
+          :thinking-bg "#3a3a3a" :symbolic-border "#707070"
+          :separator "#3c3c3c" :accent "#fab283" :dim "#606060")
+  :light nil)
+(cl-tty.theme:define-preset :gold
+  :dark (:user-fg "#ffd700" :user-bg "#1e1e1e" :user-border "#ffd700"
+          :agent-border "#c0a080" :agent-header "#d4a574" :agent-fg "#e8e8e8"
+          :system "#808080"
+          :input-prompt "#ffd700" :input-fg "#e8e8e8" :hint "#606060"
+          :status-bg "#141414" :status-fg "#ffd700"
+          :bg "#0a0a0a" :bg-panel "#141414" :bg-element "#1e1e1e"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#7fd88f" :dot-disconnected "#e06c75"
+          :error "#e06c75"
+          :tool-running "#ffd700" :tool-done "#7fd88f" :tool-error "#e06c75"
+          :thinking-bg "#3a3a3a" :symbolic-border "#707070"
+          :separator "#3c3c3c" :accent "#ffd700" :dim "#606060")
+  :light nil)
+(cl-tty.theme:define-preset :terracotta
+  :dark (:user-fg "#e87a5d" :user-bg "#1e1e1e" :user-border "#e87a5d"
+          :agent-border "#c0a080" :agent-header "#d4956a" :agent-fg "#e0c8b0"
+          :system "#808080"
+          :input-prompt "#e87a5d" :input-fg "#e0c8b0" :hint "#606060"
+          :status-bg "#141414" :status-fg "#d4956a"
+          :bg "#0a0a0a" :bg-panel "#141414" :bg-element "#1e1e1e"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#6cb85c" :dot-disconnected "#d94a3a"
+          :error "#d94a3a"
+          :tool-running "#e87a5d" :tool-done "#6cb85c" :tool-error "#d94a3a"
+          :thinking-bg "#3a3a3a" :symbolic-border "#707070"
+          :separator "#3c3c3c" :accent "#e87a5d" :dim "#606060")
+  :light nil)
+(cl-tty.theme:define-preset :sepia
+  :dark (:user-fg "#c4a882" :user-bg "#1e1e1e" :user-border "#c4a882"
+          :agent-border "#c0a080" :agent-header "#b89870" :agent-fg "#d4c4a8"
+          :system "#808080"
+          :input-prompt "#c4a882" :input-fg "#d4c4a8" :hint "#606060"
+          :status-bg "#141414" :status-fg "#b89870"
+          :bg "#0a0a0a" :bg-panel "#141414" :bg-element "#1e1e1e"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#7aac5c" :dot-disconnected "#c84a3a"
+          :error "#c84a3a"
+          :tool-running "#c4a882" :tool-done "#7aac5c" :tool-error "#c84a3a"
+          :thinking-bg "#3a3a3a" :symbolic-border "#707070"
+          :separator "#3c3c3c" :accent "#c4a882" :dim "#606060")
+  :light nil)
+(cl-tty.theme:define-preset :nord-warm
+  :dark (:user-fg "#d4a574" :user-bg "#1e1e1e" :user-border "#d4a574"
+          :agent-border "#c0a080" :agent-header "#c49870" :agent-fg "#e0d0c0"
+          :system "#808080"
+          :input-prompt "#d08770" :input-fg "#e0d0c0" :hint "#606060"
+          :status-bg "#141414" :status-fg "#c8a080"
+          :bg "#0a0a0a" :bg-panel "#141414" :bg-element "#1e1e1e"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#7cb860" :dot-disconnected "#d06050"
+          :error "#d06050"
+          :tool-running "#d08770" :tool-done "#7cb860" :tool-error "#d06050"
+          :thinking-bg "#3a3a3a" :symbolic-border "#707070"
+          :separator "#3c3c3c" :accent "#d4a574" :dim "#606060")
+  :light nil)
+(cl-tty.theme:define-preset :monokai-warm
+  :dark (:user-fg "#e6b87d" :user-bg "#1e1e1e" :user-border "#e6b87d"
+          :agent-border "#c0a080" :agent-header "#d4a06a" :agent-fg "#d8c8b0"
+          :system "#808080"
+          :input-prompt "#e6b87d" :input-fg "#d8c8b0" :hint "#606060"
+          :status-bg "#141414" :status-fg "#cc9966"
+          :bg "#0a0a0a" :bg-panel "#141414" :bg-element "#1e1e1e"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#7ab85c" :dot-disconnected "#d94a3a"
+          :error "#d94a3a"
+          :tool-running "#e6b87d" :tool-done "#7ab85c" :tool-error "#d94a3a"
+          :thinking-bg "#3a3a3a" :symbolic-border "#707070"
+          :separator "#3c3c3c" :accent "#e6b87d" :dim "#606060")
+  :light nil)
+(cl-tty.theme:define-preset :gruvbox-warm
+  :dark (:user-fg "#d8a657" :user-bg "#1e1e1e" :user-border "#d8a657"
+          :agent-border "#c0a080" :agent-header "#c8a070" :agent-fg "#e0c8a8"
+          :system "#808080"
+          :input-prompt "#d8a657" :input-fg "#e0c8a8" :hint "#606060"
+          :status-bg "#141414" :status-fg "#c8a070"
+          :bg "#0a0a0a" :bg-panel "#141414" :bg-element "#1e1e1e"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#7ab85c" :dot-disconnected "#d94a3a"
+          :error "#d94a3a"
+          :tool-running "#d8a657" :tool-done "#7ab85c" :tool-error "#d94a3a"
+          :thinking-bg "#3a3a3a" :symbolic-border "#707070"
+          :separator "#3c3c3c" :accent "#d8a657" :dim "#606060")
+  :light nil)
+(cl-tty.theme:define-preset :light-amber
+  :dark (:user-fg "#d4a574" :user-bg "#f5f0eb" :user-border "#c4956a"
+          :agent-border "#c0a090" :agent-header "#b88050" :agent-fg "#3a3a3a"
+          :system "#606060"
+          :input-prompt "#c4956a" :input-fg "#3a3a3a" :hint "#a0a0a0"
+          :status-bg "#e8e0d8" :status-fg "#5a5a5a"
+          :bg "#f5f0eb" :bg-panel "#e8e0d8" :bg-element "#f0ebe5"
+          :bg-input "#ffffff" :text-muted "#909090"
+          :dot-connected "#6cb85c" :dot-disconnected "#c84a3a"
+          :error "#c84a3a"
+          :tool-running "#c4956a" :tool-done "#6cb85c" :tool-error "#c84a3a"
+          :thinking-bg "#e8e0d8" :symbolic-border "#a09080"
+          :separator "#d0c8c0" :accent "#b88050" :dim "#a0a0a0")
+  :light nil)
+(cl-tty.theme:define-preset :catppuccin
+  :dark (:user-fg "#fab387" :user-bg "#1e1e2e" :user-border "#fab387"
+          :agent-border "#a6adc8" :agent-header "#cba6f7" :agent-fg "#cdd6f4"
+          :system "#808080"
+          :input-prompt "#fab387" :input-fg "#cdd6f4" :hint "#6c7086"
+          :status-bg "#181825" :status-fg "#bac2de"
+          :bg "#11111b" :bg-panel "#181825" :bg-element "#1e1e2e"
+          :bg-input "#2e2e2e" :text-muted "#6c7086"
+          :dot-connected "#a6e3a1" :dot-disconnected "#f38ba8"
+          :error "#f38ba8"
+          :tool-running "#fab387" :tool-done "#a6e3a1" :tool-error "#f38ba8"
+          :thinking-bg "#363a4f" :symbolic-border "#6c7086"
+          :separator "#313244" :accent "#fab387" :dim "#585b70")
+  :light nil)
+(cl-tty.theme:define-preset :tokyonight
+  :dark (:user-fg "#ff9e64" :user-bg "#1a1b26" :user-border "#ff9e64"
+          :agent-border "#7982a8" :agent-header "#7aa2f7" :agent-fg "#a9b1d6"
+          :system "#808080"
+          :input-prompt "#ff9e64" :input-fg "#a9b1d6" :hint "#565f89"
+          :status-bg "#16161e" :status-fg "#9aa5ce"
+          :bg "#0f0f18" :bg-panel "#16161e" :bg-element "#1a1b26"
+          :bg-input "#2e2e2e" :text-muted "#565f89"
+          :dot-connected "#9ece6a" :dot-disconnected "#db4b4b"
+          :error "#db4b4b"
+          :tool-running "#ff9e64" :tool-done "#9ece6a" :tool-error "#db4b4b"
+          :thinking-bg "#363b54" :symbolic-border "#565f89"
+          :separator "#292e42" :accent "#ff9e64" :dim "#444b6a")
+  :light nil)
+(cl-tty.theme:define-preset :dracula
+  :dark (:user-fg "#ff9580" :user-bg "#1e1f2b" :user-border "#ff9580"
+          :agent-border "#c0c0e0" :agent-header "#bd93f9" :agent-fg "#f8f8f2"
+          :system "#808080"
+          :input-prompt "#ff9580" :input-fg "#f8f8f2" :hint "#6272a4"
+          :status-bg "#191a24" :status-fg "#e0e0e0"
+          :bg "#0f101a" :bg-panel "#191a24" :bg-element "#1e1f2b"
+          :bg-input "#2e2e2e" :text-muted "#6272a4"
+          :dot-connected "#50fa7b" :dot-disconnected "#ff5555"
+          :error "#ff5555"
+          :tool-running "#ff9580" :tool-done "#50fa7b" :tool-error "#ff5555"
+          :thinking-bg "#3a3b50" :symbolic-border "#6272a4"
+          :separator "#34354a" :accent "#ff9580" :dim "#5a5b7a")
+  :light nil)
+(cl-tty.theme:define-preset :gemini
+  :dark (:user-fg "#87afff" :user-bg "#1a1a1a" :user-border "#87afff"
+          :agent-border "#d0d0d0" :agent-header "#d7afff" :agent-fg "#ffffff"
+          :system "#808080"
+          :input-prompt "#87afff" :input-fg "#ffffff" :hint "#606060"
+          :status-bg "#141414" :status-fg "#afafaf"
+          :bg "#000000" :bg-panel "#141414" :bg-element "#1a1a1a"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#d7ffd7" :dot-disconnected "#ff87af"
+          :error "#ff87af"
+          :tool-running "#87afff" :tool-done "#d7ffd7" :tool-error "#ff87af"
+          :thinking-bg "#3a3a3a" :symbolic-border "#707070"
+          :separator "#3a3a3a" :accent "#87afff" :dim "#5f5f5f")
+  :light nil)
+(cl-tty.theme:define-preset :mono
+  :dark (:user-fg "#e0e0e0" :user-bg "#1a1a1a" :user-border "#808080"
+          :agent-border "#a0a0a0" :agent-header "#c0c0c0" :agent-fg "#d0d0d0"
+          :system "#808080"
+          :input-prompt "#ffffff" :input-fg "#d0d0d0" :hint "#606060"
+          :status-bg "#141414" :status-fg "#b0b0b0"
+          :bg "#0a0a0a" :bg-panel "#141414" :bg-element "#1a1a1a"
+          :bg-input "#2e2e2e" :text-muted "#808080"
+          :dot-connected "#a0a0a0" :dot-disconnected "#808080"
+          :error "#808080"
+          :tool-running "#e0e0e0" :tool-done "#a0a0a0" :tool-error "#808080"
+          :thinking-bg "#3a3a3a" :symbolic-border "#808080"
+          :separator "#303030" :accent "#ffffff" :dim "#505050")
+  :light nil)
+
+;; Load default theme at startup
+(cl-tty.theme:load-preset *theme* :amber)
+
+(defun theme-save ()
+  "Persist current theme to disk."
+  (let ((path (merge-pathnames ".cache/passepartout/theme.lisp"
+                               (user-homedir-pathname))))
+    (ensure-directories-exist path)
+    (cl-tty.theme:save-theme *theme* path)))
+
+(defun theme-load ()
+  "Load persisted theme from disk. Called at startup."
+  (let ((path (merge-pathnames ".cache/passepartout/theme.lisp"
+                               (user-homedir-pathname))))
+    (unless (cl-tty.theme:load-theme *theme* path)
+      (cl-tty.theme:load-preset *theme* :amber))))
+
+(defun theme-switch (name)
+  "Switch to a named theme preset. Returns the preset name or nil if not found."
+  (let ((key (intern (string-upcase (string name)) :keyword)))
+    (cl-tty.theme:load-preset *theme* key)
+    (theme-save)
+    (setf (st :dirty) (list t t t))
+    key))
+
+(defun theme-color (role)
+  "Returns a hex color string for a semantic role via cl-tty.theme."
+  (or (cl-tty.theme:theme-color *theme* role)
+      "#FFFFFF"))
+
+(defun st (key) (getf *state* key))
+(defun (setf st) (val key) (setf (getf *state* key) val))
+
+(defun init-state ()
+  (setf *state*
+        (list :running t :mode :chat :connected nil :stream nil
+              :input-history nil :input-hpos 0
+              :text-input (cl-tty.input:make-text-input
+                           :on-submit #'handle-submit
+                           :on-cancel #'handle-cancel
+                           :on-tab #'handle-tab
+                           :on-history #'handle-history)
+              :messages (make-array 16 :adjustable t :fill-pointer 0)
+               :scroll-offset 0 :busy nil
+              :pending-ctrl-x nil
+              :scroll-at-bottom t :scroll-notify nil
+              :streaming-text nil :url-buffer nil            ; v0.7.1
+              :collapsed-gates nil                          ; v0.7.2
+              :search-mode nil :search-query ""           ; v0.7.2
+              :search-matches nil :search-match-idx 0
+               :sidebar-mode :auto                       ; v0.8.0: :auto/:visible/:hidden
+               :sidebar-width 42                           ; v0.8.0
+               :expand-tool-calls nil                      ; v0.8.0
+               :mcp-count 0                                ; v0.8.0
+               :kill-ring nil                               ; v0.9.0
+               :dialog-stack nil                           ; v0.8.0
+               :minibuffer-active nil                      ; v0.8.0
+                :command-palette-active nil                 ; v0.8.0
+                :command-palette-dialog nil                 ; v0.8.0
+                :session-cost 0.0                          ; v0.9.0
+                :daemon-version nil                        ; filled by handshake
+                :dirty (list nil nil nil))))
+#+END_SRC
+
+** Helpers
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-state.lisp
+(defun now ()
+  (multiple-value-bind (s m h) (get-decoded-time)
+    (declare (ignore s))
+    (format nil "~2,'0d:~2,'0d" h m)))
+
+(defun add-msg (role content &key gate-trace panel)
+  (vector-push-extend (list :role role :content content :time (now) :gate-trace gate-trace :panel panel) (st :messages))
+  ;; v0.7.0: notify when scrolled up and new msg arrives
+  (unless (st :scroll-at-bottom)
+    (setf (st :scroll-notify) t))
+  (setf (st :dirty) (list t t nil)))
+#+END_SRC
+
+** Slash Commands
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-state.lisp
+(defvar *slash-commands*
+  '((:title "/eval <expr> — Evaluate Lisp"        :value "/eval")
+    (:title "/undo — Undo last operation"           :value "/undo")
+    (:title "/redo — Redo last operation"           :value "/redo")
+    (:title "/reconnect — Re-establish daemon"     :value "/reconnect")
+    (:title "/quit — Save history and exit"        :value "/quit")
+    (:title "/q — Quick quit"                       :value "/q")
+    (:title "/why — Show last gate trace"           :value "/why")
+    (:title "/tags — List tag severities"           :value "/tags")
+    (:title "/audit <id> — Inspect memory"          :value "/audit")
+    (:title "/audit verify — Memory integrity"      :value "/audit verify")
+    (:title "/rewind <n> — Rewind to snapshot"     :value "/rewind")
+    (:title "/sessions — Show memory snapshots"    :value "/sessions")
+    (:title "/resume <n> — Resume from snapshot"   :value "/resume")
+    (:title "/theme [name] — Show/switch theme"    :value "/theme")
+    (:title "/context — Show context summary"      :value "/context")
+    (:title "/search <query> — Search messages"    :value "/search")
+    (:title "/help — Show commands"                 :value "/help")
+    (:title "/help <topic> — Search manual"         :value "/help "))
+  "Slash commands for minibuffer select-dialog.")
+
+(defvar *daemon-commands*
+  '((:title "Status — Daemon health info"          :value (:action :status))
+    (:title "Stats — Daemon statistics"              :value (:action :stats))
+    (:title "Ping — Daemon reachability"             :value (:action :ping))
+    (:title "Test Provider — Check connection"      :value (:action :provider-test))
+    (:title "Discover Models — List available"       :value (:action :provider-models))
+    (:title "Memory Snapshot — Capture state"        :value (:action :memory-snapshot))
+    (:title "Memory Rebuild — Rebuild indices"       :value (:action :memory-rebuild))
+    (:title "Memory Compact — Optimize storage"      :value (:action :memory-compact))
+    (:title "Reload Config — Reload configuration"   :value (:action :reload-config))
+    (:title "Reload Identity — Reload identity file" :value (:action :reload-identity))
+    (:title "List Skills — Available skills"         :value (:action :list-skills))
+    (:title "Help — Show daemon help"                :value (:action :help)))
+  "Daemon commands for the command palette (Ctrl+P).")
+
+(defun all-commands ()
+  "Merge slash commands, daemon commands, and menu entries into one unified list."
+  (append *menu-entries* *slash-commands* *daemon-commands*))
+
+(defvar *menu-entries*
+  '((:title "/config — LLM providers, cascade, network, folders, identity"
+     :value :config-menu
+     :action passepartout.channel-tui::show-config-main-menu))
+  "Special menu entries with actions (open submenus).")
+#+END_SRC
+
+** Event Queue
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-state.lisp
+(defun queue-event (ev)
+  (bt:with-lock-held (*event-lock*) (push ev *event-queue*)))
+
+(defun drain-queue ()
+  (bt:with-lock-held (*event-lock*)
+    (let ((evs (nreverse *event-queue*)))
+      (setf *event-queue* nil) evs)))
+#+END_SRC

org/channel-tui-view.org

@@ -0,0 +1,517 @@
+#+TITLE: Passepartout TUI — View
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-view.lisp
+
+* View
+
+|Pure render functions. Each takes the cl-tty backend and current state.
+|State is read via ~(st :key)~ — no mutation here.
+
+** Contract
+
+1. (view-status fb w h): no-op. Status bar is a clean black line.
+2. (view-chat fb w h): renders scrolled chat messages. User messages
+   get amber left border (│), agent messages no border, streaming
+   agent gets grey left border. Gate traces/tool calls use ╎ prefix.
+3. (view-input fb w h): renders expanding light grey input box,
+    multi-line word-wrapped prompt, hint bar at h-2. Text and cursor
+   rendered by cl-tty.input text-input's render method.
+4. (view-sidebar fb w h): renders sidebar panels using ~sidebar-lines~.
+5. (sidebar-lines): builds a flat list of (text . color-key) pairs for
+   the sidebar: gate trace, rules, cost, files, version.
+6. (msg->pairs msg index bordered-w unbordered-w is-search): converts
+    a message to renderable ~(border border-color text text-color &optional bg)~
+    lines. Handles markdown, gate trace, tool calls, search highlight.
+7. (render-pair fb hpad y pair): draws one message line pair.
+8. (redraw fb w h): wraps view-status/chat/input in begin-sync/end-sync,
+   dispatches per dirty flags, fills global :bg first.
+9. ~cl-tty.box:char-width~ for terminal column width.
+   ASCII < 128 = 1. CJK, fullwidth, emoji = 2. Combining marks = 0.
+   Tab = 8. Used by cl-tty.box:word-wrap for accurate line counting.
+10. (sidebar-visible-p w): returns T if sidebar should show given width W
+    and current :sidebar-mode (:auto >120, :visible always, :hidden never).
+
+** Status Bar
+
+The status bar, as of v0.4.0, renders Passepartout's three differentiator
+visualizations — data only available because of the deterministic gate
+architecture:
+
+- *Rule counter* (~Rules:N~): the number of pending HITL actions from the
+  Dispatcher's ~*hitl-pending*~ hash table. The user watches this tick up
+  as they teach the agent their preferences through approve/deny decisions.
+- *Focus map* (~[Focus: <id>]~): the foveal focus from the daemon's signal
+  context. Shows the user what the agent is currently looking at.
+- *Gate trace* (not rendered in status bar — attached to individual
+  messages via ~:gate-trace~ field for future collapsible rendering per
+  message).
+
+All three enrichments cost 0 LLM tokens — they are daemon-state queries
+that the TUI actuator attaches to the response plist before transmission.
+
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-view.lisp
+(in-package :passepartout.channel-tui)
+
+(defun sidebar-visible-p (w)
+  "Compute whether sidebar should be shown given terminal width W
+and current sidebar mode (:auto/:visible/:hidden)."
+  (let ((mode (st :sidebar-mode)))
+    (or (eq mode :visible)
+        (and (eq mode :auto) (> w 120)))))
+
+(defun view-status (fb w h)
+  (declare (ignore fb w h))
+  ;; Status bar is now a clean black line — blends with global :bg.
+  ;; No clock, no dot, no text. Everything clean.
+  )
+
+(defun input-panel-top (chat-w h)
+  "Compute the top row of the input panel based on current input text."
+  (let* ((hpad 2)
+         (inner-w (- chat-w (* 2 hpad)))
+         (prompt-w (- inner-w 2))
+         (text (cl-tty.input:text-input-value (st :text-input)))
+         (lines (cl-tty.box:word-wrap text prompt-w))
+         (n-lines (max 1 (length lines)))
+         (panel-rows (max 4 (+ n-lines 2))))
+    (- h 4 panel-rows -1)))
+#+end_src
+
+;; Build simple tab-like blocks
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-view.lisp
+(in-package :passepartout.channel-tui)
+
+(defun msg->pairs (msg index bordered-w unbordered-w is-search)
+  "Convert a message to a list of (border-str border-color text-str text-color &optional bg) lines."
+  (let* ((role (getf msg :role))
+         (content (getf msg :content))
+         (cs (if is-search (cl-tty.markdown:search-highlight content (st :search-query)) content))
+         (pairs nil)
+         (think-bg (theme-color :thinking-bg))
+         (sym-bdr (theme-color :symbolic-border))
+         (agent-bdr (theme-color :agent-border))
+         (user-bdr (theme-color :user-border))
+         (user-fg (theme-color :user-fg))
+         (agent-fg (theme-color :agent-fg))
+         (system-fg (theme-color :system)))
+    (case role
+      (:user
+       (dolist (l (cl-tty.box:word-wrap cs bordered-w))
+         (push (list "│" user-bdr l user-fg) pairs)))
+      (:agent
+       (let* ((streaming (getf msg :streaming))
+              (think-rect (if streaming think-bg nil))
+              (bdr (if streaming nil agent-bdr))
+              (bstr (if streaming nil "│"))
+              (wrap-w (if streaming unbordered-w bordered-w))
+              (nodes (cl-tty.markdown:parse-blocks cs))
+              (raw-body (or (and nodes (cl-tty.markdown:render-md nodes)) (list "")))
+              (body (mapcan (lambda (l) (cl-tty.box:word-wrap l wrap-w)) raw-body)))
+         (dolist (l body)
+           (push (list bstr bdr l agent-fg think-rect) pairs))))
+      (t (dolist (l (cl-tty.box:word-wrap cs unbordered-w))
+           (push (list nil nil l system-fg) pairs))))
+    ;; Gate trace
+    (let ((gt (getf msg :gate-trace)))
+      (when (and gt (eq role :agent))
+        (if (member index (st :collapsed-gates))
+            (push (list "│" sym-bdr (format nil "Gate trace: ~a gates" (length gt)) sym-bdr) pairs)
+            (dolist (entry (passepartout::gate-trace-lines gt))
+              (let ((ec (theme-color (getf (cdr entry) :fgcolor))))
+                (dolist (l (cl-tty.box:word-wrap (car entry) bordered-w))
+                  (push (list "│" sym-bdr l ec) pairs)))))))
+    ;; Tool calls
+    (let ((tc (getf msg :tool-calls)))
+      (when tc
+        (if (member index (st :collapsed-tools))
+            (let* ((n (or (getf (first tc) :name) "tool"))
+                   (d (or (getf (first tc) :duration) 0.0)))
+              (push (list "│" (theme-color :tool-done) (format nil "~a … ~,1fs" n d) (theme-color :tool-done)) pairs))
+            (dolist (call tc)
+              (let* ((name (or (getf call :name) "tool"))
+                     (dur (or (getf call :duration) 0.0))
+                     (st (getf call :status))
+                     (out (getf call :output))
+                     (bc (theme-color
+                          (cond ((eq st :running) :tool-running)
+                                ((eq st :error) :tool-error)
+                                (t :tool-done))))
+                     (pfx (cond ((eq st :error) "✗") ((eq st :running) "●") (t "✓")))
+                     (ol (when out (cl-tty.box:word-wrap out bordered-w))))
+                (push (list "│" bc (format nil "~a ~a  ~,1fs" pfx name dur) bc) pairs)
+                (dolist (l ol)
+                  (push (list "│" bc l bc) pairs)))))))
+    (nreverse pairs)))
+
+(defun render-pair (fb hpad y pair)
+  "Draw a single (border-str border-color text-str text-color &optional bg) line."
+  (destructuring-bind (bstr bcolor tstr tcolor &optional rect-bg) pair
+    (when rect-bg
+      (cl-tty.backend:draw-rect fb 0 y 1 1 :bg rect-bg))
+    (let ((has-border (and bstr (> (length bstr) 0))))
+      (when has-border
+        (cl-tty.backend:draw-text fb hpad y bstr bcolor (theme-color :bg)))
+      (cl-tty.backend:draw-text fb (+ hpad (if has-border 2 0)) y tstr tcolor (theme-color :bg)))))
+
+(defun view-chat (fb w h)
+  (let* ((w (or (and (numberp w) (> w 0) w) 80))
+         (h (or (and (numberp h) (> h 0) h) 24))
+         (hpad 2)
+         (sidebar-w (if (sidebar-visible-p w) (or (st :sidebar-width) 42) 0))
+         (chat-w (- w sidebar-w))
+         (msgs (st :messages)) (total (length msgs))
+         (panel-top (input-panel-top chat-w h))
+         (max-lines (max 0 panel-top)) (is-search (st :search-mode))
+         (bordered-w (- chat-w (* 2 hpad) 2))
+         (unbordered-w (- chat-w (* 2 hpad)))
+         (y 0))
+    ;; Search header
+    (when is-search
+      (let* ((matches (st :search-matches)) (idx (st :search-match-idx))
+             (query (st :search-query))
+             (hdr (format nil "Search: ~d matches for '~a' (~d/~d) — Esc to exit"
+                          (length matches) query (1+ idx) (length matches))))
+        (cl-tty.backend:draw-text fb hpad y hdr (theme-color :accent) nil)
+        (incf y) (decf max-lines)))
+    ;; Build all message lines once
+    (let* ((msg-lines (map 'vector
+                           (lambda (msg i) (msg->pairs msg i bordered-w unbordered-w is-search))
+                           msgs
+                           (make-array total :initial-contents (loop for i below total collect i))))
+           (heights (map 'vector #'length msg-lines))
+           (scroll-skip (st :scroll-offset))
+           (i 0))
+      ;; Forward scan: skip messages scrolled past, then render visible ones
+      (loop while (< i total)
+            do (let ((hgt (aref heights i)))
+                 (if (> scroll-skip 0)
+                     (decf scroll-skip hgt)
+                     (let ((msg-y y))
+                       (dolist (pair (aref msg-lines i))
+                         (when (>= msg-y panel-top) (return))
+                         (render-pair fb hpad msg-y pair)
+                         (incf msg-y))
+                       (setf y (1+ msg-y))  ;; +1 spacer between messages
+                       (when (>= y panel-top) (return)))))
+            (incf i)))))
+#+END_SRC
+
+** Input Line
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-view.lisp
+(defun view-input (fb w h)
+  (let* ((w (or (and (numberp w) (> w 0) w) 80))
+         (h (or (and (numberp h) (> h 0) h) 24))
+         (hpad 2)
+         (sidebar-w (if (sidebar-visible-p w) (or (st :sidebar-width) 42) 0))
+         (chat-w (- w sidebar-w))
+         (inner-w (- chat-w (* 2 hpad)))
+         (prompt-w (- inner-w 2))
+         (input (st :text-input))
+         (n-lines (max 1 (length (cl-tty.box:word-wrap (cl-tty.input:text-input-value input) prompt-w))))
+          (panel-rows (max 4 (+ n-lines 2)))
+          (panel-top (input-panel-top chat-w h))
+         (bg-i (theme-color :bg-input))
+         (hint-fg (theme-color :hint)))
+    ;; Fill input panel
+    (cl-tty.backend:draw-rect fb hpad panel-top inner-w panel-rows :bg bg-i)
+    ;; Speaker lines for all input rows
+    (dotimes (r panel-rows)
+      (cl-tty.backend:draw-text fb hpad (+ panel-top r) "│" (theme-color :input-prompt) nil))
+    ;; Render text-input widget (word-wrap + cursor)
+    (let ((ln (cl-tty.layout:make-layout-node)))
+      (setf (cl-tty.layout:layout-node-x ln) (+ hpad 2)
+            (cl-tty.layout:layout-node-y ln) (1+ panel-top)
+            (cl-tty.layout:layout-node-width ln) prompt-w)
+      (setf (cl-tty.input:text-input-layout-node input) ln)
+      (cl-tty.box:render input fb))
+    ;; Hint bar at h-2
+    (let* ((focal (or (st :foveal-id) "-"))
+           (focal-str (format nil "F:~a" focal))
+           (mcp-str (format nil "MCP:~d" (or (st :mcp-count) 0)))
+           (left-str (format nil "~a  ~a" focal-str mcp-str))
+           (msg-count (max 1 (length (st :messages))))
+           (ctx-est (* msg-count 60))
+           (ctx-limit 8192)
+           (ctx-pct (min 100 (floor (* 100 ctx-est) ctx-limit)))
+           (ctx-tok (if (< ctx-est 1000)
+                        (format nil "~d" ctx-est)
+                        (format nil "~dK" (floor ctx-est 1000))))
+           (ctx-str (format nil "~a (~d%%)" ctx-tok ctx-pct))
+           (hint-str "ctrl+p | /help")
+           (ctx-fg (cond ((< ctx-pct 50) (theme-color :tool-done))
+                         ((< ctx-pct 80) (theme-color :input-prompt))
+                         (t (theme-color :error))))
+           (hint-x (- chat-w (length hint-str) 2))
+           (ctx-x (- hint-x 1 (length ctx-str))))
+      (cl-tty.backend:draw-text fb hpad (- h 2) left-str hint-fg (theme-color :bg))
+      (cl-tty.backend:draw-text fb ctx-x (- h 2) ctx-str ctx-fg (theme-color :bg))
+      (cl-tty.backend:draw-text fb hint-x (- h 2) hint-str hint-fg (theme-color :bg)))))
+#+end_src
+
+** Sidebar
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-view.lisp
+(defun sidebar-lines ()
+  "Collect all sidebar lines as (text . color-key) pairs."
+  (let* ((msgs (st :messages))
+         (last-gt (loop for i from (1- (length msgs)) downto 0
+                        for m = (aref msgs i)
+                        when (getf m :gate-trace)
+                        return (getf m :gate-trace)))
+         (blocked (loop for i below (length msgs)
+                        for m = (aref msgs i)
+                        sum (loop for g in (getf m :gate-trace)
+                                  count (eq (getf g :result) :blocked))))
+         (ver (or (st :daemon-version) ""))
+         (ver-label (if (> (length ver) 0) (format nil "passepartout ~a" ver) "passepartout"))
+         (dot (if (st :connected) "●" "○"))
+         (dot-color (if (st :connected) :dot-connected :dot-disconnected)))
+    (append
+     ;; Gate Trace
+     (list (cons "GATE TRACE" :accent))
+     (if last-gt
+         (mapcan (lambda (g)
+                   (let* ((name (getf g :gate))
+                          (result (getf g :result))
+                          (reason (getf g :reason))
+                          (glyph (case result (:passed "✓") (:blocked "✗") (:approval "→") (t "?")))
+                          (color (case result
+                                   (:passed :tool-done)
+                                   (:blocked :error)
+                                   (:approval :input-prompt)
+                                   (t :dim))))
+                     (if reason
+                         (list (cons (format nil "  ~a ~a" glyph name) color)
+                               (cons (format nil "    ~a" reason) :dim))
+                         (list (cons (format nil "  ~a ~a" glyph name) color)))))
+                 last-gt)
+         (list (cons "  (none)" :dim)))
+     ;; Rules
+     (list (cons "" nil))
+     (list (cons "RULES" :accent))
+     (list (cons (format nil "  ~d active" (or (st :rule-count) 0)) :agent-fg))
+     (list (cons (format nil "  ~d blocked" blocked)
+                  (if (> blocked 0) :error :dim)))
+     ;; Cost
+     (list (cons "" nil))
+     (list (cons "COST" :accent))
+     (list (cons (format nil "  $~,2f" (or (st :session-cost) 0.0)) :status-fg))
+     ;; Files
+     (list (cons "" nil))
+     (list (cons "FILES" :accent))
+     (list (cons "  (not yet)" :dim))
+     ;; spacer
+     (list (cons "" nil))
+     ;; Version footer — rendered at h-2, not in the loop
+     (list (cons (format nil "~a ~a" dot ver-label) dot-color)))))
+
+(defun view-sidebar (fb w h)
+  (let* ((w (or (and (numberp w) (> w 0) w) 80))
+         (h (or (and (numberp h) (> h 0) h) 24))
+         (x (- w (or (st :sidebar-width) 42)))
+         (lines (sidebar-lines))
+         (content-lines (butlast lines))
+         (footer-line (car (last lines))))
+    (cl-tty.backend:draw-rect fb x 0 (- w x) (1- h) :bg (theme-color :bg-panel))
+    (loop for (text . color-key) in content-lines
+          for y from 0
+          when text
+            do (cl-tty.backend:draw-text fb (+ x 2) y text
+                                          (if color-key (theme-color color-key) (theme-color :dim))
+                                          (theme-color :bg-panel)))
+    ;; Version footer at h-2
+    (when footer-line
+      (cl-tty.backend:draw-text fb (+ x 2) (- h 2) (car footer-line)
+                                (theme-color (cdr footer-line))
+                                (theme-color :bg-panel)))))
+#+END_SRC
+
+** Redraw (dirty-flag dispatch)
+#+begin_src lisp
+(defun redraw (fb w h)
+  (setq w (or (and (numberp w) (> w 0) w) 80)
+        h (or (and (numberp h) (> h 0) h) 24))
+  (when (or (first (st :dirty)) (second (st :dirty)) (third (st :dirty)))
+    (handler-case
+        (progn
+          (cl-tty.backend:with-frame (fb)
+            (cl-tty.backend:draw-rect fb 0 0 w h :bg (theme-color :bg))
+            (view-status fb w h)
+            (view-chat fb w h)
+            (view-input fb w h)
+            (when (sidebar-visible-p w)
+              (view-sidebar fb w h)))
+          (setf (st :dirty) (list nil nil nil)))
+      (error (c)
+        (add-msg :system (format nil "* Render error: ~a *" c))))))
+
+#+END_SRC
+
+* v0.7.2 — Gate Trace
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-view.lisp
+(in-package :passepartout)
+
+(defun gate-trace-lines (trace)
+  "Convert gate-trace plist to display lines."
+  (let ((lines nil))
+    (dolist (entry trace)
+      (let* ((gate (getf entry :gate))
+             (result (getf entry :result))
+             (reason (getf entry :reason))
+             (name (or gate "unknown"))
+             (color (case result
+                       (:passed :tool-done)
+                       (:blocked :error)
+                       (:approval :accent)
+                       (t :dim)))
+             (prefix (case result
+                       (:passed "  \u2713 ")
+                       (:blocked "  \u2717 ")
+                       (:approval "  \u2192 ")
+                       (t "  ? ")))
+             (text (format nil "~a~a~@[~a~]~@[~a~]"
+                           prefix name
+                           (when reason (format nil ": ~a" reason))
+                           (if (eq result :approval) " (HITL required)" ""))))
+        (push (cons text (list :fgcolor color)) lines)))
+    (nreverse lines)))
+#+END_SRC
+
+* Test Suite
+#+BEGIN_SRC lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui-view.lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-tui-view-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:tui-view-suite))
+
+(in-package :passepartout-tui-view-tests)
+
+(def-suite tui-view-suite :description "TUI view rendering helpers")
+(in-suite tui-view-suite)
+
+(test test-markdown-bold
+  "parse-inline detects **bold**."
+  (let ((nodes (cl-tty.markdown:parse-inline "hello **world**!")))
+    (is (= 3 (length nodes)))
+    (is (eq :bold (getf (second nodes) :type)))))
+
+(test test-markdown-plain
+  "parse-inline returns text node for plain input."
+  (let ((nodes (cl-tty.markdown:parse-inline "plain")))
+    (is (= 1 (length nodes)))
+    (is (eq :text (getf (first nodes) :type)))))
+
+(test test-markdown-url
+  "parse-inline returns text nodes including URLs (no built-in auto-link)."
+  (let ((nodes (cl-tty.markdown:parse-inline "see https://example.com for more")))
+    (is (>= (length nodes) 1))))
+
+(test test-markdown-blocks
+  "parse-blocks detects code blocks."
+  (let* ((text (format nil "before~%```lisp~%(+ 1 2)~%```~%after"))
+         (nodes (cl-tty.markdown:parse-blocks text)))
+    (is (= 3 (length nodes)))
+    (is (eq :code-block (getf (second nodes) :type)))
+    (is (string= "(+ 1 2)" (string-trim '(#\Space #\Newline)
+                              (getf (second nodes) :content))))))
+
+(test test-markdown-blocks-no-close
+  "parse-blocks returns code-block even when unclosed."
+  (let* ((text "```~%unclosed code")
+         (nodes (cl-tty.markdown:parse-blocks text)))
+    (is (eq :code-block (getf (first nodes) :type)))))
+
+(test test-syntax-highlight
+  "highlight-code returns segment pairs for Lisp code."
+  (let ((result (cl-tty.markdown:highlight-code "(defun foo (x) (+ x 1))" "lisp")))
+    (is (listp result))
+    (is (> (length result) 0))))
+
+(test test-syntax-highlight-keyword
+  "highlight-code classifies keywords."
+  (let ((result (cl-tty.markdown:highlight-code "(let ((x 1)) (+ x 2))" "lisp")))
+    (is (find :keyword result :key #'cdr))))
+
+(test test-syntax-highlight-function
+  "highlight-code classifies function calls."
+  (let ((result (cl-tty.markdown:highlight-code "(+ 1 2)" "lisp")))
+    (is (listp result))
+    (is (> (length result) 0))))
+
+(test test-gate-trace-lines-passed
+  "Contract 9: gate-trace-lines for passed gate."
+  (let ((lines (passepartout::gate-trace-lines
+                '((:gate "path" :result :passed)))))
+    (is (= 1 (length lines)))
+    (is (eq :tool-done (getf (cdar lines) :fgcolor)))))
+
+(test test-gate-trace-lines-blocked
+  "Contract 9: gate-trace-lines for blocked gate."
+  (let ((lines (passepartout::gate-trace-lines
+                '((:gate "shell" :result :blocked :reason "rm")))))
+    (is (= 1 (length lines)))
+    (is (search "rm" (caar lines)))))
+
+(test test-gate-trace-lines-approval
+  "Contract 9: gate-trace-lines for approval gate."
+  (let ((lines (passepartout::gate-trace-lines
+                '((:gate "network" :result :approval)))))
+    (is (= 1 (length lines)))
+    (is (search "HITL" (caar lines)))))
+
+(test test-init-state-has-collapsed-gates
+  "Contract v0.7.2: init-state includes :collapsed-gates field."
+  (passepartout.channel-tui::init-state)
+  (let ((cg (passepartout.channel-tui::st :collapsed-gates)))
+    (is (null cg))))
+
+(test test-sidebar-state
+  "Contract v0.8.0: init-state includes :sidebar-mode (:auto) and :sidebar-width (42)."
+  (passepartout.channel-tui::init-state)
+  (is (eq :auto (passepartout.channel-tui::st :sidebar-mode)))
+  (is (= 42 (passepartout.channel-tui::st :sidebar-width))))
+
+(defun sidebar-visible-p (w)
+  "Compute whether sidebar should be shown given terminal width W
+and current sidebar mode."
+  (let ((mode (passepartout.channel-tui::st :sidebar-mode)))
+    (or (eq mode :visible)
+        (and (eq mode :auto) (> w 120)))))
+
+(test test-sidebar-auto-wide
+  "Contract v0.8.0: sidebar auto-shows when terminal > 120 cols."
+  (passepartout.channel-tui::init-state)
+  (setf (passepartout.channel-tui::st :sidebar-mode) :auto)
+  (is (sidebar-visible-p 140))
+  (is (not (sidebar-visible-p 100))))
+
+(test test-sidebar-visible-mode
+  "Contract v0.8.0: :visible mode shows sidebar regardless of width."
+  (passepartout.channel-tui::init-state)
+  (setf (passepartout.channel-tui::st :sidebar-mode) :visible)
+  (is (sidebar-visible-p 40))
+  (is (sidebar-visible-p 140)))
+
+(test test-sidebar-hidden-mode
+  "Contract v0.8.0: :hidden mode hides sidebar regardless of width."
+  (passepartout.channel-tui::init-state)
+  (setf (passepartout.channel-tui::st :sidebar-mode) :hidden)
+  (is (not (sidebar-visible-p 140)))
+  (is (not (sidebar-visible-p 40))))
+
+(test test-status-bar-tokens
+  "v0.9.0: status bar uses :status-fg and :status-bg theme tokens."
+  (is (stringp (passepartout.channel-tui:theme-color :status-fg)))
+  (is (stringp (passepartout.channel-tui:theme-color :status-bg))))
+
+(test test-new-theme-keys
+  "v0.10.0: theme has all zone keys."
+  (is (stringp (passepartout.channel-tui:theme-color :bg)))
+  (is (stringp (passepartout.channel-tui:theme-color :bg-panel)))
+  (is (stringp (passepartout.channel-tui:theme-color :bg-element)))
+  (is (stringp (passepartout.channel-tui:theme-color :bg-input)))
+  (is (stringp (passepartout.channel-tui:theme-color :agent-border)))
+  (is (stringp (passepartout.channel-tui:theme-color :thinking-bg)))
+  (is (stringp (passepartout.channel-tui:theme-color :symbolic-border)))
+  (is (stringp (passepartout.channel-tui:theme-color :text-muted))))
+#+END_SRC

org/channel-tui.org

@@ -0,0 +1,173 @@
+#+TITLE: Passepartout TUI
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui.lisp
+
+* TUI
+
+Direct-rendering TUI using cl-tty backend + framebuffer. Layout by
+~compute-layout~. Three zones: status (3 lines), chat, input.
+
+#+begin_src lisp :tangle /home/user/.local/share/passepartout/lisp/channel-tui.lisp
+(in-package :cl-user)
+
+(ql:quickload :cl-tty :silent t)
+(ql:quickload :passepartout :silent t)
+(ql:quickload :usocket :silent t)
+(ql:quickload :bordeaux-threads :silent t)
+
+(defpackage :passepartout.tui
+  (:use :cl :cl-tty.backend :cl-tty.input :cl-tty.rendering :cl-tty.layout)
+  (:export #:tui-main))
+(in-package :passepartout.tui)
+
+(defvar *messages* (make-array 0 :fill-pointer 0 :adjustable t))
+(defvar *daemon-stream* nil)
+(defvar *event-queue* nil)
+(defvar *event-lock* (bt:make-lock "tui-event"))
+(defvar *streaming-text* nil)
+(defvar *input-buf* nil)
+(defvar *cursor-pos* 0)
+(defvar *connected* nil)
+(defvar *running* t)
+
+;; Input
+(defun input-insert-char (ch)
+  (let ((pos *cursor-pos*))
+    (setf *input-buf* (concatenate 'list (subseq *input-buf* 0 pos) (list ch)
+                                   (subseq *input-buf* pos)))
+    (incf *cursor-pos*)))
+
+(defun input-delete-char ()
+  (when (and *input-buf* (> *cursor-pos* 0))
+    (setf *input-buf* (nconc (subseq *input-buf* 0 (1- *cursor-pos*))
+                              (subseq *input-buf* *cursor-pos*)))
+    (decf *cursor-pos*)))
+
+(defun input-string () (coerce (reverse *input-buf*) 'string))
+
+(defun input-submit ()
+  (let ((text (string-trim '(#\Space) (input-string))))
+    (when (> (length text) 0)
+      (vector-push-extend (list :role :user :content text) *messages*)
+      (send-daemon `(:type :event :payload (:sensor :user-input :text ,text)))
+      (setf *input-buf* nil *cursor-pos* 0))))
+
+;; Daemon
+(defun send-daemon (msg)
+  (let ((s *daemon-stream*))
+    (when (and s (open-stream-p s))
+      (handler-case
+          (let ((str (prin1-to-string msg)))
+            (format s "~6,'0X~A" (length str) str)
+            (finish-output s))
+        (error () nil)))))
+
+(defun connect-daemon (&optional (host "127.0.0.1") (port 9105))
+  (handler-case
+      (let ((s (usocket:socket-connect host port :timeout 5)))
+        (setf *daemon-stream* (usocket:socket-stream s) *connected* t)
+        (bt:make-thread (lambda () (reader-loop)) :name "tui-reader")
+        (vector-push-extend '(:role :system :content "* Connected *") *messages*))
+    (error (c)
+      (vector-push-extend (list :role :system :content
+                                (format nil "* Connection failed: ~A *" c))
+                          *messages*))))
+
+(defun reader-loop ()
+  (loop while *running*
+        for msg = (handler-case
+                      (let* ((hdr (make-string 6)) (n 0))
+                        (loop while (< n 6)
+                              do (let ((ch (read-char *daemon-stream* nil)))
+                                   (unless ch (return-from reader-loop nil))
+                                   (setf (char hdr n) ch) (incf n)))
+                        (let* ((len (parse-integer hdr :radix 16 :junk-allowed t))
+                               (buf (make-string (or len 0))))
+                          (when (and len (> len 0))
+                            (loop for i from 0 below len
+                                  do (let ((ch (read-char *daemon-stream* nil)))
+                                       (unless ch (return-from reader-loop nil))
+                                       (setf (char buf i) ch)))
+                            (let ((*read-eval* nil)) (read-from-string buf)))))
+                    (error () nil))
+        if msg do (bt:with-lock-held (*event-lock*) (push msg *event-queue*))
+        else do (sleep 0.5)))
+
+;; Render
+(defun render-frame (fb w h)
+  (backend-clear fb)
+  (let ((fg (if *connected* "#00FF00" "#FF4444")))
+    (draw-text fb 1 1
+      (format nil " Passepartout  ~a  [CHAT]  msgs:~d"
+              (if *connected* "● Connected" "○ Disconnected")
+              (length *messages*))
+      fg nil)
+    (draw-text fb 1 2 " Ctrl+P: palette  Ctrl+Q: quit  /help: help" "#888888" nil))
+  (let ((y 4))
+    (loop for i from (1- (length *messages*)) downto 0
+          for msg = (aref *messages* i)
+          do (let* ((role (getf msg :role))
+                    (content (getf msg :content))
+                    (fg (case role (:user "#00FF00") (:agent "#FFFFFF")
+                                 (:system "#FFFF00") (t "#888888")))
+                    (pfx (case role (:user "> ") (:agent "  ") (:system "* ") (t "  ")))))
+               (draw-text fb 1 y (concatenate 'string pfx content) fg nil)
+               (incf y))
+          (when (> y (- h 3)) (loop-finish))))
+  (draw-text fb 1 (- h 1) (concatenate 'string "> " (input-string)) "#FFFFFF" "#0F3460"))
+
+;; Event loop
+(defun tui-main ()
+  (setf *running* t *messages* (make-array 0 :fill-pointer 0 :adjustable t))
+  (connect-daemon)
+  (with-raw-terminal
+    (with-terminal (be w h)
+      (let ((prev-fb (make-framebuffer w h))
+            (curr-fb (make-framebuffer w h)))
+        (loop while *running* do
+          (bt:with-lock-held (*event-lock*)
+            (dolist (msg (nreverse *event-queue*))
+              (let* ((payload (getf msg :payload)) (text (getf payload :text))
+                     (type (getf msg :type)))
+                (cond
+                  ((and (eq type :stream-chunk) text (not (string= text "")))
+                   (if *streaming-text*
+                       (setf *streaming-text* (concatenate 'string *streaming-text* text))
+                       (setf *streaming-text* text
+                             *messages* (let ((v (make-array (1+ (length *messages*))
+                                               :fill-pointer (1+ (length *messages*))
+                                               :adjustable t)))
+                                         (loop for i below (length *messages*)
+                                               do (setf (aref v i) (aref *messages* i)))
+                                         (setf (aref v (length *messages*))
+                                               (list :role :thinking :content text))
+                                         v))))
+                  ((and (eq type :stream-chunk) (string= text ""))
+                   (setf *streaming-text* nil))
+                  (text
+                   (vector-push-extend (list :role :agent :content text) *messages*)))))
+            (setf *event-queue* nil))
+          (multiple-value-bind (type data) (read-event be :timeout 0)
+            (declare (ignore type))
+            (when (key-event-p data)
+              (let ((k (key-event-key data)))
+                (cond
+                  ((eq k :escape) (when *streaming-text* (setf *streaming-text* nil)))
+                  ((eq k :enter) (input-submit))
+                  ((eq k :backspace) (input-delete-char))
+                  ((eq k :left) (when (> *cursor-pos* 0) (decf *cursor-pos*)))
+                  ((eq k :right) (when (< *cursor-pos* (length *input-buf*))
+                                   (incf *cursor-pos*)))
+                  ((eq k :ctrl-u) (setf *input-buf* nil *cursor-pos* 0))
+                  ((eq k :ctrl-a) (setf *cursor-pos* 0))
+                  ((eq k :ctrl-e) (setf *cursor-pos* (length *input-buf*)))
+                  ((eq k :ctrl-d) (when (null *input-buf*) (setf *running* nil)))
+                  ((eq k :ctrl-q) (setf *running* nil))
+                  (t (let ((chr (when (keywordp k)
+                                   (let ((s (string k)))
+                                     (when (= (length s) 1) (char-downcase (char s 0)))))))
+                       (when chr (input-insert-char chr))))))))
+          (render-frame curr-fb w h)
+          (flush-framebuffer prev-fb curr-fb be)
+          (rotatef prev-fb curr-fb)
+          (sleep 0.05))))))
+#+end_src

org/core-act.org

@@ -0,0 +1,528 @@
+#+TITLE: Stage 3: Act (act.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:act:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/lisp/core-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 Dispatcher, 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 ~cognitive-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.
+
+** Contract
+
+1. (loop-gate-act signal): the final pipeline stage. Handles HITL
+   ~:approval-required~ (suspends action), runs last-mile
+   ~cognitive-verify~ on approved actions, dispatches via
+   ~action-dispatch~, sets ~:status :acted~, returns feedback.
+2. (act-gate signal): thin alias for ~loop-gate-act~.
+3. (action-dispatch approved signal): routes approved actions to
+    registered actuators by ~:target~ keyword.
+ 4. (tui-enrich-response action context): enriches the outgoing action
+    plist with sidebar fields — ~:block-counts~, ~:context-usage~,
+    ~:modified-files~, ~:session-cost~ (v0.8.0) — plus existing
+    ~:rule-count~ and ~:foveal-id~ (v0.4.0). Each field is
+    ~fboundp~-guarded; missing skills produce nil. Called from the
+    ~:tui~ actuator lambda.
+
+* 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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defvar *actuator-default* :cli
+  "The actuator used when no explicit target is specified.")
+
+#+end_src
+** *actuator-silent*
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defvar *actuator-silent* '(:cli :system-message :emacs)
+  "List of actuators that don't generate tool-output feedback.")
+
+#+end_src
+** actuator-initialize
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(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))
+                                 ;; Enrich response with differentiator visualization data
+                              (setf (getf (getf action :payload) :rule-count)
+                                    (if (boundp '*hitl-pending*)
+                                        (hash-table-count *hitl-pending*)
+                                        0))
+                                 (setf (getf (getf action :payload) :foveal-id)
+                                       (getf context :foveal-id))
+                                 ;; v0.8.0: sidebar enrichment via fboundp guards
+                                 (when (fboundp 'dispatcher-block-counts-summary)
+                                   (setf (getf (getf action :payload) :block-counts)
+                                         (dispatcher-block-counts-summary)))
+                                 (when (fboundp 'context-usage-percentage)
+                                   (setf (getf (getf action :payload) :context-usage)
+                                         (context-usage-percentage)))
+                                 (when (fboundp 'tool-modified-files-summary)
+                                   (setf (getf (getf action :payload) :modified-files)
+                                         (tool-modified-files-summary)))
+                                 (when (fboundp 'cost-session-summary)
+                                   (setf (getf (getf action :payload) :session-cost)
+                                         (cost-session-summary)))
+                                 (format stream "~a" (frame-message action))
+                                 (finish-output stream))))))
+#+end_src
+
+** TUI Differentiator Enrichment (v0.4.0, extended v0.8.0)
+
+The TUI actuator is the last point in the pipeline before the response leaves the daemon. It enriches the action plist with fields that power the TUI's differentiator visualizations:
+
+- ~:rule-count~ = ~(hash-table-count *hitl-pending*)~ — the number of pending HITL actions. The user watches this counter tick as they teach the agent their preferences. (v0.4.0)
+- ~:foveal-id~ = the current foveal focus from the signal context — enables the TUI's focus map status line. (v0.4.0)
+- ~:gate-trace~ — already attached by ~cognitive-verify~, flows through the action plist unchanged. (v0.4.0)
+
+v0.8.0 adds four sidebar fields via ~fboundp~ guards — same pattern as
+~core-reason.lisp~'s calls into token-economics, awareness, and time skills.
+Each field degrades gracefully to nil when its source skill is not loaded:
+
+- ~:block-counts~ = ~(dispatcher-block-counts-summary)~ — per-gate block tallies from ~security-dispatcher~. Powers the sidebar's Protection panel.
+- ~:context-usage~ = ~(context-usage-percentage)~ — token budget percentage from ~token-economics~. Powers the sidebar's Context gauge.
+- ~:modified-files~ = ~(tool-modified-files-summary)~ — files modified this turn from ~programming-tools~. Powers the sidebar's Files panel.
+- ~:session-cost~ = ~(cost-session-summary)~ — cumulative cost data from ~cost-tracker~. Powers the sidebar's Cost panel.
+
+The enrichment is added inside the existing ~:tui~ actuator lambda (one block
+after the ~:rule-count~ and ~:foveal-id~ enrichment). No new actuator is
+registered; no new ASDF component is added. The contract is: each field
+arrives via ~fboundp~ guard and is silently nil when unavailable.
+
+** 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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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))
+             ;; If target is :SYSTEM and we have a live reply-stream, route to :TUI instead
+             (actual-target (if (and (eq target :system)
+                                     (getf meta :reply-stream)
+                                     (ignore-errors (open-stream-p (getf meta :reply-stream))))
+                               :tui
+                               target))
+             (actuator-fn (gethash actual-target *actuator-registry*)))
+        (when (and meta (null (getf action :meta)))
+          (setf (getf action :meta) meta))
+        (if actuator-fn
+            (funcall actuator-fn action context)
+            (log-message "ACT ERROR: No actuator registered for '~s'" actual-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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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 (let ((*read-eval* nil)) (read-from-string (getf payload :code)))))
+      (:message
+       (log-message "ACT [System]: ~a" (getf payload :text)))
+      (t
+       (log-message "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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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-tool-registry*)))
+    ;; v0.7.2: snapshot before destructive tool execution
+    (when (and tool (not (cognitive-tool-read-only-p tool)))
+      (undo-snapshot))
+    (if tool
+        (handler-case
+            (let* ((clean-args (if (and (listp tool-args) (listp (car tool-args))) (car tool-args) tool-args))
+                   (is-read-only (cognitive-tool-read-only-p tool))
+                   (cache-key (when is-read-only (tool-cache-key tool-name clean-args)))
+                   (cached (when cache-key (gethash cache-key *tool-cache*)))
+                   (raw-result (if cached
+                                   (progn (log-message "TOOL-CACHE: hit for ~a" tool-name) cached)
+                                   (let* ((res (call-with-tool-timeout tool-name
+                                                (lambda () (funcall (cognitive-tool-body tool) clean-args)))))
+                                     (when (and is-read-only cache-key)
+                                       (setf (gethash cache-key *tool-cache*) res))
+                                     res))))
+              ;; Timeout: propagate error
+              (when (and (listp raw-result) (eq (getf raw-result :status) :error))
+                (return-from action-tool-execute
+                  (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
+                        :PAYLOAD (list :SENSOR :tool-error :TOOL tool-name
+                                      :MESSAGE (getf raw-result :message)))))
+              (when source
+                (action-dispatch (list :TYPE :REQUEST :TARGET source 
+                                       :PAYLOAD (list :ACTION :MESSAGE :TEXT (tool-result-format tool-name raw-result)))
+                                context))
+              (list :TYPE :EVENT :DEPTH (1+ depth) :META meta
+                    :PAYLOAD (list :SENSOR :tool-output :RESULT raw-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
+
+** v0.7.2 — Tool Execution Hardening
+#+begin_src lisp
+(defvar *tool-timeouts* (make-hash-table :test 'equal)
+  "Per-tool timeout in seconds. Default 120s.")
+
+;; Defaults: shell=300s, search-files=30s, eval-form=10s
+(setf (gethash "shell" *tool-timeouts*) 300)
+(setf (gethash "search-files" *tool-timeouts*) 30)
+(setf (gethash "eval-form" *tool-timeouts*) 10)
+
+(defun tool-timeout (tool-name)
+  "Return timeout for tool-name, default 120 seconds."
+  (gethash (string-downcase (string tool-name)) *tool-timeouts* 120))
+
+(defun call-with-tool-timeout (tool-name fn)
+  "Execute FN within the timeout for TOOL-NAME.
+On timeout, returns (:status :error :message ...)."
+  (let ((timeout (tool-timeout tool-name)))
+    (handler-case
+        (sb-ext:with-timeout timeout
+          (funcall fn))
+      (sb-ext:timeout (c)
+        (declare (ignore c))
+        (list :status :error :message
+              (format nil "Timed out after ~a second~:p" timeout))))))
+
+(defun verify-write (filepath expected-content)
+  "Verify that FILEPATH contains EXPECTED-CONTENT after write.
+Returns T on match, logs and returns NIL on mismatch or read error."
+  (handler-case
+      (let ((actual (uiop:read-file-string filepath)))
+        (if (string= expected-content actual)
+            t
+            (progn
+              (log-message "WRITE-VERIFY: Mismatch in ~a" filepath)
+              nil)))
+    (error (c)
+      (log-message "WRITE-VERIFY: Cannot read ~a: ~a" filepath c)
+      nil)))
+
+;; v0.7.2: read-only tool response cache
+(defvar *tool-cache* (make-hash-table :test 'equal)
+  "Cache for read-only tool results. Key: tool-name$sxhash-args. Cleared per session.")
+
+(defun tool-cache-key (tool-name args)
+  "Build a cache key from TOOL-NAME and ARGS."
+  (format nil "~a$~a" (string-downcase (string tool-name)) (sxhash args)))
+
+(defun tool-cache-clear ()
+  "Clear the read-only tool response cache."
+  (clrhash *tool-cache*))
+#+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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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.
+
+*** loop-gate-act
+
+The main act pipeline stage.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defun loop-gate-act (signal)
+  "Final stage of the metabolic pipeline: Actuation.
+For approval-required actions, creates a Flight Plan instead of executing."
+  (let* ((approved (getf signal :approved-action))
+         (signal-status (getf signal :status))
+         (type (getf signal :type))
+         (meta (getf signal :meta))
+         (source (getf meta :source))
+         (feedback nil))
+    ;; HITL: if the approved action requires human approval,
+    ;; create a Flight Plan (Emacs) and HITL entry (all gateways).
+    (when (and approved
+               (eq (getf approved :level) :approval-required))
+      (let* ((payload (getf approved :payload))
+             (blocked-action (getf payload :action))
+             (hitl (hitl-create blocked-action)))
+        (log-message "ACT: Action requires approval — creating Flight Plan + HITL (~a)" (getf hitl :token))
+        (dispatcher-flight-plan-create blocked-action)
+        (setf (getf signal :status) :suspended)
+        (action-dispatch (list :target source
+                               :payload (list :text (getf hitl :message)))
+                         signal)
+        (setf approved nil)
+        (setf feedback nil)))
+    (when approved
+      (let* ((original-type (getf approved :type))
+             (verified (cognitive-verify approved signal)))
+        (if (and (listp verified) (member (getf verified :type) '(:LOG :EVENT))
+                 (not (eq (getf verified :level) :approval-required))
+                 (not (member original-type '(:LOG :EVENT))))
+            (progn
+              (log-message "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
+
+*** act-gate (backward-compatibility alias)
+
+The pipeline gate was originally named ~act-gate~. Code that still
+uses the old name can call this alias. New code should call
+~loop-gate-act~.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defun act-gate (signal)
+  (loop-gate-act signal))
+#+end_src
+
+* Test Suite
+Verifies that the act gate correctly processes an approved action and sets the signal status to ~:acted~.
+#+begin_src 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
+  "Contract 1: approved action reaches :acted status via loop-gate-act."
+  (clrhash passepartout::*skill-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))))
+
+(test test-loop-gate-act-no-approved-action
+  "Contract 1: signal with no approved-action still reaches :acted status."
+  (clrhash passepartout::*skill-registry*)
+  (let* ((signal (list :type :EVENT :status nil :depth 0)))
+    (loop-gate-act signal)
+    (is (eq :acted (getf signal :status)))))
+
+(test test-loop-gate-act-last-mile-reject
+  "Contract 1: last-mile cognitive-verify rejection blocks approved-action."
+  (clrhash passepartout::*skill-registry*)
+  (passepartout::defskill :mock-blocker
+    :priority 50
+    :trigger (lambda (ctx) (declare (ignore ctx)) t)
+    :deterministic (lambda (action ctx)
+                    (declare (ignore ctx action))
+                    (list :type :LOG :payload (list :text "Last-mile block"))))
+  (let* ((signal (list :type :EVENT :status nil :depth 0
+                        :approved-action '(:type :REQUEST :target :cli :payload (:text "blocked")))))
+    (loop-gate-act signal)
+    (is (eq :acted (getf signal :status)))
+    (is (null (getf signal :approved-action)))))
+
+(test test-loop-gate-act-preserves-meta
+  "Contract 1: signal metadata is not mutated by loop-gate-act."
+  (clrhash passepartout::*skill-registry*)
+  (let* ((meta '(:source :tui :session "s1"))
+         (signal (list :type :EVENT :status nil :depth 0 :meta meta
+                        :approved-action '(:target :cli :payload (:text "test")))))
+    (loop-gate-act signal)
+    (is (equal meta (getf signal :meta)))))
+
+(test test-action-dispatch-routes
+  "Contract 3: action-dispatch routes to registered actuators without crashing."
+  (actuator-initialize)
+  (let ((result (action-dispatch '(:type :REQUEST :target :system :payload (:action :eval :code "(+ 1 2)"))
+                                  '(:type :EVENT :depth 0))))
+    (is (numberp result) "eval should return a number")))
+
+(test test-tool-timeout-shell
+  "Contract v0.7.2: shell timeout is 300 seconds."
+  (is (= 300 (passepartout::tool-timeout "shell"))))
+
+(test test-tool-timeout-unknown
+  "Contract v0.7.2: unknown tool gets default 120s."
+  (is (= 120 (passepartout::tool-timeout "nonexistent-tool"))))
+
+(test test-verify-write-match
+  "Contract v0.7.2: verify-write returns T on match."
+  (let ((path "/tmp/passepartout-verify-test.org")
+        (content "test content"))
+    (with-open-file (f path :direction :output :if-exists :supersede)
+      (write-string content f))
+    (unwind-protect
+         (is (passepartout::verify-write path content))
+      (ignore-errors (delete-file path)))))
+
+(test test-tool-timeout-enforcement
+  "Contract v0.7.2: tool exceeding timeout returns :error with timeout message."
+  (setf (gethash "sleep-forever" passepartout::*tool-timeouts*) 1)
+  (setf (gethash "sleep-forever" passepartout::*cognitive-tool-registry*)
+        (passepartout::make-cognitive-tool :name "sleep-forever"
+                                          :read-only-p nil
+                                          :body (lambda (args)
+                                                  (declare (ignore args))
+                                                  (sleep 10)
+                                                  "done")))
+  (unwind-protect
+       (let* ((action '(:type :REQUEST :payload (:tool "sleep-forever" :args nil)))
+              (ctx '(:depth 0))
+              (result (passepartout::action-tool-execute action ctx)))
+         (is (eq :EVENT (getf result :TYPE)))
+         (let ((payload (getf result :PAYLOAD)))
+           (is (eq :tool-error (getf payload :SENSOR)))
+           (is (search "timed out" (string-downcase (getf payload :MESSAGE))))))
+    (remhash "sleep-forever" passepartout::*cognitive-tool-registry*)
+    (remhash "sleep-forever" passepartout::*tool-timeouts*)))
+
+(test test-tool-cache-read-only
+  "Contract v0.7.2: read-only tool results are cached and reused."
+  (let ((call-count 0))
+    (setf (gethash "cache-test" passepartout::*cognitive-tool-registry*)
+          (passepartout::make-cognitive-tool :name "cache-test"
+                                            :read-only-p t
+                                            :body (lambda (args)
+                                                    (declare (ignore args))
+                                                    (incf call-count)
+                                                    (list :status :success :content (format nil "call ~d" call-count)))))
+    (unwind-protect
+         (progn
+           (clrhash passepartout::*tool-cache*)
+           (let* ((action '(:type :REQUEST :payload (:tool "cache-test" :args nil)))
+                  (ctx '(:depth 0))
+                  (r1 (passepartout::action-tool-execute action ctx))
+                  (r2 (passepartout::action-tool-execute action ctx)))
+             (is (= 1 call-count) "Second call should hit cache, not re-execute")
+             (let ((p1 (getf r1 :PAYLOAD))
+                   (p2 (getf r2 :PAYLOAD)))
+               (is (string= (getf (getf p1 :RESULT) :CONTENT)
+                            (getf (getf p2 :RESULT) :CONTENT))))))
+      (remhash "cache-test" passepartout::*cognitive-tool-registry*)
+      (clrhash passepartout::*tool-cache*))))
+#+end_src

org/core-manifest.org

@@ -0,0 +1,55 @@
+#+TITLE: System Manifest (manifest.org)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:manifest:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/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.4.3"
+  :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-package")
+               (:file "lisp/core-skills")
+               (:file "lisp/core-transport")
+               (:file "lisp/core-memory")
+               (:file "lisp/core-perceive")
+               (:file "lisp/core-reason")
+               (:file "lisp/core-act")
+               (:file "lisp/core-pipeline")))
+#+end_src
+
+** Test System
+
+Tests are embedded directly in each module's source file — see the `* Test Suite` section at the end of each `.org` file. No separate test system is needed.
+
+** TUI System
+
+The TUI is a standalone system that depends on cl-tty (pure CL terminal UI) in addition to the core system. It's loaded separately because it requires a terminal and is not needed for daemon-mode operation.
+
+#+begin_src lisp
+(defsystem :passepartout/tui
+  :depends-on (:passepartout :cl-tty :usocket :bordeaux-threads)
+  :serial t
+  :components ((:file "lisp/channel-tui-state")
+               (:file "lisp/channel-tui-view")
+               (:file "lisp/channel-tui-main")))
+#+end_src

org/core-memory.org

@@ -0,0 +1,568 @@
+#+TITLE: The System Memory (memory.lisp)
+#+AUTHOR: Agent
+#+FILETAGS: :harness:memory:
+#+STARTUP: content
+#+PROPERTY: header-args:lisp :tangle /home/user/.local/share/passepartout/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).
+
+** Contract
+
+1. (ingest-ast ast &key scope): stores AST nodes in ~*memory-store*~.
+   Detaches children, gives each an ID, computes Merkle hash, and
+   populates the ~:vector~ slot via ~embeddings-compute~. Returns the
+   root ID string.
+2. (memory-object-hash object): returns the SHA-256 Merkle hash of the
+   object's content. Hash is deterministic — same content → same hash.
+3. (memory-object-get id): retrieves a stored object by ID, or nil.
+4. (snapshot-memory): deep-copies ~*memory-store*~ to ~*memory-snapshots*~.
+5. (rollback-memory snap-index): restores ~*memory-store*~ from a snapshot.
+
+* 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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defvar *memory-store* (make-hash-table :test 'equal))
+#+end_src
+** *memory-history*
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defvar *memory-history* (make-hash-table :test 'equal)
+  "Immutable Merkle-Tree versioning store mapping hashes to objects.")
+#+end_src
+#+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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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 Dispatcher 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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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).
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defun memory-id-generate ()
+  "Generates a UUIDv4 unique ID. Compatible with Agora Note UUIDs."
+  (concatenate 'string "id-" (string-downcase (format nil "~a" (uuid:make-v4-uuid)))))
+#+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
+- ~scope~ — scope keyword (:memex/:session/:project) for context-aware retrieval
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defstruct memory-object
+  id type attributes content vector parent-id children version last-sync hash scope)
+#+end_src
+
+** Serialization Support
+
+Required by the Lisp runtime for saving/loading objects across image restarts via ~make-load-form-saving-slots~.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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)
+                  :scope (memory-object-scope 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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defun ingest-ast (ast &key parent-id (scope :memex))
+  (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 :parent-id id :scope scope)))
+          (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 :scope scope))))
+      (unless existing-obj (setf (gethash hash *memory-history*) obj))
+      (setf (gethash id *memory-store*) obj)
+      ;; Populate embedding vector for new objects
+      (when (and raw-content (not existing-obj) (not (memory-object-vector obj)))
+        (handler-case
+            (setf (memory-object-vector obj)
+                  (embeddings-compute raw-content))
+          (error (c)
+            (log-message "INGEST: Embedding deferred: ~a" c))))
+      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).
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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)))
+    (log-message "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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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)))
+               (log-message "MEMORY - Memory rolled back to snapshot ~a" index))
+        (log-message "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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(defvar *memory-snapshot-path* nil)
+
+#+end_src
+** memory-snapshot-path-ensure
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+begin_src lisp
+(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
+#+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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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)))
+    (log-message "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.
+
+;; REPL-VERIFIED: 2026-05-03T13:00:00
+#+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 (let ((*read-eval* nil)) (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)))
+                  (log-message "MEMORY - Loaded from ~a (~a objects)" path (hash-table-size *memory-store*))))))
+          (error (c) (log-message "MEMORY WARNING - Failed to load snapshot: ~a" c)))))
+  t)
+
+;; v0.7.2 — Undo/Redo
+(defvar *undo-stack* nil
+  "Ring buffer of pre-operation memory snapshots. Newest first, max 20.")
+(defvar *redo-stack* nil
+  "Stack of snapshots saved during undo for redo. Max 20.")
+
+(defun undo-snapshot ()
+  "Save current memory state to the undo stack."
+  (let ((snap (list :timestamp (get-universal-time)
+                    :data (memory-hash-table-copy *memory-store*))))
+    (push snap *undo-stack*)
+    (when (> (length *undo-stack*) 20)
+      (setf *undo-stack* (subseq *undo-stack* 0 20)))))
+
+(defun undo (&optional source)
+  "Restore memory to the most recent undo snapshot. Returns T on success, NIL if stack empty."
+  (declare (ignore source))
+  (if *undo-stack*
+      (let ((snap (pop *undo-stack*)))
+        (push (list :timestamp (get-universal-time)
+                    :data (memory-hash-table-copy *memory-store*))
+              *redo-stack*)
+        (when (> (length *redo-stack*) 20)
+          (setf *redo-stack* (subseq *redo-stack* 0 20)))
+        (setf *memory-store* (memory-hash-table-copy (getf snap :data)))
+        (log-message "UNDO: Memory restored to snapshot ~a" (getf snap :timestamp))
+        t)
+      (progn (log-message "UNDO: No snapshots to undo") nil)))
+
+(defun redo (&optional source)
+  "Restore memory to the most recent redo snapshot. Returns T on success, NIL if stack empty."
+  (declare (ignore source))
+  (if *redo-stack*
+      (let ((snap (pop *redo-stack*)))
+        (push (list :timestamp (get-universal-time)
+                    :data (memory-hash-table-copy *memory-store*))
+              *undo-stack*)
+        (when (> (length *undo-stack*) 20)
+          (setf *undo-stack* (subseq *undo-stack* 0 20)))
+        (setf *memory-store* (memory-hash-table-copy (getf snap :data)))
+        (log-message "REDO: Memory restored to snapshot ~a" (getf snap :timestamp))
+        t)
+      (progn (log-message "REDO: No snapshots to redo") nil)))
+#+end_src
+
+** Merkle Audit
+#+begin_src lisp
+(defun audit-node (node-id)
+  "Return audit info for a memory object by ID."
+  (let ((obj (memory-object-get node-id)))
+    (when obj
+      (list :id node-id :type (memory-object-type obj)
+            :version (memory-object-version obj)
+            :hash (or (memory-object-hash obj) "(none)")
+            :scope (memory-object-scope obj)))))
+
+(defun audit-verify-hash ()
+  "Count memory objects and report any with missing/empty hashes.
+Returns (total . missing-hashes)."
+  (let ((total 0) (missing 0))
+    (maphash (lambda (id obj)
+               (declare (ignore id))
+               (when obj
+                 (incf total)
+                 (let ((h (memory-object-hash obj)))
+                   (when (or (null h) (string= h ""))
+                     (incf missing)))))
+             *memory-store*)
+    (cons total missing)))
+#+end_src
+
+* Test Suite
+Verifies that the Merkle hash is deterministic and consistent across independent AST ingestions.
+#+begin_src 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
+  "Contract 2: identical ASTs produce identical Merkle hashes."
+  (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)))))))))
+
+(test merkle-hash-different
+  "Contract 2: distinct ASTs produce different Merkle hashes."
+  (clrhash passepartout::*memory-store*)
+  (let* ((ast1 '(:type :HEADLINE :properties (:ID "a" :TITLE "Alpha") :contents nil))
+         (ast2 '(:type :HEADLINE :properties (:ID "b" :TITLE "Beta") :contents nil))
+         (id1 (ingest-ast ast1))
+         (id2 (ingest-ast ast2))
+         (hash1 (memory-object-hash (memory-object-get id1)))
+         (hash2 (memory-object-hash (memory-object-get id2))))
+    (is (not (equal hash1 hash2)))))
+
+(test test-ingest-ast-returns-id
+  "Contract 1: ingest-ast returns a string ID and stores the object."
+  (clrhash passepartout::*memory-store*)
+  (let ((id (ingest-ast '(:type :HEADLINE :properties (:ID "ingest-test" :TITLE "Test Node") :contents nil))))
+    (is (stringp id))
+    (is (not (null id)))))
+
+(test test-memory-object-get
+  "Contract 3: memory-object-get retrieves an object by ID after ingest."
+  (clrhash passepartout::*memory-store*)
+  (let ((id (ingest-ast '(:type :HEADLINE :properties (:ID "get-test" :TITLE "Retrieve Me") :contents nil))))
+    (let ((obj (memory-object-get id)))
+      (is (not (null obj)))
+      (is (eq :HEADLINE (memory-object-type obj)))
+      (is (string= "Retrieve Me" (getf (memory-object-attributes obj) :TITLE))))))
+
+(test test-snapshot-and-rollback
+  "Contract 4+5: snapshot-memory saves state; rollback-memory restores it."
+  (clrhash passepartout::*memory-store*)
+  (setf passepartout::*memory-snapshots* nil)
+  (ingest-ast '(:type :HEADLINE :properties (:ID "snap-a" :TITLE "Pre-snapshot") :contents nil))
+  (snapshot-memory)
+  (clrhash passepartout::*memory-store*)
+  (ingest-ast '(:type :HEADLINE :properties (:ID "snap-b" :TITLE "Post-snapshot") :contents nil))
+  (rollback-memory 0)
+  (is (not (null (memory-object-get "snap-a"))))
+  (is (null (memory-object-get "snap-b"))))
+
+(test test-undo-snapshot-restore
+  "Contract v0.7.2: undo-snapshot captures state, undo restores."
+  (let ((orig-store passepartout::*memory-store*)
+        (orig-undo passepartout::*undo-stack*)
+        (orig-redo passepartout::*redo-stack*))
+    (unwind-protect
+         (progn
+           (setf passepartout::*memory-store* (make-hash-table :test 'equal)
+                 passepartout::*undo-stack* nil
+                 passepartout::*redo-stack* nil)
+           (passepartout::undo-snapshot)
+           (setf (gethash "x" passepartout::*memory-store*) "hello")
+           (is (string= "hello" (gethash "x" passepartout::*memory-store*)))
+           (is (passepartout::undo))
+           (is (null (gethash "x" passepartout::*memory-store*))))
+      (setf passepartout::*memory-store* orig-store
+            passepartout::*undo-stack* orig-undo
+            passepartout::*redo-stack* orig-redo))))
+
+(test test-undo-redo-cycle
+  "Contract v0.7.2: redo restores undone state."
+  (let ((orig-store passepartout::*memory-store*)
+        (orig-undo passepartout::*undo-stack*)
+        (orig-redo passepartout::*redo-stack*))
+    (unwind-protect
+         (progn
+           (setf passepartout::*memory-store* (make-hash-table :test 'equal)
+                 passepartout::*undo-stack* nil
+                 passepartout::*redo-stack* nil)
+           (passepartout::undo-snapshot)
+           (setf (gethash "y" passepartout::*memory-store*) "world")
+           (is (passepartout::undo))
+           (is (null (gethash "y" passepartout::*memory-store*)))
+           (is (passepartout::redo))
+           (is (string= "world" (gethash "y" passepartout::*memory-store*))))
+      (setf passepartout::*memory-store* orig-store
+            passepartout::*undo-stack* orig-undo
+            passepartout::*redo-stack* orig-redo))))
+
+(test test-undo-empty-stack-nil
+  "Contract v0.7.2: undo returns nil on empty stack."
+  (let ((orig-undo passepartout::*undo-stack*))
+    (unwind-protect
+         (progn (setf passepartout::*undo-stack* nil)
+                (is (null (passepartout::undo))))
+      (setf passepartout::*undo-stack* orig-undo))))
+
+(test test-audit-node-found
+  "Contract v0.7.2: audit-node returns info for existing object."
+  (clrhash passepartout::*memory-store*)
+  (setf (gethash "audit-1" passepartout::*memory-store*)
+        (passepartout::make-memory-object :id "audit-1" :type :HEADLINE
+                                         :version 1 :hash "abc123" :scope :memex))
+  (let ((info (passepartout::audit-node "audit-1")))
+    (is (not (null info)))
+    (is (eq :HEADLINE (getf info :type)))
+    (is (string= "abc123" (getf info :hash)))))
+
+(test test-audit-node-not-found
+  "Contract v0.7.2: audit-node returns nil for nonexistent id."
+  (is (null (passepartout::audit-node "nonexistent-xxxx"))))
+
+(test test-audit-verify-hash
+  "Contract v0.7.2: audit-verify-hash returns (total . missing)."
+  (clrhash passepartout::*memory-store*)
+  (setf (gethash "a" passepartout::*memory-store*)
+        (passepartout::make-memory-object :id "a" :type :HEADLINE :hash "abc"))
+  (let ((result (passepartout::audit-verify-hash)))
+    (is (= 1 (car result)))
+    (is (= 0 (cdr result)))))
+#+end_src