Initial commit: extracted from memex

docs/PHASE_2_ROADMAP.org

@@ -0,0 +1,39 @@
+#+TITLE: Phase 2: The Delegator (Roadmap)
+#+AUTHOR: org-agent
+#+DATE: [2026-03-23 Mon]
+
+* Overview
+Phase 2 shifts focus from kernel architecture to capability expansion. Because the kernel (Phase 1) is a generalized Event Bus, **all Phase 2 features are implemented entirely as Org-Native Skills**. No modifications to the Lisp Core (`core.lisp`, `neuro.lisp`, `symbolic.lisp`) are required.
+
+* The Phase 2 Skill Roster
+
+** 1. The LLM Router
+- **Skill File:** `skills/skill-router.org`
+- **Role:** Meta-cognition. Replaces complex Lisp trigger logic with LLM intent classification.
+- **Trigger:** Catches general `:user-command` or ambiguous `:buffer-update` events.
+- **Action:** Instead of editing a file, it emits an internal Lisp event `(:type :EVENT :payload (:sensor :delegation :target-skill <skill-name>))`, forcing the engine to re-loop and trigger the specific skill.
+
+** 2. Deep Memory (Vector/Semantic Search)
+- **Skill File:** `skills/skill-atomic-notes.org`
+- **Role:** Context augmentation beyond the live RAM `*object-store*`.
+- **System 2 (Lisp):** Wraps a local search tool (like `ripgrep` or a lightweight Lisp vector db).
+- **System 1 (LLM):** Formats the retrieved text into the Context API so downstream skills can read it before making decisions.
+
+** 3. The Shell Actuator
+- **Skill File:** `skills/skill-shell-actuator.org`
+- **Role:** Gives the agent hands outside of Emacs.
+- **Registration:** Uses `(org-agent:register-actuator :shell #'execute-shell-safely)`.
+- **System 2 (Gatekeeper):** A massive, paranoid Lisp function that whitelist-checks commands (e.g., allows `git status`, blocks `rm`).
+
+** 4. The Cron Scheduler
+- **Skill File:** `skills/skill-cron.org`
+- **Role:** Autonomous temporal action.
+- **Trigger:** `(eq sensor :heartbeat)`
+- **System 2 (Lisp):** Queries the `*object-store*` for deadlines. If a deadline has passed, it creates an action.
+- **System 1 (LLM):** Drafts a polite, contextual warning message to send to the user.
+
+** 5. Web Research
+- **Skill File:** `skills/skill-web-research.org`
+- **Role:** Internet connectivity via headless text browsing.
+- **System 2 (Lisp):** Wraps `lynx` and `curl` to fetch webpage content.
+- **System 1 (LLM):** Parses the raw HTML/text and synthesizes a summary for the user.

docs/PRD.org

@@ -0,0 +1,29 @@
+#+TITLE: PRD: org-agent Cognitive Core & Configuration
+#+AUTHOR: PSF Requirements Definer
+#+CREATED: [2026-03-23 Mon]
+#+STATUS: FROZEN
+
+* 0. Core Mandates
+The `org-agent` project MUST adhere to these foundational mandates:
+- **Mandate 1: Strict Homoiconic Memory.** All documentation, planning, and system logic MUST be authored in Org-mode (.org) and Common Lisp. Markdown (.md) and JSON are strictly prohibited for internal use.
+- **Mandate 2: Minimalist Microkernel.** The core daemon MUST remain minimalist, handling only the cognitive loop, the persistent Object-Store, and the communication protocol. All domain-specific features and LLM provider logic MUST be implemented as hot-reloadable **Skills** living in the user's Memex.
+
+* 1. Purpose
+The `org-agent` must transition from a monolithic prototype to a generalized neurosymbolic kernel.
+
+* 2. Functional Requirements
+** 2.1. Cognitive Loop (PTA Refactor)
+- The daemon MUST implement a 4-stage pipeline: Perceive -> Think -> Decide -> Act.
+- System 1 (Neural) MUST be restricted to the 'Think' stage.
+- System 2 (Symbolic) MUST have absolute authority in the 'Decide' stage to block or modify neural proposals.
+- The I/O protocol (OACP) MUST be encapsulated in 'Perceive' and 'Act'.
+
+** 2.2. Externalized Configuration (.env)
+- All secrets (API keys) and environment-specific settings (ports, paths) MUST live in a `.env` file.
+- The system MUST automatically load `.env` upon system initialization.
+- Secrets MUST NOT be hardcoded or checked into source control.
+
+* 3. Success Criteria
+ - TODO Daemon starts and loads LLM_API_KEY from .env.
+ - TODO `cognitive-loop` successfully routes a `:buffer-update` event through all 4 stages.
+ - TODO System 2 (`decide`) successfully blocks an `:eval` request containing "shell-command".

