feat: initial seed of domain-specific contrib skills

org-skill-web-interface.org

@@ -0,0 +1,92 @@
+:PROPERTIES:
+:ID:       ce3bef2a-ff93-49a5-ae5e-acde1de19000
+:CREATED:  [2026-03-30 Mon 21:16]
+:EDITED:   [2026-04-07 Tue 13:42]
+:END:
+#+TITLE: SKILL: Web Dashboard Agent (Universal Literate Note)
+#+STARTUP: content
+#+FILETAGS: :web:dashboard:telemetry:psf:
+
+* Overview
+The *Web Dashboard Agent* provides a lightweight telemetry window into the Neurosymbolic Kernel. It exposes the active skill graph and system logs via a local HTML dashboard.
+
+* Phase A: Demand (PRD)
+:PROPERTIES:
+:STATUS: FROZEN
+:END:
+
+** 1. Purpose
+Define the interfaces for system observability and telemetry serving.
+
+** 2. User Needs
+- *Transparency:* Overview of skill performance (executions, time, failures).
+- *Accessibility:* Served over a local HTTP port.
+- *Observability:* Tail of system logs for debugging.
+- *Low Overhead:* Background execution.
+
+** 3. Success Criteria
+*** TODO Server Bootstrap Verification
+*** TODO Telemetry Data Rendering
+*** TODO Log Tail Exposure
+
+
+* Phase B: Blueprint (PROTOCOL)
+:PROPERTIES:
+:STATUS: SIGNED
+:END:
+
+* Phase B: Blueprint (PROTOCOL)
+
+** 1. Architectural Intent
+
+The Web Dashboard Agent will function as a lightweight HTTP server exposing key aspects of the Neurosymbolic Kernel's state and logs.  It will leverage a simple, efficient rendering mechanism (likely string-based initially) to minimize overhead. Key components include:
+
+- *Telemetry Collection:*  A mechanism to passively receive skill execution telemetry data from the kernel.  This could involve a message queue, shared memory, or direct function calls.
+- *Data Model:* An in-memory representation of the collected telemetry data, optimized for fast rendering.
+- *HTTP Server:* A lightweight HTTP server (e.g., Hunchentoot, embeddable Jetty)  to serve the dashboard.
+- *Rendering Engine:* A template-based renderer to generate HTML from the data model.  Consider a simple string-based solution for initial implementation.
+- *Log Tail Reader:* A mechanism to efficiently read and expose the tail of the system log file(s).
+
+** 2. Semantic Interfaces (Lisp Signatures)
+
+*** `telemetry-collector (skill-name start-time end-time success-p)`
+
+    - *Purpose:*  Receives telemetry data from the Neurosymbolic Kernel.
+    - *Args:*
+       - `skill-name`:  Symbol representing the skill (e.g., `'parse-address`).
+       - `start-time`:  Timestamp (integer or float) of skill execution start.
+       - `end-time`:  Timestamp (integer or float) of skill execution end.
+       - `success-p`:  Boolean indicating successful execution (`T` or `NIL`).
+    - *Returns:* `T` (acknowledgment).
+    - *Side Effects:* Updates the in-memory data model.
+
+*** `current-telemetry-data ()`
+
+    - *Purpose:* Returns the current telemetry data for rendering.
+    - *Args:* None.
+    - *Returns:* A data structure, likely an alist or plist,  containing aggregated telemetry information suitable for rendering. Example:
+      ```lisp
+      (list :total-executions 1234 :successful-executions 1200 :failure-rate 0.027 :last-execution-times (list 1678886400 1678886460 1678886520))
+      ```
+
+*** `system-log-tail (n)`
+
+    - *Purpose:* Returns the last `n` lines of the system log.
+    - *Args:*
+       - `n`: Integer representing the number of lines to return.
+    - *Returns:* A list of strings, each string representing a line from the log file.
+
+*** `start-web-dashboard (port)`
+
+    - *Purpose:* Starts the HTTP server on the given port.
+    - *Args:*
+       - `port`: Integer representing the port number.
+    - *Returns:* `T` on success, `NIL` on failure.
+    - *Side Effects:* Starts the HTTP server in its own thread.
+
+*** `stop-web-dashboard ()`
+
+    - *Purpose:* Stops the HTTP server.
+    - *Args:* None.
+    - *Returns:* `T` on success, `NIL` on failure.
+    - *Side Effects:* Stops the HTTP server.