#+TITLE: SKILL: Org-Mode & AST Manipulation (The Grammar)
#+ID: skill-org-mode
#+STARTUP: content
#+FILETAGS: :org-mode:ast:homoiconic:

* Overview
This skill defines the **Grammar of the Memex**. It is the set of rules that allow the `org-agent` to treat plain text as a structured, hierarchical database. In the [[file:personal-software-foundry.org][Personal Software Foundry (PSF)]], Org-mode is the **Homoiconic Memory**—it is both the documentation for humans and the abstract syntax tree (AST) for the agent.

* The Org Mandate
Following the PSF Mandates, all internal logic, plans, and skills MUST follow these structural rules:

** 1. Everything is a Node
Every concept or task is represented as an Org headline. 
- **Headlines:** Hierarchical structure using asterisks (`*`, `**`, etc.).
- **Metadata:** Contained within `:PROPERTIES:` drawers.
- **Identity:** Every permanent node MUST have a globally unique `:ID:` for robust cross-referencing.

** 2. Literate Programming
Code is never isolated. It must be wrapped in `#+begin_src` blocks and accompanied by a narrative that explains its architectural intent. This ensures the "Why" is as persistent as the "How."

** 3. Naming & Paths
The Memex uses a strictly flat, link-heavy structure to prevent "folder silos":
- **Daily Captures:** `~/memex/daily/YYYY-MM-DD.org`
- **Permanent Knowledge:** `~/memex/notes/kebab-case-filename.org`
- **Project Roots:** `~/memex/projects/project-name/`

* Binary Integrity (org-attach)
To prevent "broken path rot," all binary files (PDFs, images, data) are managed via the **Attachment Protocol**.
1. **Host Node:** Binaries are always attached to a specific symbolic node (headline).
2. **ID-Based Storage:** Files are stored in a directory named after the node's UUID.
3. **Internal Linking:** Use `[[attachment:filename.ext]]` to ensure links remain valid even if the host file is moved.

* Symbolic Implementation
The following logic defines how the agent perceives and manipulates the Org AST.

#+begin_src lisp
(defun org-mode-parse-node (id)
  "Retrieves the AST of a specific node by its ID."
  (let ((notes-dir (expand-file-name "~/memex/notes/")))
    (kernel-log "AST - Parsing node: ~a" id)
    ;; Implementation of org-element-parse-buffer for the targeted node
    (org-agent:run-shell-command (format nil "grep -r ':ID: ~a' ~a" id notes-dir))))
#+end_src

* See Also
- [[file:personal-software-foundry.org][Personal Software Foundry Mandates]]
- [[file:org-skill-scribe.org][Scribe Agent (The Archivist)]]