docs/PRD_LLM_CASCADE.org

@@ -0,0 +1,16 @@
+#+TITLE: PRD: LLM Failover Cascade & Multi-Provider Support
+#+AUTHOR: PSF Requirements Definer
+#+STATUS: FROZEN
+
+* 1. Purpose
+Ensure 100% availability of System 1 (Neural) reasoning via an ordered list of providers and automatic fallbacks.
+
+* 2. Functional Requirements
+- **Backend Registry:** The core MUST allow Skills to register new AI providers (Gemini, OpenAI, Claude, etc.).
+- **Automatic Failover:** The `ask-neuro` function MUST iterate through a `*provider-cascade*` list, automatically trying the next provider if the previous one fails.
+- **Interactive Re-Ordering:** The system MUST allow the user to update the cascade order in real-time from Emacs.
+
+* 3. Success Criteria
+ - DONE Daemon correctly falls back from a failing API key to a working one.
+ - DONE `M-x org-agent-set-model-cascade` successfully updates the live Lisp hierarchy.
+ - DONE Support for 5+ providers (Gemini, OpenAI, Anthropic, OpenRouter, Ollama).

docs/PRD_ORG_DELIVERY.org

@@ -0,0 +1,17 @@
+#+TITLE: PRD: Org-Native Multi-Modal Delivery
+#+AUTHOR: PSF Requirements Definer
+#+STATUS: FROZEN
+
+* 1. Purpose
+Enable the agent to communicate outside of Emacs while maintaining all outbound records in a human-readable, homoiconic format.
+
+* 2. Functional Requirements
+- **Org-Native Outbox:** The system MUST use a central Org file (`9_system/delivery.org`) as its outbound message queue.
+- **Actuator API:** A `:delivery` actuator MUST be registered to handle external messaging intents.
+- **Channel Support:** The system MUST support Signal, Telegram, and Discord metadata.
+- **Proactive Alerts:** The Cron skill MUST be able to route alerts to the delivery actuator based on Org properties.
+
+* 3. Success Criteria
+ - DONE New messages appear as structured headlines in `delivery.org`.
+ - DONE Metadata (channel, target) is stored in native Org property drawers.
+ - DONE No hidden JSON or external database required for queueing.

docs/PRD_PROJECT_FOUNDRY.org

@@ -0,0 +1,17 @@
+#+TITLE: PRD: Project Foundry (Scaffolding)
+#+AUTHOR: PSF Requirements Definer
+#+STATUS: FROZEN
+
+* 1. Purpose
+Act as a senior engineer by autonomously scaffolding new project directories, git repos, and documentation templates.
+
+* 2. Functional Requirements
+- **Directory Creation:** The system MUST be able to create new folders within the `$PROJECTS_DIR`.
+- **Git Integration:** The foundry MUST initialize a new git repository for every scaffolded project.
+- **Boilerplate Generation:** The system MUST write a customized `README.org` for new projects.
+- **GTD Connection:** The foundry MUST automatically add a `PROJ` headline to `gtd.org` with a dynamic `:PROJECT_PATH:`.
+
+* 3. Success Criteria
+ - DONE New projects appear in the physical filesystem and the GTD plan simultaneously.
+ - DONE Path resolution handles environment variables (`$PROJECTS_DIR`) correctly.
+ - DONE System 2 prevents overwriting existing project directories.

