#+TITLE: SKILL: Org-Mode & AST Manipulation (Universal Literate Note)
#+ID: skill-org-mode
#+STARTUP: content
#+FILETAGS: :org-mode:ast:homoiconic:psf:

* Overview
This skill defines the **Grammar of the Memex**. It establishes the rules for treating plain text as a structured, hierarchical database. Org-mode is our **Homoiconic Memory**—documentation for humans and AST for the agent.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define the structural rules and manipulation interfaces for the Org-mode AST.

** 2. User Needs
- **Everything is a Node:** Mandatory headlines, properties, and unique IDs.
- **Literate Programming:** Code must be wrapped in narrative-rich blocks.
- **Naming & Paths:** Strict kebab-case and flat directory structure.
- **Binary Integrity:** Management of attachments via the Attachment Protocol.

** 3. Success Criteria
*** TODO ID Uniqueness Enforcement
*** TODO Literate Block Parsing
*** TODO Attachment Link Validation

* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

** 1. Architectural Intent
Interfaces for perceiving and manipulating Org nodes. Source of truth is the filesystem and the Org element parser.

** 2. Semantic Interfaces
#+begin_src lisp
(defun org-mode-parse-node (id)
  "Retrieves the AST of a specific node by its ID.")

(defun org-mode-validate-structure (file-path)
  "Checks a file for compliance with the Org Mandate.")
#+end_src

* Phase D: Build (Implementation)

** Node Parsing
#+begin_src lisp :tangle projects/org-skill-org-mode/src/org-logic.lisp
(defun org-mode-parse-node (id)
  "Retrieves the AST of a specific node by its ID."
  (let ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "notes/")))
    (kernel-log "AST - Parsing node: ~a" id)
    ;; In practice, this uses cl-org-mode or similar element parsers
    (uiop:run-program (list "grep" "-r" (format nil ":ID: ~a" id) notes-dir) :output :string)))
#+end_src

** Attachment Protocol
#+begin_src lisp :tangle projects/org-skill-org-mode/src/org-logic.lisp
(defun org-mode-get-attachment-path (node-id filename)
  "Resolves the physical path of an attachment based on node ID."
  (format nil "attachments/~a/~a" node-id filename))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-org-mode
  :priority 100
  :trigger (lambda (context) nil)
  :neuro (lambda (context) nil)
  :symbolic #'org-mode-parse-node)
#+end_src