DOCS: Systematic overhaul of Literate source (Granularity & Technical Reasoning)

literate/manifest.org

@@ -4,19 +4,19 @@
 #+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, dependency resolution, and loading of all harness modules.
 
-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. 
+In standard Common Lisp projects, dependency graphs can be complex and non-linear. However, the OpenCortex harness mandates a strict, linear bootstrap sequence.
 
-Traditional Lisp systems often use complex, non-linear dependency graphs. However, the ~opencortex~ harness mandates a strict, linear bootstrap sequence.
+*** 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. 
+- *Why?* This eliminates "macro-not-found" errors by guaranteeing that the ~package.lisp~ (where the core namespace is defined) and ~skills.lisp~ (where core macros are defined) are always established before any behavioral logic or dynamic skills are loaded.
 
-*** 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.
+*** Separation of Concerns
+The manifest defines three distinct systems to minimize runtime bloat and maximize portability.
 
-*** 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]
@@ -26,8 +26,8 @@ flowchart TD
     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.
+** Core Harness System
+This system defines the "Thin Harness"—the minimalist microkernel responsible for the protocol and the metabolic loop.
 
 #+begin_src lisp :tangle ../opencortex.asd
 (defsystem :opencortex
@@ -55,8 +55,8 @@ This system defines the core "Thin Harness." It includes the protocol, the objec
   :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.
+** Verification Suite
+The Verification Suite contains the empirical tests required by the Engineering Standards. It is isolated from the core system to ensure that production environments do not load the FiveAM framework or test data.
 
 #+begin_src lisp :tangle ../opencortex.asd
 (defsystem :opencortex/tests
@@ -76,8 +76,8 @@ This system contains the empirical tests required by the Engineering Standards.
              (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.
+** TUI Client
+The TUI Client is a standalone consumer of the OpenCortex protocol. It uses the ~croatoan~ library for native terminal rendering.
 
 #+begin_src lisp :tangle ../opencortex.asd
 (defsystem :opencortex/tui