docs/PRD_SKILL_GRAPH.org

@@ -0,0 +1,16 @@
+#+TITLE: PRD: The Skill Graph & Self-Awareness
+#+AUTHOR: PSF Requirements Definer
+#+STATUS: FROZEN
+
+* 1. Purpose
+Enable recursive, networked intelligence by unifying logic (skills) and knowledge (Atomic Notes (Zettelkasten)).
+
+* 2. Functional Requirements
+- **Dependency Tracking:** Skills MUST be able to declare dependencies on other skills via `#+DEPENDS_ON:`.
+- **Introspection:** The kernel MUST provide an API to list all active skills and read their source code.
+- **Topological Dispatch:** The system MUST resolve dependencies recursively before engaging a skill.
+
+* 3. Success Criteria
+ - DONE `(context-list-all-skills)` returns accurate priority and dependency metadata.
+ - DONE Skills jailed in isolated packages can still resolve symbols from their declared dependencies.
+ - DONE The Brain Mapper skill can successfully visualize the network.

docs/PRD_WEB_DASHBOARD.org

@@ -0,0 +1,17 @@
+#+TITLE: PRD: Kernel Web Dashboard
+#+AUTHOR: PSF Requirements Definer
+#+STATUS: FROZEN
+
+* 1. Purpose
+Provide a read-only visual interface for monitoring the Lisp Machine's internal state and execution logs.
+
+* 2. Functional Requirements
+- **Web Server:** A lightweight HTTP server (Hunchentoot) MUST run inside the kernel.
+- **Skill Visualization:** The dashboard MUST display the current Skill Graph, priorities, and jailing status.
+- **Log Monitoring:** The dashboard MUST display the most recent 20-50 system log entries.
+- **Remote Access:** The dashboard MUST be accessible from other computers on the local network (binding to 0.0.0.0).
+
+* 3. Success Criteria
+ - DONE Dashboard loads at `http://<ip>:8081`.
+ - DONE Skill list updates dynamically as new skills are hot-loaded.
+ - DONE Kernel errors are visible in the web UI.

docs/PRD_dynamic_model_switching.org

@@ -0,0 +1,23 @@
+#+TITLE: PRD: Skill-Based Dynamic Model Switching
+#+AUTHOR: PSF Requirements Definer
+#+DATE: 2026-03-24
+#+STARTUP: content
+
+* Overview
+The `org-agent` currently relies on hardcoded LLM model strings within its pluggable provider skills. To match the flexibility of the legacy Openclaw system while maintaining a **Minimalist Core**, we will implement a "Homoiconic Configuration" model using the **Skill Graph**. Configuration settings will live as standard Org-mode properties in the user's memex, and a dedicated configuration skill will provide lookup services to other skills.
+
+* Mandates
+- **The Org Mandate:** Configuration MUST be human-editable and machine-readable within `.org` files.
+- **Minimalist Core:** No new global variables or state-management registries shall be added to the kernel (`src/*.lisp`).
+- **Skill Graph Sovereignty:** Capabilities MUST build upon one another via dependencies.
+
+* Requirements
+1. **Property-Based Configuration:** The system MUST allow defining LLM models via Org-mode properties (e.g., `:LLM_MODEL_OPENAI: gpt-4o`) anywhere in the loaded memex files.
+2. **Configuration Skill:** A new skill (`skill-environment-config.org`) MUST be created to handle property lookups within the persistent `*object-store*`.
+3. **Skill Integration:** Provider skills (OpenAI, Anthropic, OpenRouter) MUST declare a dependency on `skill-environment-config` and query it for their model string at runtime.
+4. **Late-Binding Updates:** Because the kernel updates the `*object-store*` on every buffer save, changing a model string in an Org file results in an immediate, hot-swapped change to the agent's behavior.
+
+* Acceptance Criteria
+- A user can add `:LLM_MODEL_OPENAI: gpt-4o` to a "Settings" headline in their memex.
+- The OpenAI provider skill successfully fetches this value via the configuration skill.
+- No modifications are made to the core Lisp daemon files.

docs/PRD_model_discovery.org

@@ -0,0 +1,22 @@
+#+TITLE: PRD: Model Discovery
+#+AUTHOR: PSF Requirements Definer
+#+DATE: 2026-03-24
+#+STARTUP: content
+
+* Overview
+Users currently lack visibility into the LLM models available via the registered provider skills (OpenAI, Anthropic, OpenRouter). To match Openclaw's UX while preserving a Minimalist Core, the system needs an intra-skill discovery protocol.
+
+* Mandates
+- **The Org Mandate:** Outputs must be rendered natively in Org-mode buffers.
+- **Minimalist Core:** No state or new capabilities shall be added to the Lisp Daemon. All discovery logic must be localized to the Skill Graph.
+
+* Requirements
+1. **Dynamic Provider Introspection:** The system MUST be able to query loaded skills dynamically to find which ones act as LLM providers.
+2. **Model Listing API:** Every provider skill MUST export a function that returns a list of its available models (e.g., ID, Context Window).
+3. **The Explorer Skill:** A new skill (`skill-model-explorer.org`) MUST intercept the command `@agent list models` and aggregate the results from all providers.
+4. **Org-Table Output:** The Explorer Skill MUST output the aggregated list back to the Emacs buffer formatted as an `org-table` for immediate human readability.
+
+* Acceptance Criteria
+- Writing `@agent list models` in an Org buffer and saving triggers the Explorer Skill.
+- An Org-mode table is inserted below the command containing columns for `Provider`, `Model`, and `Context`.
+- Adding a new provider skill automatically includes its models in future queries without modifying the Explorer Skill.

docs/PROTOCOL.org

@@ -0,0 +1,137 @@
+#+TITLE: org-agent Communication Protocol (OACP)
+#+AUTHOR: Agent
+#+DATE: 2026-03-22
+#+ID: org-agent-protocol
+#+STARTUP: content
+
+* Core Mandates
+The OACP and the `org-agent` project MUST adhere to these foundational mandates:
+- **Mandate 1: Strict Homoiconic Memory.** All documentation, planning, and system logic MUST be authored in Org-mode (.org) and Common Lisp. Markdown (.md) and JSON are strictly prohibited for internal use.
+- **Mandate 2: Minimalist Microkernel.** The core daemon MUST remain minimalist, handling only the cognitive loop, the persistent Object-Store, and the communication protocol. All domain-specific features and LLM provider logic MUST be implemented as hot-reloadable **Skills** living in the user's Memex.
+
+* Overview
+
+OACP (org-agent Communication Protocol) defines the "nervous system" of the Neurosymbolic Lisp Machine. It facilitates bidirectional, asynchronous communication between the **Common Lisp Core** (The Soul/Daemon) and the **Emacs Interface** (The Actuator/Terminal).
+
+The protocol is designed to be:
+- **Homoiconic:** Messages are native Lisp S-expressions (plists).
+- **Asynchronous:** Neither side should block waiting for the other.
+- **Extensible:** New sensors and actuators can be added by defining new plist keys.
+
+* Framing & Transport
+
+- **Transport:** TCP Socket (default port: 9105).
+- **Framing:** Each message is prefixed by a 6-character hexadecimal length string (e.g., `00002a` for a 42-byte message), followed by the S-expression string encoded in UTF-8.
+
+* Message Structure
+
+A standard message is a flat property list (plist):
+
+#+begin_src lisp
+(:type TYPE :id ID :payload PAYLOAD)
+#+end_src
+
+- **:type:** One of `:EVENT`, `:REQUEST`, `:RESPONSE`, or `:LOG`.
+- **:id:** A unique integer or string for correlation (mandatory for `:REQUEST` and `:RESPONSE`).
+- **:payload:** A nested plist containing the specific data or command.
+
+* Perception (Emacs -> Core)
+
+Emacs acts as the sensor array, pushing events to the Core daemon.
+
+** :BUFFER-MODIFIED
+Sent when an Org buffer is changed or saved.
+#+begin_src lisp
+(:type :EVENT :payload (:sensor :buffer-update :file "/home/amr/org/todo.org" :state :saved))
+#+end_src
+
+** :USER-INPUT
+Sent when the user explicitly triggers an agent action (e.g., `M-x org-agent-ask`).
+#+begin_src lisp
+(:type :EVENT :payload (:sensor :user-prompt :text "Refactor this subtree" :context :current-subtree))
+#+end_src
+
+** :CURSOR-MOVED
+Sent when the agent needs to track the user's focus.
+#+begin_src lisp
+(:type :EVENT :payload (:sensor :focus :buffer "init.el" :line 42 :column 0))
+#+end_src
+
+* Action (Core -> Emacs)
+
+The Core daemon sends requests to Emacs to perform physical actions in the environment.
+
+** :EXECUTE-ELISP
+The primary "actuator."
+#+begin_src lisp
+(:type :REQUEST :id 101 :payload (:action :eval :code "(org-todo \"NEXT\")"))
+#+end_src
+
+** :UI-NOTIFY
+Display info to the user without interrupting focus.
+#+begin_src lisp
+(:type :REQUEST :id 102 :payload (:action :message :text "I have identified a contradiction in your GTD.org" :level :warning))
+#+end_src
+
+** :PROVIDE-COMPLETION
+Provide LLM-driven completions for the current point.
+#+begin_src lisp
+(:type :REQUEST :id 103 :payload (:action :complete :prefix "defun" :suggestions ("defun-agent" "defun-percieve")))
+#+end_src
+
+** :ORG-DELIVERY
+Enqueue external messages.
+#+begin_src lisp
+(:type :REQUEST :target :delivery :payload (:channel :signal :to "+1..." :text "Hello"))
+#+end_src
+
+** :PROJECT-SCAFFOLD
+Create new project folders and headings.
+#+begin_src lisp
+(:type :REQUEST :target :foundry :payload (:action :scaffold :name "Project-X" :type "Lisp"))
+#+end_src
+
+** :SYSTEM-SELF-EDIT
+Kernel-level self-modification.
+#+begin_src lisp
+(:type :REQUEST :target :system :payload (:action :create-skill :filename "skill-x.org" :content "..."))
+#+end_src
+
+* Metadata & Handshake
+
+** :HELLO
+Sent by both sides upon connection.
+#+begin_src lisp
+(:type :EVENT :payload (:action :handshake :version "0.1.0" :capabilities (:auth :swank :org-ast)))
+#+end_src
+
+* Cognitive Loop Internal API (Foundry Standard)
+
+To ensure neurosymbolic sovereignty, the Core Daemon must strictly separate stages.
+
+** 1. Perceive
+- **Signature:** `(perceive raw-stimulus) -> context-plist`
+- **Responsibility:** Protocol decoding, Object-Store synchronization, context augmentation.
+
+** 2. Think (System 1)
+- **Signature:** `(think context-plist) -> proposed-action-plist`
+- **Responsibility:** Neural pattern matching, associative retrieval, unverified proposal generation.
+
+** 3. Decide (System 2)
+- **Signature:** `(decide proposed-action context) -> approved-action-plist`
+- **Responsibility:** Symbolic verification, safety gating, deterministic rule application (e.g., GTD logic).
+
+** 4. Act (Dispatch)
+- **Signature:** `(act stream approved-action)` / `(dispatch-action approved-action)`
+- **Responsibility:** Actuator lookup and transmission. Targets: `:emacs`, `:delivery`, `:system`, `:shell`.
+
+** 5. Context API (System 1 Peripheral Vision)
+- **(context-list-all-skills):** Introspect the brain hierarchy.
+- **(context-get-skill-source name):** Read the logic graph.
+- **(context-resolve-path path):** Environment-relative path expansion.
+- **(context-get-system-logs limit):** Perception of kernel failures.
+
+* Success Metrics
+- Latency between `:EVENT` and `:RESPONSE` < 100ms for UI actions.
+- 100% fidelity in Org AST preservation across the bridge.
+- Zero UI blocking in Emacs during heavy CL reasoning loops.

docs/PROTOCOL_dynamic_model_switching.org

@@ -0,0 +1,47 @@
+#+TITLE: PROTOCOL: Skill-Based Configuration
+#+AUTHOR: PSF Architect
+#+DATE: 2026-03-24
+#+STARTUP: content
+
+* Overview
+This protocol defines the skill-to-skill interface for retrieving environment configuration from the Org-mode Object-Store. It leverages the **Skill Graph** to provide a centralized configuration API for all other skills.
+
+* The Configuration Skill (`skill-environment-config.org`)
+
+** 1. Internal Logic
+The skill iterates over the kernel's `*object-store*` to find headlines containing specific properties.
+
+#+begin_src lisp
+(defun get-config-attribute (property-key &optional default)
+  "Searches the global *object-store* for any headline containing PROPERTY-KEY."
+  (let ((store org-agent:*object-store*))
+    (maphash (lambda (id obj)
+               (declare (ignore id))
+               (when (eq (org-agent:org-object-type obj) :HEADLINE)
+                 (let ((val (getf (org-agent:org-object-attributes obj) property-key)))
+                   (when val
+                     (return-from get-config-attribute val)))))
+             store)
+    default))
+#+end_src
+
+* Skill Graph Integration
+
+** 2. Dependency Declaration
+Other skills requiring configuration MUST declare a dependency on this skill.
+
+#+begin_src org
+#+DEPENDS_ON: skill-environment-config
+#+end_src
+
+** 3. Provider Integration Example
+Provider skills will invoke the config skill's API during the System 1 prompt generation.
+
+#+begin_src lisp
+(let ((model (org-agent.skills.skill-environment-config:get-config-attribute :LLM_MODEL_OPENAI "gpt-4-turbo-preview")))
+  ;; ... use model in API call ...
+  )
+#+end_src
+
+* No Core Modifications Required
+This protocol adheres to the **Minimalist Core** mandate by implementing the entirety of the "Dynamic Model Switching" logic within the Skill Layer.

docs/PROTOCOL_model_discovery.org

@@ -0,0 +1,51 @@
+#+TITLE: PROTOCOL: Model Discovery
+#+AUTHOR: PSF Architect
+#+DATE: 2026-03-24
+#+STARTUP: content
+
+* Overview
+This protocol defines the interfaces allowing the `org-agent` to dynamically introspect available models from any loaded provider skill, outputting the result to Emacs as an Org table.
+
+* 1. The Provider Export Interface
+Every skill acting as a Neural Provider MUST export a function named `GET-AVAILABLE-MODELS`.
+
+#+begin_src lisp
+;; Signature
+(get-available-models) -> list-of-plists
+
+;; Return Format Example
+'((:id "gpt-4-turbo" :context "128k")
+  (:id "gpt-4o"      :context "128k"))
+#+end_src
+
+* 2. The Model Explorer Skill (`skill-model-explorer.org`)
+
+** Dynamic Introspection
+The explorer uses the kernel's `(org-agent:context-list-all-skills)` API to find all skills whose name starts with `skill-provider-`.
+
+For each matching skill, it looks up the package:
+#+begin_src lisp
+(let* ((pkg (find-package (intern (string-upcase (format nil "ORG-AGENT.SKILLS.~a" skill-name)) :keyword)))
+       (fn (when pkg (find-symbol "GET-AVAILABLE-MODELS" pkg))))
+  (when (and fn (fboundp fn))
+    (funcall fn)))
+#+end_src
+
+** Org-Table Formatting
+The explorer aggregates the plists and formats them into an Org table string:
+#+begin_example
+| Provider | Model ID | Context |
+|----------+----------+---------|
+| OpenAI   | gpt-4o   | 128k    |
+#+end_example
+
+* 3. Emacs Actuator Command
+The explorer generates a System 2 `approved-action` that instructs the `:emacs` actuator to insert this text.
+
+#+begin_src lisp
+'(:type :REQUEST 
+  :target :emacs 
+  :payload (:action :insert-text 
+            :text "| Provider | Model ID | Context |\n..."
+            :position :after-trigger))
+#+end_src