reseed

CLAUDE.md

@@ -44,8 +44,10 @@ This SleeperAgents-internal project (RcmEmailAutomation) sits at the SA-Orchestr
 
 ## ── REPO LAYOUT (root level) ────────────────────────────────────────────────
 
+> Paths below are **relative to this repo root** — wherever the developer cloned it. Drive letters and absolute paths from the seeding machine do not apply. See `README.md` → "Path discipline" before assuming any path.
+
 ```
-F:\SleeperAgents\RcmEmailAutomation\
+<repo-root>/                 ← wherever the developer cloned RcmEmailAutomation
 ├── app/                     ← Python FastAPI service (production target)
 │   ├── main.py
 │   ├── auth.py, config.py, database.py, email_processor.py

ONBOARDING.md

@@ -64,13 +64,14 @@ Run this audit before installing or running anything. Surface findings to the hu
 
 ### Audit checklist
 
-1. **Local stack capability** — does this machine already have a local PHP + MySQL + WordPress capability? Check for:
-   - XAMPP at `C:\xampp` or `F:\XAMPP` or similar
-   - Local by Flywheel at `C:\Users\<user>\Local Sites`
-   - Laragon at `C:\laragon`
-   - MAMP at `/Applications/MAMP` (macOS) or equivalent
-   - Docker Desktop with WordPress containers
+1. **Local stack capability** — does this machine already have a local PHP + MySQL + WordPress capability? **Where the developer's stack lives is a Phase 0 question** (see Phase 0 above) — do NOT assume a default install location. Common patterns the audit may discover:
+   - XAMPP (Windows: typically `C:\xampp`; sometimes installed on a different drive — confirm with the developer, never assume)
+   - Local by Flywheel (Windows: `C:\Users\<user>\Local Sites`; macOS: `~/Local Sites`)
+   - Laragon (Windows: typically `C:\laragon` — confirm)
+   - MAMP (macOS: `/Applications/MAMP`; Windows: `C:\MAMP`)
+   - Docker Desktop with WordPress containers (any path; ask)
    - Any custom Apache/Nginx + PHP-FPM + MySQL combination
+   - **The developer may have none of the above** — JNO must respect that and use what they have or what they explicitly approve installing. Do not install on a drive or location the developer has not authorized.
 
 2. **PHP version available** — `php --version` (target: 7.4+, 8.1+ preferred)
 
@@ -177,16 +178,21 @@ cp -r <this-repo>/asterion/* <wp-install>/wp-content/sa-asterion/
 
 **B. Point the spec_root filter at this repo's `asterion/` directory directly** (no copy):
 
-Drop a mu-plugin at `<wp-install>/wp-content/mu-plugins/sa-orch-spec-root.php`:
+Drop a mu-plugin at `<wp-install>/wp-content/mu-plugins/sa-orch-spec-root.php`. The filter must return the **absolute path to this repo's `asterion/` directory on the developer's machine** — substitute `<repo-root>` with whatever the developer's actual clone path is (Phase 0 should have surfaced this; if not, ask):
 
 ```php
 <?php
 add_filter( 'sa_orch_asterion_spec_root', function () {
-    return 'F:/SleeperAgents/RcmEmailAutomation/asterion';
+    // Replace <repo-root> with the absolute path to where this repo lives
+    // on the developer's machine. DO NOT hardcode a drive letter or path
+    // that has not been confirmed by the developer.
+    return '<repo-root>/asterion';
 }, 5 );
 ```
 
-Choose A for cleanliness (corpus lives inside the WP install). Choose B for "single source of truth" (corpus stays in this repo, the WP install reads through). Either is acceptable for JNO.
+If the developer prefers POSIX-style forward slashes vs. Windows backslashes, follow their convention — WordPress accepts either, but consistency aids debugging. **Verify the path resolves** (`is_dir()` returns true) before trusting it; otherwise the Asterion Explorer will silently render an empty tree.
+
+Choose A for cleanliness (corpus lives inside the WP install, no path-resolution surprises). Choose B for "single source of truth" (corpus stays in this repo, the WP install reads through). Either is acceptable for JNO. **Discuss the trade-off with the developer; they pick.**
 
 **Verify**: filesystem readable by the web user; `01-ontology.md` and `02-invariants.md` exist at the chosen location.
 

README.md

@@ -32,7 +32,20 @@ CR ⊇ CA ⊇ JourneySeeker ⊇ MissionNet/MeshNet ⊇ SA-Orchestration ⊇ Bran
 
 Causal Relativity, Causal Agentics, JourneySeeker, the Compass Doctrine, the Story Seed pattern, and the Quest-vs-Job distinction are pre-existing intellectual property authored by **Mark Holak**. They are preserved under Invariant **I9** of the SA-Orchestration spec pack. **You may reference these concepts. You may not re-author them as if they originated at the implementation layer or at the agent layer.** When you cite them, cite them.
 
-The full canonical corpus lives at `asterion/` in this repo (copied from the SA-Orchestration source of truth at `F:/SleeperAgents/SA-orchestration/asterion/`). Read it when you encounter a term you are uncertain about.
+The full canonical corpus lives at **`asterion/` in this repo** (copied here at seed time from the SA-Orchestration source of truth that lives in a separate SleeperAgents-internal repository — the absolute path on the seeding machine is not relevant to the developer's machine). Read it when you encounter a term you are uncertain about.
+
+### Path discipline (read once; never violate)
+
+This seed was authored on a different machine than the developer's. **Any absolute path that may appear in `ONBOARDING.md`, in this README, or in code excerpts is illustrative — drawn from the seeding machine — not canonical for the developer's environment.** Drive letters, root paths, and OS conventions on the seeding machine do not transfer.
+
+Specifically:
+
+- **Do not** install anything onto a drive letter, mount point, or path the developer has not declared.
+- **Do not** assume any directory exists outside this repo's tree without verifying or asking.
+- **Always** map paths through the developer's stated layout (Phase 0 surfaces this).
+- **When in doubt about where something goes, ask.** The developer is the arbiter of their domain (see Phase 0 in `ONBOARDING.md`). Asking is cheaper than installing into the wrong place.
+
+If the developer has not declared a drive layout in Phase 0, **ask explicitly before any install action**. Path-related questions are the kind that quietly pass when the agent assumes — and quietly destroy when the assumption is wrong.
 
 ### Doctrine carry-forward (the operating discipline)
 

sa-orchestration/README.md

@@ -0,0 +1,33 @@
+# SA-Orchestration plugin (v0.1.0)
+
+First slice of the SA-Core / MissionNet alignment layer above the Fluent stack.
+
+## What it does
+
+Records three kinds of canonical artifacts that Fluent does not natively carry:
+
+| Artifact | Table | Concept |
+|---|---|---|
+| Arbitration record | `wp_sa_arbitration` | Manager-as-arbiter outcome (rationale, projection_type, demand_ref) |
+| Demand → Plan linkage | `wp_sa_arbitration_plan_link` | Edges from an arbitration to its resulting Plan refs |
+| Acceptance event chain | `wp_sa_acceptance_event` | Append-only events: result_claimed → acceptance_disputed → acceptance_affirmed |
+
+Each row has a corresponding markdown file in the **Asterion ledger** at `wp-content/sa-asterion/`. **Asterion is canonical-at-write; the DB is cache.** If the file write fails, no DB row is created.
+
+## REST endpoints (admin-only)
+
+```
+POST /wp-json/sa-orch/v1/arbitration
+POST /wp-json/sa-orch/v1/acceptance
+GET  /wp-json/sa-orch/v1/demand/{surface}/{ref}/trace
+```
+
+All require `current_user_can('manage_options')`.
+
+## Schema reference
+
+See [SA-orchestration repo](../../../../../SleeperAgents/SA-orchestration) — `FLUENT_DATA_MAPPING.md` and `CORE_MODEL.md` for vocabulary.
+
+## Status
+
+v0.1.0 — minimum viable. No admin UI. No advanced features. Plugin code currently lives at `wp-content/plugins/sa-orchestration/`; canonical home should move to the SA-orchestration repo at a future milestone.

sa-orchestration/assets/asterion-bubble.css

@@ -0,0 +1,245 @@
+/* Asterion Projection — floating canonical-query button (Board #30) */
+
+#sa-orch-asterion-root {
+    position: fixed;
+    top: 60px;
+    right: 24px;
+    z-index: 99998;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+}
+
+#sa-orch-asterion-button {
+    width: 48px;
+    height: 48px;
+    border-radius: 50%;
+    background: #1a1a24;
+    color: #e8e8ea;
+    border: 2px solid #4a4a55;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    box-shadow: 0 2px 10px rgba(0,0,0,0.3);
+    transition: all 0.15s ease;
+}
+
+#sa-orch-asterion-button:hover {
+    background: #25252e;
+    border-color: #6a6a75;
+    transform: scale(1.05);
+}
+
+.sa-orch-asterion-glyph {
+    font-size: 22px;
+    line-height: 1;
+}
+
+#sa-orch-asterion-panel {
+    position: fixed;
+    top: 60px;
+    right: 80px;
+    width: 420px;
+    max-height: 70vh;
+    background: #15151c;
+    color: #e8e8ea;
+    border: 1px solid #3a3a45;
+    border-radius: 8px;
+    box-shadow: 0 8px 32px rgba(0,0,0,0.5);
+    display: none;
+    flex-direction: column;
+    overflow: hidden;
+    font-size: 13px;
+}
+
+#sa-orch-asterion-panel.open {
+    display: flex;
+}
+
+.sa-orch-asterion-header {
+    padding: 10px 14px;
+    background: #1f1f28;
+    border-bottom: 1px solid #3a3a45;
+    position: relative;
+}
+
+.sa-orch-asterion-title {
+    font-weight: 700;
+    font-size: 14px;
+    letter-spacing: 0.4px;
+    color: #e8e8ea;
+}
+
+.sa-orch-asterion-subtitle {
+    font-size: 11px;
+    color: #8a8a95;
+    margin-top: 2px;
+}
+
+.sa-orch-asterion-close {
+    position: absolute;
+    top: 6px;
+    right: 8px;
+    background: transparent;
+    color: #8a8a95;
+    border: 0;
+    font-size: 20px;
+    line-height: 1;
+    cursor: pointer;
+    padding: 4px 8px;
+}
+
+.sa-orch-asterion-close:hover {
+    color: #e8e8ea;
+}
+
+.sa-orch-asterion-context {
+    padding: 6px 14px;
+    background: #14141a;
+    border-bottom: 1px solid #2a2a33;
+    font-size: 11px;
+    color: #a0a0ad;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+.sa-orch-asterion-conv {
+    flex: 1;
+    overflow-y: auto;
+    padding: 10px 14px;
+    min-height: 80px;
+    max-height: 400px;
+}
+
+.sa-orch-asterion-hint {
+    color: #777783;
+    font-size: 12px;
+    font-style: italic;
+}
+
+.sa-orch-asterion-qa {
+    margin-bottom: 16px;
+    padding-bottom: 12px;
+    border-bottom: 1px dashed #2e2e38;
+}
+
+.sa-orch-asterion-qa:last-child {
+    border-bottom: 0;
+}
+
+.sa-orch-asterion-q {
+    color: #c8c8d2;
+    font-weight: 600;
+    margin-bottom: 6px;
+}
+
+.sa-orch-asterion-q::before {
+    content: "▸ ";
+    color: #6a6a75;
+}
+
+.sa-orch-asterion-a {
+    color: #e8e8ea;
+    line-height: 1.5;
+    white-space: pre-wrap;
+    margin-bottom: 8px;
+}
+
+.sa-orch-asterion-cites {
+    margin-top: 8px;
+    padding: 8px 10px;
+    background: #11111a;
+    border-left: 3px solid #4a4a55;
+    border-radius: 0 4px 4px 0;
+}
+
+.sa-orch-asterion-cites-label {
+    font-size: 10px;
+    color: #8a8a95;
+    letter-spacing: 1.2px;
+    margin-bottom: 6px;
+    font-weight: 700;
+}
+
+.sa-orch-asterion-cite {
+    margin-bottom: 8px;
+}
+
+.sa-orch-asterion-cite:last-child {
+    margin-bottom: 0;
+}
+
+.sa-orch-asterion-cite-file {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 11px;
+    color: #c8c8d2;
+    font-weight: 600;
+}
+
+.sa-orch-asterion-cite-excerpt {
+    font-size: 11.5px;
+    color: #a0a0ad;
+    margin-top: 2px;
+    padding-left: 12px;
+    line-height: 1.45;
+    white-space: pre-wrap;
+}
+
+.sa-orch-asterion-scope {
+    font-size: 10px;
+    color: #6a6a75;
+    margin-top: 6px;
+    text-align: right;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+.sa-orch-asterion-input-row {
+    display: flex;
+    gap: 8px;
+    padding: 10px 14px;
+    border-top: 1px solid #2a2a33;
+    background: #1a1a22;
+}
+
+.sa-orch-asterion-input {
+    flex: 1;
+    background: #0e0e14;
+    color: #e8e8ea;
+    border: 1px solid #3a3a45;
+    border-radius: 4px;
+    padding: 6px 8px;
+    font-family: inherit;
+    font-size: 12.5px;
+    resize: vertical;
+}
+
+.sa-orch-asterion-input:focus {
+    outline: none;
+    border-color: #6a6a75;
+}
+
+.sa-orch-asterion-send {
+    background: #2a2a35;
+    color: #e8e8ea;
+    border: 1px solid #4a4a55;
+    border-radius: 4px;
+    padding: 0 14px;
+    cursor: pointer;
+    font-weight: 600;
+    font-size: 12px;
+}
+
+.sa-orch-asterion-send:hover:not(:disabled) {
+    background: #353541;
+}
+
+.sa-orch-asterion-send:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+.sa-orch-asterion-status {
+    padding: 4px 14px;
+    font-size: 11px;
+    color: #8a8a95;
+    min-height: 16px;
+    background: #15151c;
+}

sa-orchestration/assets/asterion-bubble.js

@@ -0,0 +1,237 @@
+/**
+ * Asterion Projection — floating canonical-query button.
+ * Board #30.
+ *
+ * Sister surface to sara-bubble.js. Distinct identity:
+ *   - top-right corner (Sara is bottom-right; Attention is bottom-left)
+ *   - stone glyph (◾) for "south pole / foundation"
+ *   - librarian tone, citation-grounded responses
+ *   - reads URL ?file= when on Asterion explorer page (single-file scope)
+ *   - no draft / no insert / no advice — only canonical answers
+ *
+ * No DB writes. No mutation. POST /sa-orch/v1/asterion/query round-trip only.
+ */
+(function () {
+    'use strict';
+
+    if (typeof window.SA_ORCH_ASTERION === 'undefined') return;
+    var cfg = window.SA_ORCH_ASTERION;
+
+    var root, button, panel, input, sendBtn, contextLabel, statusLine, answerEl, citationsEl;
+    var conversationContainer;
+    var isOpen = false;
+    var inFlight = false;
+
+    function createEl(tag, attrs, text) {
+        var el = document.createElement(tag);
+        if (attrs) {
+            for (var k in attrs) {
+                if (k === 'style') {
+                    for (var s in attrs.style) el.style[s] = attrs.style[s];
+                } else if (k === 'class') {
+                    el.className = attrs[k];
+                } else {
+                    el.setAttribute(k, attrs[k]);
+                }
+            }
+        }
+        if (text !== undefined) el.textContent = text;
+        return el;
+    }
+
+    function getBoundFile() {
+        if (cfg.page !== 'sa-orchestration-asterion') return '';
+        if (typeof URLSearchParams === 'undefined') return '';
+        return new URLSearchParams(window.location.search).get('file') || '';
+    }
+
+    function contextLabelText() {
+        var f = getBoundFile();
+        if (f) return 'canonical: ' + f;
+        if (cfg.page === 'sa-orchestration-asterion') return 'canonical: spec corpus (no file bound)';
+        return 'canonical: spec corpus';
+    }
+
+    function buildUI() {
+        root = createEl('div', { id: 'sa-orch-asterion-root' });
+
+        button = createEl('button', {
+            id: 'sa-orch-asterion-button',
+            type: 'button',
+            'aria-label': 'Ask Asterion (canonical librarian)',
+            title: 'Ask Asterion'
+        });
+        button.innerHTML = '<span class="sa-orch-asterion-glyph">◾</span>';
+        button.addEventListener('click', toggle);
+
+        panel = createEl('div', { id: 'sa-orch-asterion-panel', 'aria-hidden': 'true' });
+
+        var header = createEl('div', { class: 'sa-orch-asterion-header' });
+        var title  = createEl('div', { class: 'sa-orch-asterion-title' }, 'Asterion');
+        var subtitle = createEl('div', { class: 'sa-orch-asterion-subtitle' },
+            'canonical librarian · cite-only · no speculation');
+        var closeBtn = createEl('button', {
+            class: 'sa-orch-asterion-close',
+            type: 'button',
+            'aria-label': 'Close'
+        }, '×');
+        closeBtn.addEventListener('click', toggle);
+        header.appendChild(title);
+        header.appendChild(subtitle);
+        header.appendChild(closeBtn);
+
+        contextLabel = createEl('div', { class: 'sa-orch-asterion-context' }, contextLabelText());
+
+        conversationContainer = createEl('div', { class: 'sa-orch-asterion-conv' });
+        var hint = createEl('div', { class: 'sa-orch-asterion-hint' },
+            'Ask a question about the spec corpus. If the answer is not in the corpus, Asterion will say so.');
+        conversationContainer.appendChild(hint);
+
+        var inputRow = createEl('div', { class: 'sa-orch-asterion-input-row' });
+        input = createEl('textarea', {
+            class: 'sa-orch-asterion-input',
+            placeholder: 'Ask Asterion (e.g. "what is Truth Class?")',
+            rows: '2'
+        });
+        input.addEventListener('keydown', function (e) {
+            if (e.key === 'Enter' && !e.shiftKey) {
+                e.preventDefault();
+                send();
+            }
+        });
+        sendBtn = createEl('button', {
+            class: 'sa-orch-asterion-send',
+            type: 'button'
+        }, 'Ask');
+        sendBtn.addEventListener('click', send);
+        inputRow.appendChild(input);
+        inputRow.appendChild(sendBtn);
+
+        statusLine = createEl('div', { class: 'sa-orch-asterion-status' }, '');
+
+        panel.appendChild(header);
+        panel.appendChild(contextLabel);
+        panel.appendChild(conversationContainer);
+        panel.appendChild(inputRow);
+        panel.appendChild(statusLine);
+
+        root.appendChild(button);
+        root.appendChild(panel);
+        document.body.appendChild(root);
+    }
+
+    function toggle() {
+        isOpen = !isOpen;
+        if (isOpen) {
+            panel.classList.add('open');
+            panel.setAttribute('aria-hidden', 'false');
+            contextLabel.textContent = contextLabelText();
+            setTimeout(function () { input.focus(); }, 50);
+        } else {
+            panel.classList.remove('open');
+            panel.setAttribute('aria-hidden', 'true');
+        }
+    }
+
+    function appendQA(question, result) {
+        var block = createEl('div', { class: 'sa-orch-asterion-qa' });
+
+        var q = createEl('div', { class: 'sa-orch-asterion-q' }, question);
+        block.appendChild(q);
+
+        var a = createEl('div', { class: 'sa-orch-asterion-a' });
+        a.textContent = (result && result.answer) ? result.answer : '(empty)';
+        block.appendChild(a);
+
+        if (result && Array.isArray(result.citations) && result.citations.length > 0) {
+            var cites = createEl('div', { class: 'sa-orch-asterion-cites' });
+            var lbl = createEl('div', { class: 'sa-orch-asterion-cites-label' }, 'CITATIONS');
+            cites.appendChild(lbl);
+            result.citations.forEach(function (c, i) {
+                var row = createEl('div', { class: 'sa-orch-asterion-cite' });
+                var fileEl = createEl('div', { class: 'sa-orch-asterion-cite-file' },
+                    '[' + (i + 1) + '] ' + (c.file || ''));
+                var excEl = createEl('div', { class: 'sa-orch-asterion-cite-excerpt' },
+                    c.excerpt || '');
+                row.appendChild(fileEl);
+                row.appendChild(excEl);
+                cites.appendChild(row);
+            });
+            block.appendChild(cites);
+        }
+
+        if (result && result.scope) {
+            var scope = createEl('div', { class: 'sa-orch-asterion-scope' },
+                'scope: ' + result.scope);
+            block.appendChild(scope);
+        }
+
+        // Clear hint on first response
+        var hint = conversationContainer.querySelector('.sa-orch-asterion-hint');
+        if (hint) hint.remove();
+
+        conversationContainer.appendChild(block);
+        conversationContainer.scrollTop = conversationContainer.scrollHeight;
+    }
+
+    function send() {
+        if (inFlight) return;
+        var q = (input.value || '').trim();
+        if (!q) return;
+
+        inFlight = true;
+        sendBtn.disabled = true;
+        statusLine.textContent = 'querying canonical corpus…';
+        input.value = '';
+
+        var body = {
+            query: q,
+            asterion_file: getBoundFile()
+        };
+
+        fetch(cfg.rest_url, {
+            method: 'POST',
+            credentials: 'same-origin',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-WP-Nonce': cfg.nonce
+            },
+            body: JSON.stringify(body)
+        })
+            .then(function (resp) {
+                return resp.json().then(function (data) {
+                    return { ok: resp.ok, status: resp.status, data: data };
+                });
+            })
+            .then(function (r) {
+                if (!r.ok) {
+                    appendQA(q, {
+                        answer: 'Asterion error: ' + (r.data && r.data.message ? r.data.message : ('HTTP ' + r.status)),
+                        citations: [],
+                        scope: 'error'
+                    });
+                } else {
+                    appendQA(q, r.data);
+                }
+            })
+            .catch(function (err) {
+                appendQA(q, {
+                    answer: 'Asterion network error: ' + (err && err.message ? err.message : err),
+                    citations: [],
+                    scope: 'error'
+                });
+            })
+            .then(function () {
+                inFlight = false;
+                sendBtn.disabled = false;
+                statusLine.textContent = '';
+                input.focus();
+            });
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', buildUI);
+    } else {
+        buildUI();
+    }
+})();

sa-orchestration/assets/attention-bridge.js

@@ -0,0 +1,263 @@
+/**
+ * Attention Bridge — emit-only frontend (Board #21)
+ *
+ * Floating button (bottom-left, distinct from Sara's bottom-right) that lets
+ * the admin user emit a structured attention packet to the configured
+ * oversight URL. User-triggered ONLY — no auto-emission. Confirms the
+ * payload before POSTing.
+ *
+ * Per locked doctrine:
+ *   - Sara does NOT emit. This is its own surface.
+ *   - User decides. Always.
+ *   - The button label shows what would be emitted, so the user knows
+ *     before they click.
+ */
+(function () {
+    'use strict';
+
+    if (typeof window.SA_ORCH_ATTENTION === 'undefined') return;
+    var cfg = window.SA_ORCH_ATTENTION;
+
+    // ----- Context resolver (parallel to Sara's, kept independent) -----
+    var REF_PATTERNS = {
+        'fluent-support': /^ticket#\d+$/,
+        'fluent-boards':  /^task#\d+$/,
+        'fluentcrm':      /^subscriber#\d+$/,
+        'derived':        /^derived#[A-Za-z0-9_\-]+$/
+    };
+
+    function isValidSurfaceRef(surface, ref) {
+        if (!surface || !ref) return false;
+        if (!REF_PATTERNS.hasOwnProperty(surface)) return false;
+        return REF_PATTERNS[surface].test(ref);
+    }
+
+    function resolveContext() {
+        var page = cfg.page || '';
+        var hash = window.location.hash || '';
+
+        if (page === 'fluent-boards') {
+            var m = hash.match(/^#\/boards\/\d+\/tasks\/(\d+)/);
+            if (m) return { surface: 'fluent-boards', ref: 'task#' + m[1] };
+        }
+        if (page === 'fluent-support') {
+            var m2 = hash.match(/^#\/tickets\/(\d+)/);
+            if (m2) return { surface: 'fluent-support', ref: 'ticket#' + m2[1] };
+        }
+        if (page && page.indexOf('sa-orchestration') === 0 && typeof URLSearchParams !== 'undefined') {
+            var params = new URLSearchParams(window.location.search);
+            var s = params.get('demand_surface');
+            var r = params.get('demand_ref');
+            if (s && r && isValidSurfaceRef(s, r)) return { surface: s, ref: r };
+        }
+        return null;
+    }
+
+    // ----- DOM -----
+    var root, button, devButton, status;
+
+    function build() {
+        root = document.createElement('div');
+        root.id = 'sa-orch-attention-root';
+        root.setAttribute('style',
+            'position:fixed;bottom:24px;left:24px;z-index:99998;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;display:flex;flex-direction:column;align-items:flex-start;gap:6px;'
+        );
+
+        button = document.createElement('button');
+        button.id = 'sa-orch-attention-button';
+        button.type = 'button';
+        button.setAttribute('style',
+            'background:#2271b1;color:#fff;border:none;padding:10px 14px;border-radius:6px;cursor:pointer;font-size:13px;font-weight:600;box-shadow:0 2px 8px rgba(0,0,0,0.18);display:flex;align-items:center;gap:8px;'
+        );
+        button.addEventListener('mouseenter', function () { button.style.background = '#135e96'; });
+        button.addEventListener('mouseleave', function () { button.style.background = '#2271b1'; });
+        button.addEventListener('click', function () { onSendClick('default'); });
+
+        // Board #21 dev verification — second button only renders when
+        // SA_Orch_Env::is_local_or_dev() returned true on the server side.
+        // Production never sees this flag, so this button never appears in prod.
+        if (cfg.is_dev) {
+            devButton = document.createElement('button');
+            devButton.id = 'sa-orch-attention-dev-mock-button';
+            devButton.type = 'button';
+            devButton.setAttribute('style',
+                'background:#fff;color:#2271b1;border:1px dashed #2271b1;padding:6px 10px;border-radius:6px;cursor:pointer;font-size:11px;font-weight:600;display:flex;align-items:center;gap:6px;opacity:0.95;'
+            );
+            devButton.textContent = '\u{1F9EA} Dev: Send to mock receiver (200)';
+            devButton.title = 'Dev-only — emits to a local mock REST endpoint that returns HTTP 200. Verifies the success path without a real oversight site.';
+            devButton.addEventListener('click', function () { onSendClick('success_mock'); });
+        }
+
+        status = document.createElement('div');
+        status.id = 'sa-orch-attention-status';
+        status.setAttribute('style',
+            'max-width:380px;padding:8px 12px;border-radius:4px;font-size:12px;display:none;'
+        );
+
+        root.appendChild(button);
+        if (devButton) root.appendChild(devButton);
+        root.appendChild(status);
+        document.body.appendChild(root);
+
+        updateLabel();
+
+        // Surface reliability — Board #24 parallel safety.
+        // Re-mount + label refresh on either SPA navigation event. Identical
+        // pattern to Sara's bubble; no Attention behavior change beyond
+        // ensuring the button stays present and its label tracks context.
+        window.addEventListener('hashchange', function () {
+            ensureMounted();
+            updateLabel();
+        });
+        window.addEventListener('popstate',   function () {
+            ensureMounted();
+            updateLabel();
+        });
+        ensureMounted();
+    }
+
+    // Re-attach Attention's root to document.body if SPA navigation removed it.
+    function ensureMounted() {
+        if (root && !document.body.contains(root)) {
+            document.body.appendChild(root);
+        }
+    }
+
+    function updateLabel() {
+        var ctx = resolveContext();
+        var dot = '\u{1F4E1}'; // 📡
+        if (ctx) {
+            button.textContent = dot + ' Send Attention: ' + ctx.surface + ' / ' + ctx.ref;
+        } else {
+            var pageLabel = cfg.page ? cfg.page : 'page';
+            button.textContent = dot + ' Send Attention: ' + pageLabel + ' (no item bound)';
+        }
+    }
+
+    function showStatus(msg, kind) {
+        // kind: 'ok' | 'err' | 'info'
+        var bg = '#f0f0f1', color = '#1d2327', border = '#c3c4c7';
+        if (kind === 'ok')  { bg = '#edf7ed'; color = '#1e4620'; border = '#5fb56f'; }
+        if (kind === 'err') { bg = '#fcf0f1'; color = '#7a1f23'; border = '#d63638'; }
+        status.style.background = bg;
+        status.style.color      = color;
+        status.style.border     = '1px solid ' + border;
+        status.textContent      = msg;
+        status.style.display    = 'block';
+    }
+
+    function clearStatus() {
+        status.style.display = 'none';
+        status.textContent  = '';
+    }
+
+    function onSendClick(mode) {
+        // mode: 'default' (configured / dev failure scaffold) | 'success_mock' (dev-only)
+        mode = mode || 'default';
+        var modeLabel = mode === 'success_mock' ? 'dev success mock' : 'configured';
+
+        if (!cfg.configured) {
+            showStatus(
+                'Attention Bridge is not configured. Define SA_SITE_ID, SA_ATTENTION_TARGET_URL, and SA_ATTENTION_TOKEN in wp-config.php.',
+                'err'
+            );
+            return;
+        }
+
+        var ctx = resolveContext();
+        var payload = {
+            site_id: cfg.site_id || '(unset)',
+            page:    cfg.page || null,
+            surface: ctx ? ctx.surface : null,
+            ref:     ctx ? ctx.ref     : null
+        };
+
+        var modeLine = mode === 'success_mock'
+            ? 'Mode: dev success mock (HTTP 200 expected — local mock receiver)\n\n'
+            : '';
+        var preview = modeLine + 'Emit this attention packet?\n\n' + JSON.stringify(payload, null, 2);
+        if (!window.confirm(preview)) {
+            return;
+        }
+
+        var clickedButton  = mode === 'success_mock' && devButton ? devButton : button;
+        var originalText   = clickedButton.textContent;
+        button.disabled    = true;
+        if (devButton) devButton.disabled = true;
+        clickedButton.textContent = '\u{1F4E1} Sending…';
+        clearStatus();
+
+        var body = {
+            page: cfg.page || '',
+            mode: mode
+        };
+        if (ctx) {
+            body.surface = ctx.surface;
+            body.ref     = ctx.ref;
+        }
+
+        fetch(cfg.rest_url, {
+            method: 'POST',
+            credentials: 'same-origin',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-WP-Nonce':   cfg.nonce
+            },
+            body: JSON.stringify(body)
+        })
+        .then(function (r) { return r.json().then(function (j) { return { ok: r.ok, json: j }; }); })
+        .then(function (result) {
+            button.disabled = false;
+            if (devButton) devButton.disabled = false;
+            updateLabel();
+            if (devButton && clickedButton === devButton) {
+                devButton.textContent = '\u{1F9EA} Dev: Send to mock receiver (200)';
+            }
+
+            // Use the server-reported mode_label when present (server is the source
+            // of truth — production silently downgrades success_mock to configured).
+            var serverLabel = (result.json && result.json.mode_label) || modeLabel;
+            var modeAnnot = ' [' + serverLabel + ']';
+
+            // Distinguish "attempt was made" from "receiver accepted it".
+            // status semantics (Board #21 rev2):
+            //   success — HTTP 2xx received; receiver accepted the packet
+            //   failed  — transport error OR non-2xx HTTP; packet did not arrive cleanly
+            //   (no log row at all if config is missing — error returned before any I/O)
+            if (result.ok && result.json && result.json.ok && result.json.status === 'success') {
+                showStatus(
+                    'status=success' + modeAnnot + ' — HTTP ' + result.json.http_status + '. Receiver accepted the packet. Log id #' + result.json.log_id + '.',
+                    'ok'
+                );
+            } else if (result.json && result.json.code === 'attention_config_missing') {
+                // No log row created in this case (validation precedes emission).
+                showStatus(result.json.message || 'Configuration missing.', 'err');
+            } else if (result.json && result.json.status === 'failed' && result.json.error_message) {
+                showStatus(
+                    'status=failed' + modeAnnot + ' — transport error: ' + result.json.error_message + ' (log id #' + result.json.log_id + '). The packet was NOT received.',
+                    'err'
+                );
+            } else if (result.json && result.json.status === 'failed' && result.json.http_status) {
+                showStatus(
+                    'status=failed' + modeAnnot + ' — receiver returned HTTP ' + result.json.http_status + ' (log id #' + result.json.log_id + '). The packet was NOT accepted.',
+                    'err'
+                );
+            } else {
+                var msg = (result.json && (result.json.message || JSON.stringify(result.json))) || 'unknown error';
+                showStatus('Emit failed' + modeAnnot + ': ' + msg, 'err');
+            }
+        })
+        .catch(function (err) {
+            button.disabled = false;
+            if (devButton) devButton.disabled = false;
+            clickedButton.textContent = originalText;
+            showStatus('Network error: ' + (err && err.message ? err.message : String(err)), 'err');
+        });
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', build);
+    } else {
+        build();
+    }
+})();

sa-orchestration/assets/sara-bubble.css

@@ -0,0 +1,304 @@
+/* Sara — Invocation + Context Resolver + Response Layer
+   Conversation-style bubble: persistent panel size, scrolling thread,
+   never resets between prompts. Read-only against the system; outputs
+   are non-binding drafts.
+*/
+
+#sa-orch-sara-root {
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    z-index: 99999;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+
+#sa-orch-sara-button {
+    background: #1d2327;
+    color: #fff;
+    border: none;
+    border-radius: 50px;
+    padding: 12px 20px;
+    cursor: pointer;
+    font-size: 14px;
+    font-weight: 600;
+    box-shadow: 0 2px 12px rgba(0, 0, 0, 0.2);
+    transition: transform 0.1s ease, box-shadow 0.1s ease;
+}
+
+#sa-orch-sara-button:hover {
+    transform: translateY(-1px);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
+}
+
+#sa-orch-sara-button:focus {
+    outline: 2px solid #2271b1;
+    outline-offset: 2px;
+}
+
+/* Panel: fixed dimensions; doesn't shrink/grow with content. Inner
+   conversation area is what scrolls. */
+#sa-orch-sara-panel {
+    display: none;
+    position: absolute;
+    bottom: 56px;
+    right: 0;
+    width: 440px;
+    height: 600px;
+    background: #fff;
+    border: 1px solid #c3c4c7;
+    border-radius: 6px;
+    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.15);
+    padding: 12px;
+    box-sizing: border-box;
+    flex-direction: column;
+}
+
+#sa-orch-sara-panel.open {
+    display: flex;
+}
+
+.sa-orch-sara-header {
+    font-size: 14px;
+    margin-bottom: 6px;
+    color: #1d2327;
+    flex-shrink: 0;
+}
+
+.sa-orch-sara-tag {
+    font-size: 11px;
+    color: #50575e;
+    background: #f0f0f1;
+    padding: 1px 6px;
+    border-radius: 3px;
+    margin-left: 6px;
+    font-weight: normal;
+}
+
+.sa-orch-sara-context {
+    font-size: 11px;
+    color: #50575e;
+    margin-bottom: 8px;
+    padding: 4px 8px;
+    background: #f6f7f7;
+    border-radius: 3px;
+    font-family: ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+    flex-shrink: 0;
+}
+
+/* Conversation thread: takes remaining space, scrolls */
+.sa-orch-sara-conversation {
+    flex: 1 1 auto;
+    overflow-y: auto;
+    border: 1px solid #f0f0f1;
+    border-radius: 3px;
+    padding: 8px;
+    background: #fafbfc;
+    margin-bottom: 8px;
+    min-height: 0; /* lets flex item shrink properly inside flex column */
+}
+
+.sa-orch-sara-conversation:empty::before {
+    content: 'No conversation yet. Type a prompt below to start.';
+    color: #8c8f94;
+    font-size: 12px;
+    font-style: italic;
+}
+
+/* A turn = user message + Sara response */
+.sa-orch-sara-turn {
+    margin-bottom: 14px;
+    padding-bottom: 14px;
+    border-bottom: 1px dashed #dcdcde;
+}
+.sa-orch-sara-turn:last-child {
+    border-bottom: none;
+    margin-bottom: 0;
+    padding-bottom: 0;
+}
+
+.sa-orch-sara-msg-label {
+    font-size: 10px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: #50575e;
+    margin-bottom: 3px;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+}
+
+.sa-orch-sara-not-saved {
+    background: #fff2c2;
+    color: #7a5b00;
+    border: 1px solid #c9a300;
+    padding: 1px 6px;
+    border-radius: 3px;
+    font-size: 9px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+}
+
+.sa-orch-sara-user-msg {
+    margin-bottom: 8px;
+    padding: 6px 10px;
+    background: #eef4fa;
+    border-left: 3px solid #2271b1;
+    border-radius: 3px;
+}
+.sa-orch-sara-user-msg .sa-orch-sara-msg-body {
+    font-size: 13px;
+    color: #1d2327;
+    white-space: pre-wrap;
+    user-select: text;
+}
+
+.sa-orch-sara-assistant-msg {
+    padding: 0;
+}
+
+.sa-orch-sara-section {
+    margin-bottom: 6px;
+}
+.sa-orch-sara-section:last-child {
+    margin-bottom: 0;
+}
+
+.sa-orch-sara-section-header {
+    font-size: 10px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: #50575e;
+    margin-bottom: 2px;
+}
+
+.sa-orch-sara-section-body {
+    padding: 6px 10px;
+    background: #f6f7f7;
+    border-left: 3px solid #1d2327;
+    border-radius: 3px;
+    font-size: 13px;
+    line-height: 1.45;
+    white-space: pre-wrap;
+    color: #1d2327;
+    user-select: text;
+}
+
+/* Notes section (last in a Sara block) gets a different accent */
+.sa-orch-sara-assistant-msg .sa-orch-sara-section:last-child .sa-orch-sara-section-body {
+    border-left-color: #c9a300;
+    background: #fcf9e8;
+    font-size: 12px;
+}
+
+#sa-orch-sara-panel textarea {
+    width: 100%;
+    padding: 8px;
+    border: 1px solid #c3c4c7;
+    border-radius: 3px;
+    font-size: 13px;
+    font-family: inherit;
+    box-sizing: border-box;
+    resize: vertical;
+    flex-shrink: 0;
+}
+
+.sa-orch-sara-send {
+    margin-top: 6px;
+    background: #2271b1;
+    color: #fff;
+    border: none;
+    border-radius: 3px;
+    padding: 6px 14px;
+    cursor: pointer;
+    font-size: 13px;
+    flex-shrink: 0;
+}
+
+.sa-orch-sara-send:hover {
+    background: #135e96;
+}
+
+.sa-orch-sara-send:disabled {
+    background: #8c8f94;
+    cursor: not-allowed;
+}
+
+.sa-orch-sara-status {
+    margin-top: 6px;
+    padding: 6px 10px;
+    background: #fcf9e8;
+    border-left: 3px solid #c9a300;
+    border-radius: 3px;
+    font-size: 11px;
+    color: #50575e;
+    font-style: italic;
+    flex-shrink: 0;
+}
+
+.sa-orch-sara-actions {
+    margin-top: 6px;
+    display: flex;
+    gap: 6px;
+    flex-wrap: wrap;
+    flex-shrink: 0;
+}
+
+.sa-orch-sara-actions button {
+    background: #f6f7f7;
+    color: #1d2327;
+    border: 1px solid #c3c4c7;
+    border-radius: 3px;
+    padding: 4px 10px;
+    cursor: pointer;
+    font-size: 12px;
+}
+
+.sa-orch-sara-actions button:hover {
+    background: #fff;
+    border-color: #8c8f94;
+}
+
+/* Board #15 — Draft Assist: warning + inline insert message */
+.sa-orch-sara-insert-warning {
+    margin-top: 6px;
+    padding: 5px 10px;
+    background: #fcf9e8;
+    border-left: 3px solid #c9a300;
+    border-radius: 3px;
+    font-size: 11px;
+    color: #7a5b00;
+    flex-shrink: 0;
+}
+
+.sa-orch-sara-insert {
+    background: #1d2327 !important;
+    color: #fff !important;
+    border-color: #1d2327 !important;
+}
+
+.sa-orch-sara-insert:hover {
+    background: #2c3338 !important;
+}
+
+.sa-orch-sara-insert-message {
+    margin-top: 4px;
+    padding: 4px 10px;
+    background: #f6f7f7;
+    border-radius: 3px;
+    font-size: 11px;
+    color: #50575e;
+    font-style: italic;
+    flex-shrink: 0;
+}
+
+.sa-orch-sara-usage {
+    margin-top: 8px;
+    padding-top: 6px;
+    border-top: 1px dashed #dcdcde;
+    font-size: 11px;
+    color: #646970;
+    font-family: Consolas, Monaco, monospace;
+}

sa-orchestration/assets/sara-bubble.js

@@ -0,0 +1,560 @@
+/**
+ * Sara — Invocation + Context Resolver + Response Layer
+ *        (Boards #12, #13, #14)
+ *
+ * Floating button + panel. Detects surface + ref from URL hash. Maintains
+ * a session-local conversation history (JS memory only — gone on page
+ * reload; never persisted to DB or Asterion). Renders responses as a
+ * scrolling conversation, not a single output that resets per turn.
+ *
+ * Per the locked Control Rule:
+ *   Sara outputs are non-binding.
+ *   Only human-initiated actions trigger writes.
+ *
+ * Per Acceptance Boundary Rule:
+ *   No DB writes. No Asterion writes. No demand registration. No auto-post.
+ *
+ * Insert is intentionally NOT in this Board — it ships in Board #15
+ * (Draft Assist).
+ */
+(function () {
+    'use strict';
+
+    if (typeof window.SA_ORCH_SARA === 'undefined') return;
+    var cfg = window.SA_ORCH_SARA;
+
+    // ----- Session-local state -----
+    // Conversation history: closed turns only (each user prompt followed by
+    // an assistant response). Lives in module memory; resets on page reload.
+    // Not persisted anywhere.
+    var conversationHistory = [];
+    var lastDraft = '';
+
+    // Token usage counters (Board #16). Session-only; reset on page reload.
+    // Server-side audit is in wp_sa_token_log (separate concern: cross-session
+    // attribution for Board #23's hook). These counters are UI-only.
+    var sessionTokens = { prompt: 0, completion: 0, total: 0 };
+
+    function fmtNumber(n) {
+        try { return Number(n).toLocaleString(); } catch (e) { return String(n || 0); }
+    }
+
+    // Last valid input target tracked from focusin events. Used by the Insert
+    // button (Board #15). Captured live; re-evaluated on every focus change.
+    // Excludes Sara's own panel inputs.
+    var lastValidField = null;
+
+    // ----- Strict Demand-binding context resolver (Board #13) -----
+    //
+    // Resolution order:
+    //   1. fluent-boards page + #/boards/N/tasks/M hash  → fluent-boards / task#M
+    //   2. fluent-support page + #/tickets/N hash        → fluent-support / ticket#N
+    //   3. sa-orchestration* page + ?demand_surface=...&demand_ref=...
+    //      query params (closed-vocabulary surface + per-surface ref pattern
+    //      validated)                                    → that surface / ref
+    //   4. otherwise null (page-level fallback applies in backend user_prompt)
+    var REF_PATTERNS = {
+        'fluent-support': /^ticket#\d+$/,
+        'fluent-boards':  /^task#\d+$/,
+        'fluentcrm':      /^subscriber#\d+$/,
+        'derived':        /^derived#[A-Za-z0-9_\-]+$/
+    };
+
+    function isValidSurfaceRef(surface, ref) {
+        if (!surface || !ref) return false;
+        if (!REF_PATTERNS.hasOwnProperty(surface)) return false;
+        return REF_PATTERNS[surface].test(ref);
+    }
+
+    function resolveContext() {
+        var page = cfg.page || '';
+        var hash = window.location.hash || '';
+
+        if (page === 'fluent-boards') {
+            var m = hash.match(/^#\/boards\/\d+\/tasks\/(\d+)/);
+            if (m) {
+                return { surface: 'fluent-boards', ref: 'task#' + m[1] };
+            }
+        }
+
+        if (page === 'fluent-support') {
+            var m2 = hash.match(/^#\/tickets\/(\d+)/);
+            if (m2) {
+                return { surface: 'fluent-support', ref: 'ticket#' + m2[1] };
+            }
+        }
+
+        // SA-Orchestration Demand Trace pages carry demand_surface + demand_ref
+        // as URL query params (e.g. admin.php?page=sa-orchestration&demand_surface=fluent-boards&demand_ref=task%231019).
+        // URLSearchParams auto-decodes %23 → #.
+        if (page && page.indexOf('sa-orchestration') === 0 && typeof URLSearchParams !== 'undefined') {
+            var params = new URLSearchParams(window.location.search);
+            var s = params.get('demand_surface');
+            var r = params.get('demand_ref');
+            if (s && r && isValidSurfaceRef(s, r)) {
+                return { surface: s, ref: r };
+            }
+        }
+
+        return null;
+    }
+
+    // ----- DOM construction -----
+    var root, button, panel, input, sendBtn, contextLabel, statusLine;
+    var conversationContainer, copyBtn;
+    // Board #15 — Draft Assist additions
+    var insertBtn, insertWarning, insertMessage;
+
+    // ----- Focus tracking helpers (Board #15) -----
+    function isValidInsertTarget(el) {
+        if (!el) return false;
+        if (el === input) return false;             // exclude Sara's own prompt textarea
+        if (el === insertBtn) return false;         // exclude the insert button itself
+        if (el.tagName === 'TEXTAREA') return true;
+        if (el.tagName === 'INPUT') {
+            var t = (el.getAttribute('type') || 'text').toLowerCase();
+            return t === 'text';
+        }
+        return false;
+    }
+
+    function updateInsertVisibility() {
+        if (!insertBtn || !insertWarning) return;
+        var draftReady   = lastDraft && String(lastDraft).trim() !== '';
+        var fieldFocused = isValidInsertTarget(document.activeElement);
+        var show = draftReady && fieldFocused;
+
+        insertBtn.style.display     = show ? 'inline-block' : 'none';
+        insertWarning.style.display = show ? 'block'        : 'none';
+
+        // If a valid field is currently focused, capture it for the click handler.
+        if (fieldFocused) {
+            lastValidField = document.activeElement;
+        }
+    }
+
+    // Insert text at the field's cursor position, without dispatching events.
+    // Returns true on success, false otherwise.
+    function insertAtCursor(field, text) {
+        if (!field || !text) return false;
+        if (field.tagName === 'TEXTAREA' || field.tagName === 'INPUT') {
+            var current = field.value || '';
+            var start   = field.selectionStart;
+            var end     = field.selectionEnd;
+            if (typeof start === 'number' && typeof end === 'number') {
+                field.value = current.substring(0, start) + text + current.substring(end);
+                var newPos = start + text.length;
+                try { field.setSelectionRange(newPos, newPos); } catch (e) { /* some inputs don't support */ }
+            } else {
+                field.value = current + text;
+            }
+            // Per spec: do NOT dispatch change/input/submit events. The host form's
+            // state will not auto-update; the user must interact with the field
+            // afterward to flush. This is a deliberate constraint.
+            return true;
+        }
+        return false;
+    }
+
+    function build() {
+        root = document.createElement('div');
+        root.id = 'sa-orch-sara-root';
+
+        button = document.createElement('button');
+        button.id = 'sa-orch-sara-button';
+        button.setAttribute('aria-label', 'Open Sara');
+        button.textContent = 'Sara';
+        button.addEventListener('click', togglePanel);
+
+        panel = document.createElement('div');
+        panel.id = 'sa-orch-sara-panel';
+        panel.setAttribute('aria-hidden', 'true');
+
+        var header = document.createElement('div');
+        header.className = 'sa-orch-sara-header';
+        header.innerHTML = '<strong>Sara</strong> <span class="sa-orch-sara-tag">non-binding draft surface</span>';
+
+        contextLabel = document.createElement('div');
+        contextLabel.className = 'sa-orch-sara-context';
+        contextLabel.textContent = 'context: detecting...';
+
+        // Conversation thread: scrollable container that grows with each turn
+        conversationContainer = document.createElement('div');
+        conversationContainer.className = 'sa-orch-sara-conversation';
+
+        statusLine = document.createElement('div');
+        statusLine.className = 'sa-orch-sara-status';
+        statusLine.style.display = 'none';
+
+        input = document.createElement('textarea');
+        input.placeholder = 'What do you need?';
+        input.rows = 3;
+        input.addEventListener('keydown', function (e) {
+            // Ctrl/Cmd + Enter sends
+            if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') {
+                e.preventDefault();
+                send();
+            }
+        });
+
+        sendBtn = document.createElement('button');
+        sendBtn.className = 'sa-orch-sara-send';
+        sendBtn.textContent = 'Send';
+        sendBtn.addEventListener('click', send);
+
+        copyBtn = document.createElement('button');
+        copyBtn.className = 'sa-orch-sara-copy';
+        copyBtn.textContent = 'Copy latest draft';
+        copyBtn.style.display = 'none';
+        copyBtn.addEventListener('click', copyDraft);
+
+        // Board #15 — Draft Assist UI
+        // Warning text appears directly above the Insert button. Both gated on
+        // (draft non-empty) AND (a valid input field currently focused).
+        insertWarning = document.createElement('div');
+        insertWarning.className = 'sa-orch-sara-insert-warning';
+        insertWarning.textContent = 'You are about to insert this into the current field';
+        insertWarning.style.display = 'none';
+
+        insertBtn = document.createElement('button');
+        insertBtn.className = 'sa-orch-sara-insert';
+        insertBtn.textContent = 'Insert into active field';
+        insertBtn.style.display = 'none';
+
+        // mousedown preventDefault keeps focus on the textarea so document.activeElement
+        // is still the user's target field at click-time. No event dispatch.
+        insertBtn.addEventListener('mousedown', function (e) { e.preventDefault(); });
+        insertBtn.addEventListener('click', insertDraft);
+
+        insertMessage = document.createElement('div');
+        insertMessage.className = 'sa-orch-sara-insert-message';
+        insertMessage.style.display = 'none';
+
+        var actions = document.createElement('div');
+        actions.className = 'sa-orch-sara-actions';
+        actions.appendChild(copyBtn);
+        actions.appendChild(insertBtn);
+
+        panel.appendChild(header);
+        panel.appendChild(contextLabel);
+        panel.appendChild(conversationContainer);
+        panel.appendChild(statusLine);
+        panel.appendChild(input);
+        panel.appendChild(sendBtn);
+        panel.appendChild(insertWarning);
+        panel.appendChild(actions);
+        panel.appendChild(insertMessage);
+
+        root.appendChild(button);
+        root.appendChild(panel);
+        document.body.appendChild(root);
+
+        updateContextLabel();
+
+        // Surface reliability — Board #24.
+        //
+        // Listen on BOTH hashchange (Fluent's hash-routed SPA) and popstate
+        // (history.pushState navigation, used by some Fluent flows). Either
+        // event indicates the user moved to a different task/ticket; we
+        // refresh the context label so the panel header reflects reality.
+        // resolveContext() is also re-called at send() time, so even if
+        // these listeners somehow miss an update, the actual outbound
+        // request still carries current context.
+        window.addEventListener('hashchange', function () {
+            ensureMounted();
+            updateContextLabel();
+        });
+        window.addEventListener('popstate',   function () {
+            ensureMounted();
+            updateContextLabel();
+        });
+
+        // Defensive re-mount: if Fluent's SPA (or any other code) removes
+        // Sara's root from document.body during navigation, put it back.
+        // Lightweight check — runs only on hash/popstate, not on every DOM
+        // mutation. Idempotent: if root is still mounted, this is a no-op.
+        ensureMounted();
+
+        // Focus tracking — re-evaluate Insert visibility on every focus change.
+        // Captures the user's currently-focused valid field so the click handler
+        // can act on it.
+        document.addEventListener('focusin',  updateInsertVisibility);
+        document.addEventListener('focusout', function () {
+            // Defer one tick so document.activeElement reflects the new target
+            setTimeout(updateInsertVisibility, 0);
+        });
+    }
+
+    // Re-attach Sara's root to document.body if SPA navigation removed it.
+    // Cheap, idempotent. document.body.contains(root) is a fast DOM query.
+    function ensureMounted() {
+        if (root && !document.body.contains(root)) {
+            document.body.appendChild(root);
+        }
+    }
+
+    function updateContextLabel() {
+        if (!contextLabel) return;
+        var ctx = resolveContext();
+        var turns = conversationHistory.length / 2;
+        var turnSuffix = turns === 0 ? '' : ' · ' + turns + ' turn' + (turns === 1 ? '' : 's');
+
+        // Session token total (Board #16). Reset on page reload.
+        var tokSuffix = sessionTokens.total > 0
+            ? ' · session: ' + fmtNumber(sessionTokens.total) + ' tokens'
+            : '';
+
+        if (ctx) {
+            contextLabel.textContent = 'context: ' + ctx.surface + ' / ' + ctx.ref + turnSuffix + tokSuffix;
+        } else {
+            // No bound ticket/task — still show page if available so user can see
+            // what context Sara IS getting (page-level + conversation history).
+            var pageLabel = cfg.page ? "page='" + cfg.page + "'" : 'no page';
+            contextLabel.textContent = 'context: none (' + pageLabel + ')' + turnSuffix + tokSuffix;
+        }
+    }
+
+    function togglePanel() {
+        var open = panel.classList.toggle('open');
+        panel.setAttribute('aria-hidden', open ? 'false' : 'true');
+        if (open) {
+            updateContextLabel();
+            input.focus();
+            scrollConversationToBottom();
+        }
+    }
+
+    function setStatus(msg) {
+        if (msg) {
+            statusLine.textContent = msg;
+            statusLine.style.display = 'block';
+        } else {
+            statusLine.textContent = '';
+            statusLine.style.display = 'none';
+        }
+    }
+
+    function scrollConversationToBottom() {
+        if (!conversationContainer) return;
+        // Defer to next tick so DOM updates are flushed
+        setTimeout(function () {
+            conversationContainer.scrollTop = conversationContainer.scrollHeight;
+        }, 0);
+    }
+
+    // ----- Render a single turn (user message + Sara response) -----
+    function renderTurn(userText, assistantStruct, usage) {
+        var turn = document.createElement('div');
+        turn.className = 'sa-orch-sara-turn';
+
+        // User block
+        var userBlock = document.createElement('div');
+        userBlock.className = 'sa-orch-sara-user-msg';
+        var userLabel = document.createElement('div');
+        userLabel.className = 'sa-orch-sara-msg-label';
+        userLabel.textContent = 'You';
+        var userBody = document.createElement('div');
+        userBody.className = 'sa-orch-sara-msg-body';
+        userBody.textContent = userText;
+        userBlock.appendChild(userLabel);
+        userBlock.appendChild(userBody);
+
+        // Sara block
+        var saraBlock = document.createElement('div');
+        saraBlock.className = 'sa-orch-sara-assistant-msg';
+
+        var saraHeader = document.createElement('div');
+        saraHeader.className = 'sa-orch-sara-msg-label';
+        saraHeader.innerHTML = 'Sara <span class="sa-orch-sara-not-saved">Not saved</span>';
+        saraBlock.appendChild(saraHeader);
+
+        function appendSection(label, text) {
+            if (!text || String(text).trim() === '') return;
+            var section = document.createElement('div');
+            section.className = 'sa-orch-sara-section';
+            var h = document.createElement('div');
+            h.className = 'sa-orch-sara-section-header';
+            h.textContent = label;
+            var b = document.createElement('div');
+            b.className = 'sa-orch-sara-section-body';
+            b.textContent = String(text);
+            section.appendChild(h);
+            section.appendChild(b);
+            saraBlock.appendChild(section);
+        }
+
+        appendSection('Summary',    assistantStruct.summary);
+        appendSection('Suggestion', assistantStruct.suggestion);
+        appendSection('Draft',      assistantStruct.draft);
+        appendSection('Notes',      assistantStruct.notes);
+
+        // Per-turn token footer (Board #16). Only shown when usage was returned.
+        if (usage && (usage.prompt_tokens || usage.completion_tokens || usage.total_tokens)) {
+            var footer = document.createElement('div');
+            footer.className = 'sa-orch-sara-usage';
+            footer.textContent = 'tokens: '
+                + fmtNumber(usage.prompt_tokens || 0)     + ' in / '
+                + fmtNumber(usage.completion_tokens || 0) + ' out · '
+                + fmtNumber(usage.total_tokens || 0)      + ' total';
+            saraBlock.appendChild(footer);
+        }
+
+        turn.appendChild(userBlock);
+        turn.appendChild(saraBlock);
+        conversationContainer.appendChild(turn);
+
+        scrollConversationToBottom();
+    }
+
+    function send() {
+        var ctx = resolveContext();
+        var prompt = (input.value || '').trim();
+        if (!prompt) {
+            setStatus('(empty prompt)');
+            return;
+        }
+
+        sendBtn.disabled = true;
+        sendBtn.textContent = 'Thinking...';
+        setStatus('');
+
+        // Build request body. Always send page (always non-empty under our enqueue).
+        // History is the SLICE of closed prior turns — does NOT include this new prompt yet.
+        var body = {
+            prompt: prompt,
+            page: cfg.page || '',
+            history: conversationHistory.slice()
+        };
+        if (ctx) {
+            body.surface = ctx.surface;
+            body.ref     = ctx.ref;
+        }
+
+        // Board #28 — Sara Asterion Context Binding.
+        // Visibility only: when on the explorer with a file in the URL,
+        // pass the file param through. No transformation client-side.
+        if (cfg.page === 'sa-orchestration-asterion' && typeof URLSearchParams !== 'undefined') {
+            var asterionFile = new URLSearchParams(window.location.search).get('file');
+            if (asterionFile) body.asterion_file = asterionFile;
+        }
+
+        fetch(cfg.rest_url, {
+            method: 'POST',
+            credentials: 'same-origin',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-WP-Nonce': cfg.nonce
+            },
+            body: JSON.stringify(body)
+        })
+        .then(function (r) {
+            return r.json().then(function (json) { return { ok: r.ok, json: json }; });
+        })
+        .then(function (result) {
+            sendBtn.disabled = false;
+            sendBtn.textContent = 'Send';
+
+            if (result.ok && result.json && result.json.response && typeof result.json.response === 'object') {
+                var assistantStruct = result.json.response;
+                var usage = result.json.usage || null;  // Board #16
+
+                // Update session-only token counters (Board #16). Reset on page reload.
+                if (usage) {
+                    sessionTokens.prompt     += parseInt(usage.prompt_tokens     || 0, 10);
+                    sessionTokens.completion += parseInt(usage.completion_tokens || 0, 10);
+                    sessionTokens.total      += parseInt(usage.total_tokens      || 0, 10);
+                }
+
+                // Push BOTH turns to history — close the round-trip
+                conversationHistory.push({ role: 'user',      content: prompt });
+                conversationHistory.push({ role: 'assistant', content: assistantStruct });
+
+                // Render in conversation panel
+                renderTurn(prompt, assistantStruct, usage);
+
+                // Track latest draft for Copy + Insert buttons
+                lastDraft = assistantStruct.draft || '';
+                copyBtn.style.display = lastDraft.trim() !== '' ? 'inline-block' : 'none';
+
+                // Insert button visibility re-evaluates on focus change AND
+                // whenever the draft changes; refresh now that lastDraft updated.
+                updateInsertVisibility();
+
+                // Clear input ready for next turn; keep panel open + scroll
+                input.value = '';
+                setStatus('');
+                updateContextLabel();
+            } else {
+                var msg = (result.json && (result.json.message || result.json.error)) || 'unexpected error';
+                setStatus('Error: ' + msg);
+                // Do NOT push to history on failure
+            }
+        })
+        .catch(function (err) {
+            sendBtn.disabled = false;
+            sendBtn.textContent = 'Send';
+            setStatus('Network error: ' + (err && err.message ? err.message : err));
+        });
+    }
+
+    // Board #15 — Insert handler. Operates ONLY on the user's currently
+    // focused valid field. No fallback targeting. No event dispatch.
+    function insertDraft() {
+        if (!lastDraft || String(lastDraft).trim() === '') {
+            flashInsertMessage('No draft to insert');
+            return;
+        }
+        // Use document.activeElement first (mousedown preventDefault kept focus
+        // on the textarea); fall back to lastValidField as defensive backup.
+        var target = isValidInsertTarget(document.activeElement) ? document.activeElement
+                   : (isValidInsertTarget(lastValidField) ? lastValidField : null);
+        if (!target) {
+            flashInsertMessage('No active input field');
+            return;
+        }
+        var ok = insertAtCursor(target, lastDraft);
+        flashInsertMessage(ok ? 'Inserted' : 'Could not insert');
+    }
+
+    function flashInsertMessage(msg) {
+        if (!insertMessage) return;
+        insertMessage.textContent = msg;
+        insertMessage.style.display = 'block';
+        setTimeout(function () {
+            insertMessage.style.display = 'none';
+            insertMessage.textContent = '';
+        }, 1800);
+    }
+
+    function copyDraft() {
+        if (!lastDraft) return;
+        var text = String(lastDraft);
+
+        var done = function (label) {
+            var orig = copyBtn.textContent;
+            copyBtn.textContent = label;
+            setTimeout(function () { copyBtn.textContent = orig; }, 1500);
+        };
+
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+            navigator.clipboard.writeText(text).then(
+                function () { done('Copied'); },
+                function () { done('Copy failed'); }
+            );
+        } else {
+            var ta = document.createElement('textarea');
+            ta.value = text;
+            document.body.appendChild(ta);
+            ta.select();
+            try { document.execCommand('copy'); done('Copied'); }
+            catch (e) { done('Copy failed'); }
+            document.body.removeChild(ta);
+        }
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', build);
+    } else {
+        build();
+    }
+})();

sa-orchestration/includes/class-sa-acceptance.php

@@ -0,0 +1,216 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Append-only by design. Class exposes only write() and read methods.
+ * No update(), no delete().
+ */
+class SA_Orch_Acceptance {
+
+    const ALLOWED_EVENT_TYPES = [
+        'result_claimed',
+        'acceptance_disputed',
+        'acceptance_affirmed',
+        'acceptance_revoked',
+    ];
+
+    const ALLOWED_ACTOR_ROLES = [
+        'agent',
+        'stakeholder',
+        'system',
+        'inferred',
+    ];
+
+    public static function write( array $args ) {
+        global $wpdb;
+
+        $demand_surface = isset( $args['demand_surface'] ) ? trim( (string) $args['demand_surface'] ) : '';
+        $demand_ref     = isset( $args['demand_ref'] )     ? trim( (string) $args['demand_ref'] )     : '';
+        $event_type     = isset( $args['event_type'] )     ? trim( (string) $args['event_type'] )     : '';
+        $actor_role     = isset( $args['actor_role'] )     ? trim( (string) $args['actor_role'] )     : '';
+
+        if ( $demand_surface === '' || $demand_ref === '' ) {
+            return new WP_Error( 'missing_demand', 'demand_surface and demand_ref are required' );
+        }
+        if ( ! in_array( $event_type, self::ALLOWED_EVENT_TYPES, true ) ) {
+            return new WP_Error( 'invalid_event_type', 'event_type must be one of: ' . implode( ', ', self::ALLOWED_EVENT_TYPES ) );
+        }
+        if ( ! in_array( $actor_role, self::ALLOWED_ACTOR_ROLES, true ) ) {
+            return new WP_Error( 'invalid_actor_role', 'actor_role must be one of: ' . implode( ', ', self::ALLOWED_ACTOR_ROLES ) );
+        }
+        if ( ! in_array( $demand_surface, SA_Orch_Bridge_Fluent::known_surfaces(), true ) ) {
+            return new WP_Error( 'unknown_surface', "demand_surface '$demand_surface' is not in known vocabulary" );
+        }
+        if ( ! SA_Orch_Bridge_Fluent::validate( $demand_surface, $demand_ref ) ) {
+            return new WP_Error( 'invalid_demand_ref', "demand_ref does not resolve: {$demand_surface}/{$demand_ref}" );
+        }
+
+        $prior_event_id = isset( $args['prior_event_id'] ) ? (int) $args['prior_event_id'] : null;
+        if ( $prior_event_id ) {
+            $exists = $wpdb->get_var( $wpdb->prepare(
+                "SELECT id FROM {$wpdb->prefix}" . SA_ORCH_DB_PREFIX . "acceptance_event WHERE id = %d",
+                $prior_event_id
+            ) );
+            if ( ! $exists ) {
+                return new WP_Error( 'invalid_prior_event', "prior_event_id $prior_event_id not found" );
+            }
+        }
+
+        $actor_user_id = isset( $args['actor_user_id'] ) ? (int) $args['actor_user_id'] : get_current_user_id();
+        if ( $actor_user_id === 0 ) { $actor_user_id = null; }
+
+        $details     = isset( $args['details'] )     ? (string) $args['details'] : null;
+        $truth_class = isset( $args['truth_class'] ) && $args['truth_class'] !== ''
+            ? (string) $args['truth_class']
+            : 'canonical';
+
+        $observed_at = isset( $args['observed_at'] ) && $args['observed_at'] !== ''
+            ? (string) $args['observed_at']
+            : current_time( 'mysql', true );
+        $recorded_at = current_time( 'mysql', true );
+
+        $hash = self::compute_hash( $demand_surface, $demand_ref, $event_type, $observed_at, $prior_event_id );
+
+        $frontmatter = [
+            'kind'           => 'acceptance_event',
+            'hash'           => $hash,
+            'demand_surface' => $demand_surface,
+            'demand_ref'     => $demand_ref,
+            'event_type'     => $event_type,
+            'prior_event_id' => $prior_event_id,
+            'actor_user_id'  => $actor_user_id,
+            'actor_role'     => $actor_role,
+            'truth_class'    => $truth_class,
+            'observed_at'    => $observed_at,
+            'recorded_at'    => $recorded_at,
+        ];
+
+        $body = "## Details\n\n" . ( $details !== null && $details !== '' ? $details : '(none)' ) . "\n";
+
+        $rel_path = SA_Orch_Asterion::write( 'acceptance_event', $hash, $frontmatter, $body );
+        if ( is_wp_error( $rel_path ) ) {
+            return $rel_path;
+        }
+
+        $table = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'acceptance_event';
+        $ok = $wpdb->insert( $table, [
+            'hash'           => $hash,
+            'demand_surface' => $demand_surface,
+            'demand_ref'     => $demand_ref,
+            'event_type'     => $event_type,
+            'prior_event_id' => $prior_event_id,
+            'actor_user_id'  => $actor_user_id,
+            'actor_role'     => $actor_role,
+            'details'        => $details,
+            'truth_class'    => $truth_class,
+            'asterion_path'  => $rel_path,
+            'observed_at'    => $observed_at,
+            'recorded_at'    => $recorded_at,
+        ] );
+
+        if ( $ok === false ) {
+            return new WP_Error( 'db_insert_failed', $wpdb->last_error, [ 'asterion_path' => $rel_path ] );
+        }
+
+        $event_id = (int) $wpdb->insert_id;
+
+        // v0.6.0: notify projection / side-effect listeners.
+        do_action( 'sa_orch_acceptance_event_written', [
+            'id'             => $event_id,
+            'hash'           => $hash,
+            'demand_surface' => $demand_surface,
+            'demand_ref'     => $demand_ref,
+            'event_type'     => $event_type,
+            'actor_role'     => $actor_role,
+            'actor_user_id'  => $actor_user_id,
+            'truth_class'    => $truth_class,
+            'asterion_path'  => $rel_path,
+        ] );
+
+        return [
+            'id'            => $event_id,
+            'hash'          => $hash,
+            'asterion_path' => $rel_path,
+        ];
+    }
+
+    /**
+     * Latest event per Demand. Useful for closure-rule queries.
+     * Returns object|null.
+     */
+    public static function latest_for_demand( $demand_surface, $demand_ref ) {
+        global $wpdb;
+        $table = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'acceptance_event';
+        return $wpdb->get_row( $wpdb->prepare(
+            "SELECT * FROM {$table}
+              WHERE demand_surface = %s AND demand_ref = %s
+              ORDER BY observed_at DESC, id DESC LIMIT 1",
+            $demand_surface,
+            $demand_ref
+        ) );
+    }
+
+    /**
+     * Basic closure state.
+     * Returns: 'no-events' | 'open:<event_type>' | 'closed'
+     *
+     * 'closed' iff the latest event is acceptance_affirmed (regardless of who affirmed it).
+     * Existing behavior since v0.1; preserved.
+     */
+    public static function basic_closure_state( $demand_surface, $demand_ref ) {
+        $latest = self::latest_for_demand( $demand_surface, $demand_ref );
+        if ( ! $latest )                                       return 'no-events';
+        if ( $latest->event_type !== 'acceptance_affirmed' )   return 'open:' . $latest->event_type;
+        return 'closed';
+    }
+
+    /**
+     * Role-aware closure state.
+     * Returns: 'no-events' | 'open:<event_type>' | 'role-mismatch:<actor_role>' | 'closed'
+     *
+     * 'closed' iff the latest event is acceptance_affirmed AND its actor_role is 'stakeholder'.
+     * Otherwise reports the specific reason closure is not authoritative.
+     *
+     * Per SIGNAL_FLOW.md closure rule: only stakeholder affirmation closes a Demand.
+     * Agent-self-affirmation, system-affirmation, etc. write successfully (append-only is preserved)
+     * but do not constitute closure under this stricter rule.
+     */
+    public static function role_aware_closure_state( $demand_surface, $demand_ref ) {
+        $latest = self::latest_for_demand( $demand_surface, $demand_ref );
+        if ( ! $latest )                                       return 'no-events';
+        if ( $latest->event_type !== 'acceptance_affirmed' )   return 'open:' . $latest->event_type;
+        if ( $latest->actor_role !== 'stakeholder' )           return 'role-mismatch:' . $latest->actor_role;
+        return 'closed';
+    }
+
+    /**
+     * Closure authority validity.
+     *
+     * Returns:
+     *   null   — no acceptance_affirmed has been recorded yet (latest is not affirmed, or no events at all).
+     *            Authority is not yet relevant; closure is not being claimed.
+     *   true   — latest acceptance_affirmed event has actor_role = 'stakeholder'. Closure is authoritative.
+     *   false  — latest acceptance_affirmed event has actor_role != 'stakeholder'. Closure is claimed
+     *            but the actor lacked closure authority. Recording is preserved (append-only); the
+     *            closure_state_role_aware field will read 'role-mismatch:<role>'.
+     */
+    public static function closure_authority_valid( $demand_surface, $demand_ref ) {
+        $latest = self::latest_for_demand( $demand_surface, $demand_ref );
+        if ( ! $latest )                                       return null;
+        if ( $latest->event_type !== 'acceptance_affirmed' )   return null;
+        return $latest->actor_role === 'stakeholder';
+    }
+
+    private static function compute_hash( $demand_surface, $demand_ref, $event_type, $observed_at, $prior_event_id ) {
+        // wp_rand suffix prevents collision when same demand+event_type+observed_at recorded twice
+        $material = implode( '|', [
+            $demand_surface,
+            $demand_ref,
+            $event_type,
+            $observed_at,
+            (int) $prior_event_id,
+            wp_rand(),
+        ] );
+        return substr( hash( 'sha256', $material ), 0, 32 );
+    }
+}

sa-orchestration/includes/class-sa-actor-admin.php

@@ -0,0 +1,235 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Sleeper Agents admin submenu — list / create / archive actors.
+ *
+ * Single page with view modes:
+ *   ?page=sa-orchestration-actors                  → list (default)
+ *   ?page=sa-orchestration-actors&view=create      → create form
+ *   ?page=sa-orchestration-actors&view=detail&id=X → detail
+ *
+ * POST actions (admin-post-style, handled via admin_init when on this page):
+ *   sa_actor_action=create          → create new actor; redirect to list
+ *   sa_actor_action=archive&id=X    → archive actor; redirect to list
+ *   sa_actor_action=unarchive&id=X  → unarchive actor; redirect to list
+ *
+ * Per the locked doctrine: actors created here are non-binding identity
+ * records. They cannot progress Boards, accept gates, or write to
+ * Asterion. This admin surface is the deliberate human-arbitrated path
+ * for instantiating those identities.
+ */
+class SA_Orch_Actor_Admin {
+
+    const SUBMENU_SLUG = 'sa-orchestration-actors';
+
+    public static function register_menu() {
+        add_submenu_page(
+            SA_Orch_Admin::PARENT_SLUG,
+            'Sleeper Agents',
+            'Sleeper Agents',
+            SA_Orch_Admin::CAP,
+            self::SUBMENU_SLUG,
+            [ __CLASS__, 'render_page' ]
+        );
+    }
+
+    /** Catch POST actions on the submenu page before rendering. */
+    public static function maybe_handle_action() {
+        if ( ! is_admin() ) return;
+        if ( ! current_user_can( SA_Orch_Admin::CAP ) ) return;
+        $page = isset( $_GET['page'] ) ? sanitize_text_field( wp_unslash( $_GET['page'] ) ) : '';
+        if ( $page !== self::SUBMENU_SLUG ) return;
+        $action = isset( $_POST['sa_actor_action'] ) ? sanitize_text_field( wp_unslash( $_POST['sa_actor_action'] ) ) : '';
+        if ( $action === '' ) return;
+
+        check_admin_referer( 'sa_actor_form', 'sa_actor_nonce' );
+
+        if ( $action === 'create' ) {
+            $data = [
+                'name'    => isset( $_POST['actor_name'] )    ? sanitize_text_field( wp_unslash( $_POST['actor_name'] ) )    : '',
+                'type'    => isset( $_POST['actor_type'] )    ? sanitize_text_field( wp_unslash( $_POST['actor_type'] ) )    : '',
+                'persona' => isset( $_POST['actor_persona'] ) ? sanitize_textarea_field( wp_unslash( $_POST['actor_persona'] ) ) : '',
+                'scope'   => isset( $_POST['actor_scope'] )   ? sanitize_textarea_field( wp_unslash( $_POST['actor_scope'] ) )   : '',
+            ];
+            $result = SA_Orch_Actor_Registry::create_actor( $data );
+            if ( is_wp_error( $result ) ) {
+                $msg = 'error&msg=' . rawurlencode( $result->get_error_message() );
+            } else {
+                $msg = 'created&id=' . (int) $result;
+            }
+            wp_safe_redirect( admin_url( 'admin.php?page=' . self::SUBMENU_SLUG . '&notice=' . $msg ) );
+            exit;
+        }
+
+        if ( $action === 'archive' || $action === 'unarchive' ) {
+            $id = isset( $_POST['actor_id'] ) ? (int) $_POST['actor_id'] : 0;
+            if ( $id > 0 ) {
+                if ( $action === 'archive' )   SA_Orch_Actor_Registry::archive_actor( $id );
+                if ( $action === 'unarchive' ) SA_Orch_Actor_Registry::unarchive_actor( $id );
+            }
+            wp_safe_redirect( admin_url( 'admin.php?page=' . self::SUBMENU_SLUG . '&notice=' . $action . 'd' ) );
+            exit;
+        }
+    }
+
+    /** Single-page render with view dispatching. */
+    public static function render_page() {
+        if ( ! current_user_can( SA_Orch_Admin::CAP ) ) {
+            wp_die( __( 'Insufficient permissions.', 'sa-orchestration' ) );
+        }
+        $view = isset( $_GET['view'] ) ? sanitize_text_field( wp_unslash( $_GET['view'] ) ) : 'list';
+
+        echo '<div class="wrap sa-actors-wrap">';
+        echo '<h1>Sleeper Agents <span class="sa-actors-tag">identity-bound roles · non-binding</span></h1>';
+        echo self::inline_styles();
+        self::render_notice();
+
+        if ( $view === 'create' ) {
+            self::render_create_form();
+        } elseif ( $view === 'detail' ) {
+            self::render_detail();
+        } else {
+            self::render_list();
+        }
+
+        echo '</div>'; // .wrap
+    }
+
+    private static function render_notice() {
+        if ( empty( $_GET['notice'] ) ) return;
+        $notice = sanitize_text_field( wp_unslash( $_GET['notice'] ) );
+        $msg    = isset( $_GET['msg'] ) ? sanitize_text_field( wp_unslash( $_GET['msg'] ) ) : '';
+        $kind   = 'success'; $body = '';
+        if ( $notice === 'created' ) {
+            $body = 'Actor created.';
+        } elseif ( $notice === 'archived' ) {
+            $body = 'Actor archived.';
+        } elseif ( $notice === 'unarchived' ) {
+            $body = 'Actor unarchived.';
+        } elseif ( $notice === 'error' ) {
+            $kind = 'error';
+            $body = $msg !== '' ? $msg : 'Action failed.';
+        }
+        if ( $body !== '' ) {
+            echo '<div class="notice notice-' . esc_attr( $kind ) . ' is-dismissible"><p>' . esc_html( $body ) . '</p></div>';
+        }
+    }
+
+    private static function render_list() {
+        $include_archived = ! empty( $_GET['show_archived'] );
+        $actors = SA_Orch_Actor_Registry::list_actors( $include_archived );
+
+        $create_url = admin_url( 'admin.php?page=' . self::SUBMENU_SLUG . '&view=create' );
+        $toggle_archived_url = add_query_arg( 'show_archived', $include_archived ? '0' : '1' );
+
+        echo '<p class="sa-actors-meta">Actors are persistent identity-bound roles. They may speak, draft, advise, observe, coordinate. They may not progress Boards, accept gates, mutate Asterion, or act silently.</p>';
+
+        echo '<p>';
+        echo '<a href="' . esc_url( $create_url ) . '" class="button button-primary">+ Create Actor</a> &nbsp; ';
+        echo '<a href="' . esc_url( $toggle_archived_url ) . '" class="button">' . ( $include_archived ? 'Hide archived' : 'Show archived' ) . '</a>';
+        echo '</p>';
+
+        echo '<table class="wp-list-table widefat fixed striped sa-actors-table">';
+        echo '<thead><tr>';
+        echo '<th>Name</th><th>Type</th><th>Owner</th><th>Status</th><th>Persona (excerpt)</th><th>Created</th><th>Actions</th>';
+        echo '</tr></thead><tbody>';
+        if ( empty( $actors ) ) {
+            echo '<tr><td colspan="7" class="sa-actors-empty">No actors yet. <a href="' . esc_url( $create_url ) . '">Create the first one</a> with intent.</td></tr>';
+        } else {
+            foreach ( $actors as $u ) {
+                $a = SA_Orch_Actor_Registry::get_actor( (int) $u->ID );
+                if ( ! $a ) continue;
+                $detail_url = admin_url( 'admin.php?page=' . self::SUBMENU_SLUG . '&view=detail&id=' . $a['user_id'] );
+                $persona_excerpt = function_exists( 'mb_substr' ) ? mb_substr( $a['persona'], 0, 80 ) : substr( $a['persona'], 0, 80 );
+                $status_label = $a['is_active'] ? '<span class="sa-actors-status-active">active</span>' : '<span class="sa-actors-status-archived">archived</span>';
+
+                echo '<tr>';
+                echo '<td><strong><a href="' . esc_url( $detail_url ) . '">' . esc_html( $a['name'] ) . '</a></strong><br><small class="sa-actors-login">' . esc_html( $a['login'] ) . '</small></td>';
+                echo '<td>' . esc_html( $a['type'] ) . '</td>';
+                echo '<td>' . esc_html( $a['owner_login'] ?: '—' ) . '</td>';
+                echo '<td>' . $status_label . '</td>'; // status_label is pre-built; safe
+                echo '<td>' . esc_html( $persona_excerpt ) . ( strlen( $a['persona'] ) > 80 ? '…' : '' ) . '</td>';
+                echo '<td>' . esc_html( $a['created_at'] ) . '</td>';
+                echo '<td>';
+                if ( $a['is_active'] ) {
+                    self::render_post_button( 'archive', $a['user_id'], 'Archive' );
+                } else {
+                    self::render_post_button( 'unarchive', $a['user_id'], 'Unarchive' );
+                }
+                echo '</td>';
+                echo '</tr>';
+            }
+        }
+        echo '</tbody></table>';
+    }
+
+    private static function render_post_button( string $action, int $actor_id, string $label ) {
+        $url = admin_url( 'admin.php?page=' . self::SUBMENU_SLUG );
+        echo '<form method="post" action="' . esc_url( $url ) . '" style="display:inline;">';
+        wp_nonce_field( 'sa_actor_form', 'sa_actor_nonce' );
+        echo '<input type="hidden" name="sa_actor_action" value="' . esc_attr( $action ) . '" />';
+        echo '<input type="hidden" name="actor_id"        value="' . esc_attr( (string) $actor_id ) . '" />';
+        echo '<button type="submit" class="button button-small">' . esc_html( $label ) . '</button>';
+        echo '</form>';
+    }
+
+    private static function render_create_form() {
+        $list_url = admin_url( 'admin.php?page=' . self::SUBMENU_SLUG );
+        echo '<h2>Create Actor</h2>';
+        echo '<p class="sa-actors-meta">Creation discipline: actors must be named with intent, have a defined role, and a scoped purpose. No "random AI assistant" — only purposeful, identity-bound roles.</p>';
+        echo '<form method="post" action="' . esc_url( $list_url ) . '" class="sa-actors-form">';
+        wp_nonce_field( 'sa_actor_form', 'sa_actor_nonce' );
+        echo '<input type="hidden" name="sa_actor_action" value="create" />';
+
+        echo '<table class="form-table"><tbody>';
+        echo '<tr><th><label for="actor_name">Name <span class="required">*</span></label></th><td><input id="actor_name" name="actor_name" type="text" class="regular-text" required placeholder="e.g. Bridget — Reconciliation" /></td></tr>';
+        echo '<tr><th><label for="actor_type">Type <span class="required">*</span></label></th><td><input id="actor_type" name="actor_type" type="text" class="regular-text" required placeholder="e.g. reconciliation, designer, lawyer, dev" /></td></tr>';
+        echo '<tr><th><label for="actor_persona">Persona <span class="required">*</span></label></th><td><textarea id="actor_persona" name="actor_persona" rows="4" class="large-text" required placeholder="Voice + behavior. What this actor is for. e.g. \'System-level coordination actor. Monitors shared objects, highlights divergence, suggests reconciliation.\'"></textarea></td></tr>';
+        echo '<tr><th><label for="actor_scope">Scope</label></th><td><textarea id="actor_scope" name="actor_scope" rows="3" class="large-text" placeholder="What surfaces / objects this actor may comment on. e.g. \'cross-board observations\', \'fluent-support tickets\', \'fluent-boards tasks tagged urgent\'"></textarea></td></tr>';
+        echo '</tbody></table>';
+
+        echo '<p>';
+        echo '<button type="submit" class="button button-primary">Create Actor</button> &nbsp; ';
+        echo '<a href="' . esc_url( $list_url ) . '" class="button">Cancel</a>';
+        echo '</p>';
+        echo '</form>';
+    }
+
+    private static function render_detail() {
+        $list_url = admin_url( 'admin.php?page=' . self::SUBMENU_SLUG );
+        $id = isset( $_GET['id'] ) ? (int) $_GET['id'] : 0;
+        $a  = $id > 0 ? SA_Orch_Actor_Registry::get_actor( $id ) : null;
+        if ( ! $a ) {
+            echo '<p class="sa-actors-empty">Actor not found. <a href="' . esc_url( $list_url ) . '">Back to list</a></p>';
+            return;
+        }
+        echo '<h2>' . esc_html( $a['name'] ) . ' <small class="sa-actors-login">' . esc_html( $a['login'] ) . '</small></h2>';
+        echo '<p><a href="' . esc_url( $list_url ) . '">&larr; Back to list</a></p>';
+        echo '<table class="form-table"><tbody>';
+        echo '<tr><th>Type</th>              <td>' . esc_html( $a['type'] ) . '</td></tr>';
+        echo '<tr><th>Status</th>            <td>' . ( $a['is_active'] ? 'active' : 'archived' ) . '</td></tr>';
+        echo '<tr><th>Owner</th>             <td>' . esc_html( $a['owner_login'] ?: '—' ) . ' (user_id=' . (int) $a['owner_user_id'] . ')</td></tr>';
+        echo '<tr><th>Persona</th>           <td><pre class="sa-actors-pre">' . esc_html( $a['persona'] ) . '</pre></td></tr>';
+        echo '<tr><th>Scope</th>             <td><pre class="sa-actors-pre">' . esc_html( $a['scope'] ?: '—' ) . '</pre></td></tr>';
+        echo '<tr><th>Subscription tier</th> <td>' . esc_html( $a['subscription_tier'] ?: '— (reserved for future)' ) . '</td></tr>';
+        echo '<tr><th>Created</th>           <td>' . esc_html( $a['created_at'] ) . '</td></tr>';
+        echo '</tbody></table>';
+
+        echo '<h3>Activity trail</h3>';
+        echo '<p class="sa-actors-meta">Actor-attributed comments and drafts will appear here once the invocation surface is implemented (deferred to a future Board). For now: empty by design.</p>';
+    }
+
+    private static function inline_styles(): string {
+        return '<style>
+            .sa-actors-wrap h1 .sa-actors-tag { font-size:11px; padding:2px 6px; background:#f0f0f1; color:#646970; border-radius:3px; vertical-align:middle; font-weight:normal; margin-left:8px; }
+            .sa-actors-meta { color:#646970; }
+            .sa-actors-table .sa-actors-login { color:#646970; font-family:Consolas,Monaco,monospace; font-size:11px; }
+            .sa-actors-status-active   { color:#1e4620; background:#edf7ed; padding:2px 6px; border-radius:3px; font-size:11px; }
+            .sa-actors-status-archived { color:#646970; background:#f0f0f1; padding:2px 6px; border-radius:3px; font-size:11px; }
+            .sa-actors-empty { color:#646970; font-style:italic; }
+            .sa-actors-pre   { background:#f6f7f7; padding:10px; border-radius:4px; white-space:pre-wrap; max-width:680px; }
+            .sa-actors-form .required { color:#d63638; }
+        </style>';
+    }
+}

sa-orchestration/includes/class-sa-actor-handoff.php

@@ -0,0 +1,134 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Actor Handoff Log — two-axis attribution (Board #23).
+ *
+ * Provides a clear, auditable boundary between AI-operated actor mode
+ * and human-operated actor mode WITHOUT mutating Fluent's own comment
+ * tables. Strictly additive: a small dedicated table records who
+ * "pressed send" for a given actor-authored comment.
+ *
+ * The two axes:
+ *   created_by    — the actor (Bridget, etc.). The displayed author. Unchanged.
+ *   committed_by  — the user who pressed send (a human user, or an agent
+ *                   service account user). Recorded here, queried via
+ *                   SA_Orch_Actor_Handoff::get_committer().
+ *
+ * Operator-mode detection — the full provenance chain works once Board #16
+ * (Token + Usage Visibility) ships its LLM token log. Until then, the
+ * token-presence check returns 'unknown' and detect_mode reflects that
+ * honestly:
+ *
+ *   committer recorded + token row found        → 'ai'
+ *   committer recorded + token row NOT found    → 'human'
+ *   committer recorded + token state unknown    → 'unknown'  (pre-#16; honest)
+ *   committer NOT recorded                      → 'unknown'
+ *
+ * The token-presence check is implemented as a filter:
+ *
+ *   apply_filters( 'sa_orch_handoff_has_llm_token', null, $kind, $comment_id );
+ *
+ * Board #16 will register a callback that consults the token log. The
+ * default return of null means "unknown" — never a false positive.
+ *
+ * Doctrine constraints honored:
+ *   - Actors remain non-binding; this layer is observational, not enforcing
+ *   - No impact to Board progression rules
+ *   - No schema refactors — strictly additive (one new table)
+ *   - No Asterion writes
+ *   - No automation
+ *   - No UI surface beyond what already exists
+ */
+class SA_Orch_Actor_Handoff {
+
+    const KIND_FLUENT_BOARDS  = 'fluent_boards';
+    const KIND_FLUENT_SUPPORT = 'fluent_support';
+
+    const MODE_AI      = 'ai';
+    const MODE_HUMAN   = 'human';
+    const MODE_UNKNOWN = 'unknown';
+
+    private static function table(): string {
+        global $wpdb;
+        return $wpdb->prefix . SA_ORCH_DB_PREFIX . 'actor_handoff';
+    }
+
+    /**
+     * Record (or update) the committer for an actor-authored comment.
+     * Idempotent on (kind, comment_id) — re-recording replaces the prior row.
+     *
+     * Returns true on success, false on invalid input or DB failure.
+     */
+    public static function record_committer( string $kind, int $comment_id, int $committed_by_user_id ): bool {
+        if ( $comment_id <= 0 || $committed_by_user_id <= 0 ) {
+            return false;
+        }
+        $kind = sanitize_key( $kind );
+        if ( $kind === '' ) return false;
+
+        global $wpdb;
+        $tbl = self::table();
+        // Replace prior row, if any. Keeps the table thin.
+        $wpdb->delete( $tbl, [
+            'comment_kind' => $kind,
+            'comment_id'   => $comment_id,
+        ] );
+        $ok = $wpdb->insert( $tbl, [
+            'comment_kind'         => $kind,
+            'comment_id'           => $comment_id,
+            'committed_by_user_id' => $committed_by_user_id,
+            'recorded_at'          => current_time( 'mysql', true ),
+        ] );
+        return $ok !== false;
+    }
+
+    /**
+     * Get the recorded committer for a comment, or null if none recorded.
+     */
+    public static function get_committer( string $kind, int $comment_id ): ?int {
+        if ( $comment_id <= 0 ) return null;
+        $kind = sanitize_key( $kind );
+        if ( $kind === '' ) return null;
+
+        global $wpdb;
+        $row = $wpdb->get_var( $wpdb->prepare(
+            "SELECT committed_by_user_id FROM " . self::table() . "
+             WHERE comment_kind = %s AND comment_id = %d
+             ORDER BY id DESC LIMIT 1",
+            $kind,
+            $comment_id
+        ) );
+        return $row !== null ? (int) $row : null;
+    }
+
+    /**
+     * Detect operator mode for a comment. Returns one of the MODE_* constants.
+     * Never lies about uncertainty — returns 'unknown' rather than guessing.
+     */
+    public static function detect_mode( string $kind, int $comment_id ): string {
+        $committer = self::get_committer( $kind, $comment_id );
+        if ( $committer === null ) {
+            return self::MODE_UNKNOWN;
+        }
+
+        /**
+         * Filter that signals whether an LLM token row exists for this commit.
+         * Returns: true (token row found → AI mode),
+         *          false (no token row → human mode),
+         *          null (unknown — token log not yet integrated, default).
+         *
+         * Board #16 will register a callback that consults the token log.
+         */
+        $token_present = apply_filters(
+            'sa_orch_handoff_has_llm_token',
+            null,
+            $kind,
+            $comment_id
+        );
+
+        if ( $token_present === null )  return self::MODE_UNKNOWN;
+        if ( $token_present === true )  return self::MODE_AI;
+        return self::MODE_HUMAN;
+    }
+}

sa-orchestration/includes/class-sa-actor-registry.php

@@ -0,0 +1,192 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Actor Registry — WP-User-backed identity layer (Board #22).
+ *
+ * Actors are persistent identity-bound roles — NOT disposable NPCs. Each
+ * actor is a real WordPress user with the 'sa_actor' role and structured
+ * metadata recorded in user_meta. The wp_users row + meta together IS the
+ * actor's persistent identity for this Board.
+ *
+ * Doctrine constraints (locked, non-negotiable):
+ *   Actors may:    speak, draft, advise, observe, coordinate
+ *   Actors may NOT: progress Boards, accept/close tasks, mutate Asterion,
+ *                   silently act
+ *
+ *   Sara grants voice. Asterion grants permission. Human grants progress.
+ *
+ * Implementation notes:
+ *   - 'sa_actor' role gets only 'read' capability — nothing else. Actors
+ *     are not real operators; they exist to be attributed.
+ *   - Asterion ledger MD writes for actor records are out of this Board's
+ *     scope. The dormant SA_Orch_Asterion writer stays dormant. Future
+ *     Board can add literal canonical writes when the write surface
+ *     activates.
+ *   - Archive (sa_actor_is_active='0'), never delete. Actors are retired,
+ *     not destroyed. Continuity preserved.
+ */
+class SA_Orch_Actor_Registry {
+
+    const ROLE = 'sa_actor';
+
+    // user_meta keys — namespaced 'sa_actor_*' to avoid collision with other plugins
+    const META_TYPE              = 'sa_actor_type';
+    const META_PERSONA           = 'sa_actor_persona';
+    const META_SCOPE             = 'sa_actor_scope';
+    const META_OWNER_USER_ID     = 'sa_actor_owner_user_id';
+    const META_IS_ACTIVE         = 'sa_actor_is_active';
+    const META_SUBSCRIPTION_TIER = 'sa_actor_subscription_tier';
+
+    /** Idempotent role registration. Hooked on init. */
+    public static function register_role() {
+        if ( ! get_role( self::ROLE ) ) {
+            add_role( self::ROLE, __( 'SA Actor', 'sa-orchestration' ), [
+                'read' => true,
+            ] );
+        }
+    }
+
+    /**
+     * List actors. Returns an array of WP_User objects.
+     * By default excludes archived actors; pass include_archived=true to see all.
+     */
+    public static function list_actors( bool $include_archived = false ): array {
+        $args = [
+            'role'    => self::ROLE,
+            'orderby' => 'display_name',
+            'order'   => 'ASC',
+            'number'  => 200,
+        ];
+        if ( ! $include_archived ) {
+            $args['meta_query'] = [
+                'relation' => 'OR',
+                [ 'key' => self::META_IS_ACTIVE, 'value' => '1', 'compare' => '=' ],
+                [ 'key' => self::META_IS_ACTIVE, 'compare' => 'NOT EXISTS' ], // legacy/unset → treat as active
+            ];
+        }
+        $users = get_users( $args );
+        return is_array( $users ) ? $users : [];
+    }
+
+    /**
+     * Hydrate an actor's full record. Returns null if user does not exist
+     * or does not have the sa_actor role (defensive — never expose
+     * non-actor users through this surface).
+     */
+    public static function get_actor( int $user_id ): ?array {
+        $user = get_userdata( $user_id );
+        if ( ! $user || ! in_array( self::ROLE, (array) $user->roles, true ) ) {
+            return null;
+        }
+        $owner_id    = (int) get_user_meta( $user_id, self::META_OWNER_USER_ID, true );
+        $owner_user  = $owner_id ? get_userdata( $owner_id ) : null;
+        $is_active_v = get_user_meta( $user_id, self::META_IS_ACTIVE, true );
+        return [
+            'user_id'           => (int) $user->ID,
+            'name'              => (string) $user->display_name,
+            'login'             => (string) $user->user_login,
+            'email'             => (string) $user->user_email,
+            'type'              => (string) get_user_meta( $user_id, self::META_TYPE,    true ),
+            'persona'           => (string) get_user_meta( $user_id, self::META_PERSONA, true ),
+            'scope'             => (string) get_user_meta( $user_id, self::META_SCOPE,   true ),
+            'owner_user_id'     => $owner_id,
+            'owner_login'       => $owner_user ? (string) $owner_user->user_login : '',
+            'is_active'         => ( $is_active_v === '' || $is_active_v === '1' ),
+            'subscription_tier' => (string) get_user_meta( $user_id, self::META_SUBSCRIPTION_TIER, true ),
+            'created_at'        => (string) $user->user_registered,
+        ];
+    }
+
+    /**
+     * Create an actor. Required: name, type, persona (creation discipline —
+     * no nameless or roleless or purposeless actors). Owner defaults to
+     * current user. Email is synthetic if not provided (actors are not
+     * meant to log in).
+     *
+     * Returns the new user_id (int) or WP_Error on validation/creation failure.
+     */
+    public static function create_actor( array $data ) {
+        $name    = isset( $data['name'] )    ? trim( (string) $data['name'] )    : '';
+        $type    = isset( $data['type'] )    ? trim( (string) $data['type'] )    : '';
+        $persona = isset( $data['persona'] ) ? trim( (string) $data['persona'] ) : '';
+        $scope   = isset( $data['scope'] )   ? trim( (string) $data['scope'] )   : '';
+        $email   = isset( $data['email'] )   ? trim( (string) $data['email'] )   : '';
+        $owner   = isset( $data['owner_user_id'] ) ? (int) $data['owner_user_id'] : (int) get_current_user_id();
+
+        if ( $name    === '' ) return new WP_Error( 'actor_name_required',    'Actor name is required (intent — no random assistants).' );
+        if ( $type    === '' ) return new WP_Error( 'actor_type_required',    'Actor type is required (defined role).' );
+        if ( $persona === '' ) return new WP_Error( 'actor_persona_required', 'Actor persona is required (scoped purpose).' );
+
+        // Synthesize a unique login from the name. WP requires unique user_login.
+        $login_base = sanitize_user( strtolower( str_replace( ' ', '-', $name ) ), true );
+        if ( $login_base === '' ) $login_base = 'sa-actor';
+        $login = $login_base;
+        $i = 1;
+        while ( username_exists( $login ) ) {
+            $login = $login_base . '-' . $i++;
+            if ( $i > 200 ) {
+                return new WP_Error( 'actor_login_exhausted', 'Could not generate unique login for this actor name.' );
+            }
+        }
+
+        // Synthesize an email if not provided. Actors live as WP users for
+        // identity but are not expected to log in or receive mail.
+        if ( $email === '' ) {
+            $email = $login . '@sleeperagents.local';
+        }
+        if ( email_exists( $email ) ) {
+            $email = $login . '+' . wp_generate_password( 6, false ) . '@sleeperagents.local';
+        }
+
+        // Random password — actors are not meant to log in. We never expose it.
+        $password = wp_generate_password( 32, true, true );
+
+        $user_id = wp_insert_user( [
+            'user_login'   => $login,
+            'user_email'   => $email,
+            'user_pass'    => $password,
+            'display_name' => $name,
+            'first_name'   => $name,
+            'role'         => self::ROLE,
+        ] );
+        if ( is_wp_error( $user_id ) ) {
+            return $user_id;
+        }
+
+        update_user_meta( $user_id, self::META_TYPE,              $type );
+        update_user_meta( $user_id, self::META_PERSONA,           $persona );
+        update_user_meta( $user_id, self::META_SCOPE,             $scope );
+        update_user_meta( $user_id, self::META_OWNER_USER_ID,     $owner );
+        update_user_meta( $user_id, self::META_IS_ACTIVE,         '1' );
+        update_user_meta( $user_id, self::META_SUBSCRIPTION_TIER, '' );
+
+        /**
+         * Hook for downstream consumers (e.g. a future Asterion ledger writer
+         * that records canonical actor identity in markdown). Today nothing
+         * listens; the hook exists so the future write surface can attach
+         * without re-architecting this Board.
+         */
+        do_action( 'sa_orch_actor_created', (int) $user_id, $data );
+
+        return (int) $user_id;
+    }
+
+    /** Archive an actor (sets is_active=0). Returns true on success. */
+    public static function archive_actor( int $user_id ): bool {
+        $actor = self::get_actor( $user_id );
+        if ( ! $actor ) return false;
+        update_user_meta( $user_id, self::META_IS_ACTIVE, '0' );
+        do_action( 'sa_orch_actor_archived', $user_id );
+        return true;
+    }
+
+    /** Unarchive an actor (sets is_active=1). */
+    public static function unarchive_actor( int $user_id ): bool {
+        $actor = self::get_actor( $user_id );
+        if ( ! $actor ) return false;
+        update_user_meta( $user_id, self::META_IS_ACTIVE, '1' );
+        do_action( 'sa_orch_actor_unarchived', $user_id );
+        return true;
+    }
+}

sa-orchestration/includes/class-sa-adapter-fluent-boards.php

@@ -0,0 +1,116 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Fluent Boards surface adapter.
+ *
+ * Resolves task#NNN refs against wp_fbs_tasks. ALL Fluent Boards schema
+ * knowledge lives here. If Fluent Boards changes its schema (renames a
+ * column, drops a field, splits a record), the change lands in this
+ * file alone. Consumers of the adapter never see the schema directly.
+ *
+ * Ref shape: 'task#<positive integer>'
+ */
+class SA_Orch_Adapter_FluentBoards implements SA_Orch_Surface_Adapter {
+
+    public function id(): string {
+        return 'fluent-boards';
+    }
+
+    public function validate( string $ref ): bool {
+        return $this->resolve( $ref ) !== null;
+    }
+
+    public function resolve( string $ref ) {
+        global $wpdb;
+        if ( ! preg_match( '/^task#(\d+)$/', $ref, $m ) ) {
+            return null;
+        }
+        $row = $wpdb->get_row( $wpdb->prepare(
+            "SELECT * FROM {$wpdb->prefix}fbs_tasks WHERE id = %d",
+            (int) $m[1]
+        ) );
+        return $row ?: null;
+    }
+
+    public function label( string $ref ): string {
+        $row = $this->resolve( $ref );
+        if ( ! $row ) {
+            return $ref;
+        }
+        // Title is the canonical label per current Fluent Boards schema.
+        // If schema changes (e.g. title becomes a sub-field, gets renamed,
+        // requires a join), update this method only.
+        if ( isset( $row->title ) && trim( (string) $row->title ) !== '' ) {
+            return (string) $row->title;
+        }
+        return $ref;
+    }
+
+    /**
+     * Structured snapshot of the task — title, board name, stage, status,
+     * description summary, recent activity excerpts. All Fluent Boards schema
+     * knowledge stays bounded to this method; consumers receive a stable
+     * shape regardless of future schema changes.
+     */
+    public function hydrate( string $ref ): ?array {
+        global $wpdb;
+        if ( ! preg_match( '/^task#(\d+)$/', $ref, $m ) ) {
+            return null;
+        }
+        $task_id = (int) $m[1];
+
+        $task = $wpdb->get_row( $wpdb->prepare(
+            "SELECT id, title, status, description, board_id, stage_id, created_at, updated_at
+               FROM {$wpdb->prefix}fbs_tasks WHERE id = %d",
+            $task_id
+        ) );
+        if ( ! $task ) {
+            return null;
+        }
+
+        $board_name = (string) $wpdb->get_var( $wpdb->prepare(
+            "SELECT title FROM {$wpdb->prefix}fbs_boards WHERE id = %d",
+            (int) $task->board_id
+        ) );
+        $stage_name = (string) $wpdb->get_var( $wpdb->prepare(
+            "SELECT title FROM {$wpdb->prefix}fbs_board_terms WHERE id = %d",
+            (int) $task->stage_id
+        ) );
+
+        $recent = $wpdb->get_results( $wpdb->prepare(
+            "SELECT description, created_at FROM {$wpdb->prefix}fbs_comments
+              WHERE task_id = %d
+              ORDER BY created_at DESC, id DESC LIMIT 3",
+            $task_id
+        ) );
+        $activity = [];
+        foreach ( (array) $recent as $row ) {
+            $text = trim( wp_strip_all_tags( (string) $row->description ) );
+            if ( $text === '' ) continue;
+            $activity[] = [
+                'created_at' => (string) $row->created_at,
+                'excerpt'    => function_exists( 'mb_substr' )
+                    ? mb_substr( $text, 0, 240 )
+                    : substr( $text, 0, 240 ),
+            ];
+        }
+
+        $description = trim( wp_strip_all_tags( (string) $task->description ) );
+        if ( function_exists( 'mb_substr' ) ) {
+            $description = mb_substr( $description, 0, 500 );
+        } else {
+            $description = substr( $description, 0, 500 );
+        }
+
+        return [
+            'ref'             => $ref,
+            'title'           => (string) $task->title,
+            'board_name'      => $board_name,
+            'stage'           => $stage_name,
+            'status'          => (string) $task->status,
+            'description'     => $description,
+            'recent_activity' => $activity,
+        ];
+    }
+}

sa-orchestration/includes/class-sa-adapter-fluent-support.php

@@ -0,0 +1,214 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Fluent Support surface adapter.
+ *
+ * Resolves ticket#NNN refs against wp_fs_tickets. ALL Fluent Support
+ * schema knowledge lives here. If Fluent Support changes its schema
+ * (renames a column, drops a field, splits a record), the change lands
+ * in this file alone. Consumers of the adapter never see the schema
+ * directly.
+ *
+ * Schema bounded to this adapter:
+ *   wp_fs_tickets       (id, customer_id, title, status, priority, content, created_at)
+ *   wp_fs_persons       (first_name, last_name, email; person_type='customer')
+ *   wp_fs_conversations (ticket_id, person_id, conversation_type, content, created_at)
+ *
+ * NOTE: The customer display name is composed in PHP from first_name +
+ * last_name with email fallback. There is intentionally NO use of
+ * `full_name` — that is an ORM-layer accessor on the FluentSupport Person
+ * model (declared via $appends), not a real database column. SELECTing
+ * full_name from wp_fs_persons would error.
+ *
+ * Conversation snippets are filtered to conversation_type='response',
+ * which excludes 'internal_info' rows (FluentSupport's own internal
+ * notes, including SA-Orchestration's own ticket-tracking comments).
+ *
+ * Ref shape: 'ticket#<positive integer>'
+ */
+class SA_Orch_Adapter_FluentSupport implements SA_Orch_Surface_Adapter {
+
+    public function id(): string {
+        return 'fluent-support';
+    }
+
+    public function validate( string $ref ): bool {
+        return $this->resolve( $ref ) !== null;
+    }
+
+    public function resolve( string $ref ) {
+        global $wpdb;
+        if ( ! preg_match( '/^ticket#(\d+)$/', $ref, $m ) ) {
+            return null;
+        }
+        $row = $wpdb->get_row( $wpdb->prepare(
+            "SELECT * FROM {$wpdb->prefix}fs_tickets WHERE id = %d",
+            (int) $m[1]
+        ) );
+        return $row ?: null;
+    }
+
+    public function label( string $ref ): string {
+        $row = $this->resolve( $ref );
+        if ( ! $row ) {
+            return $ref;
+        }
+        if ( isset( $row->title ) && trim( (string) $row->title ) !== '' ) {
+            return (string) $row->title;
+        }
+        return $ref;
+    }
+
+    /**
+     * Structured snapshot of the ticket — title, status, priority, customer
+     * display name, description excerpt, and the latest visible conversation
+     * snippets (customer/agent dialogue only). All FluentSupport schema
+     * knowledge stays bounded to this method; consumers receive a stable
+     * shape regardless of future schema changes.
+     *
+     * Graceful fallback per field:
+     *   - missing customer row              → omit 'customer'
+     *   - first_name + last_name both empty → fall back to email
+     *   - email also empty                  → omit 'customer'
+     *   - empty ticket content              → omit 'description'
+     *   - no visible conversations          → 'recent_activity' is empty array
+     */
+    public function hydrate( string $ref ): ?array {
+        global $wpdb;
+        if ( ! preg_match( '/^ticket#(\d+)$/', $ref, $m ) ) {
+            return null;
+        }
+        $ticket_id = (int) $m[1];
+
+        $ticket = $wpdb->get_row( $wpdb->prepare(
+            "SELECT id, customer_id, title, status, priority, content, created_at, updated_at
+               FROM {$wpdb->prefix}fs_tickets WHERE id = %d",
+            $ticket_id
+        ) );
+        if ( ! $ticket ) {
+            return null;
+        }
+
+        $out = [
+            'ref'    => $ref,
+            'title'  => (string) $ticket->title,
+            'status' => (string) $ticket->status,
+        ];
+
+        // Priority is meaningful for support tickets (normal, high, urgent...).
+        // Optional — only emit if non-empty.
+        if ( ! empty( $ticket->priority ) ) {
+            $out['priority'] = (string) $ticket->priority;
+        }
+
+        // Customer — composed name from first_name + last_name; email fallback;
+        // omit entirely if neither is available.
+        $customer = $this->compose_customer_label( (int) $ticket->customer_id );
+        if ( $customer !== '' ) {
+            $out['customer'] = $customer;
+        }
+
+        // Description excerpt (HTML stripped, ~500 chars).
+        $description = trim( wp_strip_all_tags( (string) $ticket->content ) );
+        if ( $description !== '' ) {
+            $out['description'] = function_exists( 'mb_substr' )
+                ? mb_substr( $description, 0, 500 )
+                : substr( $description, 0, 500 );
+        }
+
+        // Recent customer/agent dialogue — last 3 visible exchanges.
+        // Filter to conversation_type='response' so SA-Orchestration's own
+        // internal_info tracking rows do not bleed into Sara's context.
+        $recent = $wpdb->get_results( $wpdb->prepare(
+            "SELECT id, person_id, content, created_at
+               FROM {$wpdb->prefix}fs_conversations
+              WHERE ticket_id = %d AND conversation_type = 'response'
+              ORDER BY created_at DESC, id DESC LIMIT 3",
+            $ticket_id
+        ) );
+        $activity = [];
+        foreach ( (array) $recent as $row ) {
+            $text = trim( wp_strip_all_tags( (string) $row->content ) );
+            if ( $text === '' ) continue;
+            $excerpt = function_exists( 'mb_substr' )
+                ? mb_substr( $text, 0, 240 )
+                : substr( $text, 0, 240 );
+            $by = $this->compose_person_label( (int) $row->person_id );
+            $item = [
+                'created_at' => (string) $row->created_at,
+                'excerpt'    => $excerpt,
+            ];
+            if ( $by !== '' ) {
+                $item['by'] = $by;
+            }
+            $activity[] = $item;
+        }
+        $out['recent_activity'] = $activity;
+
+        return $out;
+    }
+
+    /**
+     * Compose a display label for a customer person row.
+     * Returns empty string if the person row is missing or has no name/email.
+     *
+     * Order: "first last" → email → '' (caller should omit the field).
+     * Never reads $appends accessors like full_name — those exist only at
+     * the ORM layer.
+     */
+    private function compose_customer_label( int $person_id ): string {
+        if ( $person_id <= 0 ) {
+            return '';
+        }
+        global $wpdb;
+        $row = $wpdb->get_row( $wpdb->prepare(
+            "SELECT first_name, last_name, email
+               FROM {$wpdb->prefix}fs_persons
+              WHERE id = %d AND person_type = 'customer'",
+            $person_id
+        ) );
+        if ( ! $row ) {
+            return '';
+        }
+        return $this->compose_name_from_row( $row );
+    }
+
+    /**
+     * Compose a display label for any person (customer OR agent).
+     * Used for conversation authors — agents are people too, but they have
+     * person_type='agent' rather than 'customer', so this query is unscoped.
+     * Returns empty string if the person row is missing or has no name/email.
+     */
+    private function compose_person_label( int $person_id ): string {
+        if ( $person_id <= 0 ) {
+            return '';
+        }
+        global $wpdb;
+        $row = $wpdb->get_row( $wpdb->prepare(
+            "SELECT first_name, last_name, email
+               FROM {$wpdb->prefix}fs_persons
+              WHERE id = %d",
+            $person_id
+        ) );
+        if ( ! $row ) {
+            return '';
+        }
+        return $this->compose_name_from_row( $row );
+    }
+
+    /**
+     * Shared name composition: "first last" → email → ''.
+     * No access to ORM-only fields like full_name.
+     */
+    private function compose_name_from_row( $row ): string {
+        $first = isset( $row->first_name ) ? trim( (string) $row->first_name ) : '';
+        $last  = isset( $row->last_name )  ? trim( (string) $row->last_name )  : '';
+        $name  = trim( $first . ' ' . $last );
+        if ( $name !== '' ) {
+            return $name;
+        }
+        $email = isset( $row->email ) ? trim( (string) $row->email ) : '';
+        return $email;
+    }
+}

sa-orchestration/includes/class-sa-admin.php

@@ -0,0 +1,957 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Read-only admin visibility layer.
+ *
+ * Top-level menu "SA-Orchestration" with three subpages:
+ *   - Demand Trace          (form + full trace including v0.2 closure fields)
+ *   - Recent Arbitrations   (last 20 arbitrations)
+ *   - Acceptance Events     (last 20 acceptance events)
+ *
+ * No editing. No new tables. Reuses SA_Orch_Rest::get_demand_trace() and
+ * SA_Orch_Acceptance helpers — no logic duplication.
+ */
+class SA_Orch_Admin {
+
+    const PARENT_SLUG  = 'sa-orchestration';
+    const ARB_SLUG     = 'sa-orchestration-arbitrations';
+    const EVENT_SLUG   = 'sa-orchestration-events';
+    const LLM_SLUG     = 'sa-orchestration-llm';
+    const CAP          = 'manage_options';
+
+    public static function register_menu() {
+        add_menu_page(
+            'SA-Orchestration',
+            'SA-Orchestration',
+            self::CAP,
+            self::PARENT_SLUG,
+            [ __CLASS__, 'render_trace' ],
+            'dashicons-networking',
+            80
+        );
+
+        // First submenu — reusing the parent slug renames the auto-generated
+        // submenu from "SA-Orchestration" to "Demand Trace".
+        add_submenu_page(
+            self::PARENT_SLUG,
+            'Demand Trace',
+            'Demand Trace',
+            self::CAP,
+            self::PARENT_SLUG,
+            [ __CLASS__, 'render_trace' ]
+        );
+
+        add_submenu_page(
+            self::PARENT_SLUG,
+            'Recent Arbitrations',
+            'Recent Arbitrations',
+            self::CAP,
+            self::ARB_SLUG,
+            [ __CLASS__, 'render_arbitrations' ]
+        );
+
+        add_submenu_page(
+            self::PARENT_SLUG,
+            'Acceptance Events',
+            'Acceptance Events',
+            self::CAP,
+            self::EVENT_SLUG,
+            [ __CLASS__, 'render_events' ]
+        );
+
+        add_submenu_page(
+            self::PARENT_SLUG,
+            'Language Model Providers',
+            'Language Model Providers',
+            self::CAP,
+            self::LLM_SLUG,
+            [ __CLASS__, 'render_llm_settings' ]
+        );
+    }
+
+    /* ---------- Demand Trace ---------- */
+
+    public static function render_trace() {
+        if ( ! current_user_can( self::CAP ) ) wp_die( 'Insufficient permissions.' );
+
+        $surface = isset( $_GET['demand_surface'] ) ? sanitize_text_field( wp_unslash( $_GET['demand_surface'] ) ) : '';
+        $ref     = isset( $_GET['demand_ref'] )     ? sanitize_text_field( wp_unslash( $_GET['demand_ref'] ) )     : '';
+
+        echo '<div class="wrap">';
+        echo '<h1>Demand Trace</h1>';
+        echo '<p>Walk a Demand through arbitration → plan_links → acceptance chain → closure verdicts.</p>';
+
+        // Picker form (replaces v0.6.x free-form text inputs).
+        self::render_picker_form( $surface, $ref );
+
+        if ( $surface !== '' && $ref !== '' ) {
+            // Reuse the REST handler. Bypasses URI routing (avoids URL-encoding fragility around `#`).
+            $req = new WP_REST_Request( 'GET' );
+            $req->set_url_params( [ 'surface' => $surface, 'ref' => $ref ] );
+            $resp = SA_Orch_Rest::get_demand_trace( $req );
+            $data = $resp->get_data();
+
+            self::render_trace_results( $data );
+        }
+
+        echo '</div>';
+    }
+
+    /* ---------- Demand Trace picker (v0.6.2) ---------- */
+
+    /**
+     * Demand picker:
+     *   - surface dropdown (closed enumeration of 4)
+     *   - quick-select strip (SA-ORCH-TEST fixtures pinned + last-traced)
+     *   - searchable browser of candidates for the selected surface
+     *   - manual ref entry as fallback (validated against known per-surface patterns)
+     *
+     * No new schema; no new endpoints. All candidate data is rendered inline
+     * as JSON for client-side filtering.
+     */
+    private static function render_picker_form( $surface, $ref ) {
+        $candidates = [
+            'fluent-support' => self::candidates_fluent_support(),
+            'fluent-boards'  => self::candidates_fluent_boards(),
+            'fluentcrm'      => self::candidates_fluentcrm(),
+            'derived'        => self::candidates_derived(),
+        ];
+        $quick = self::quick_select_demands( 10 );
+
+        $surface_labels = [
+            'fluent-support' => 'fluent-support — Fluent Support tickets',
+            'fluent-boards'  => 'fluent-boards — Fluent Boards tasks',
+            'fluentcrm'      => 'fluentcrm — FluentCRM subscribers',
+            'derived'        => 'derived — rowless / inferred demands',
+        ];
+
+        // Per-surface validation regex (mirrors SA_Orch_Bridge_Fluent::validate / resolve).
+        $patterns = [
+            'fluent-support' => '^ticket#\\d+$',
+            'fluent-boards'  => '^task#\\d+$',
+            'fluentcrm'      => '^subscriber#\\d+$',
+            'derived'        => '^derived#[A-Za-z0-9_\\-]+$',
+        ];
+
+        echo '<form method="get" action="' . esc_url( admin_url( 'admin.php' ) ) . '" id="sa-orch-trace-form">';
+        echo '<input type="hidden" name="page" value="' . esc_attr( self::PARENT_SLUG ) . '" />';
+
+        // ---------- Quick-select ----------
+        if ( ! empty( $quick ) ) {
+            echo '<div class="sa-orch-quick" style="margin:1em 0; padding:10px 14px; background:#f6f7f7; border:1px solid #dcdcde; max-width:900px">';
+            echo '<h3 style="margin:0 0 6px; font-size:13px; text-transform:uppercase; letter-spacing:0.05em; color:#50575e">Quick-select</h3>';
+            echo '<p class="description" style="margin:0 0 8px">SA-ORCH-TEST fixtures pinned, then the most recently traced Demands.</p>';
+            echo '<ul style="margin:0; padding:0; list-style:none">';
+            foreach ( $quick as $d ) {
+                $url = admin_url( 'admin.php?page=' . self::PARENT_SLUG
+                    . '&demand_surface=' . urlencode( $d['surface'] )
+                    . '&demand_ref='     . urlencode( $d['ref'] ) );
+                $tag = $d['is_test']
+                    ? '<span style="background:#fff2c2;border:1px solid #c9a300;border-radius:3px;padding:0 6px;font-size:11px;margin-right:6px;color:#7a5b00">TEST</span> '
+                    : '';
+                echo '<li style="padding:3px 0">'
+                    . $tag
+                    . '<a href="' . esc_url( $url ) . '">'
+                    . '<code>' . esc_html( $d['surface'] . ' / ' . $d['ref'] ) . '</code>'
+                    . ( $d['label'] !== '' ? ' — ' . esc_html( $d['label'] ) : '' )
+                    . '</a></li>';
+            }
+            echo '</ul></div>';
+        }
+
+        // ---------- Surface + ref ----------
+        echo '<table class="form-table" role="presentation" style="max-width:900px"><tbody>';
+
+        echo '<tr><th scope="row"><label for="demand_surface_select">Demand surface</label></th><td>';
+        echo '<select id="demand_surface_select" name="demand_surface" class="regular-text">';
+        echo '<option value="">— pick a surface —</option>';
+        foreach ( $surface_labels as $sid => $slabel ) {
+            echo '<option value="' . esc_attr( $sid ) . '"' . selected( $surface, $sid, false ) . '>'
+                . esc_html( $slabel ) . '</option>';
+        }
+        echo '</select>';
+        echo '<p class="description">Closed vocabulary; extending requires touching <code>SA_Orch_Bridge_Fluent</code>.</p>';
+        echo '</td></tr>';
+
+        echo '<tr><th scope="row"><label for="demand_ref_input">Demand ref</label></th><td>';
+        echo '<input type="text" id="demand_ref_input" name="demand_ref" value="' . esc_attr( $ref ) . '"';
+        echo ' class="regular-text" placeholder="pick from the list below, or type" autocomplete="off" />';
+        echo '<span id="sa-orch-ref-status" style="margin-left:10px; font-size:12px"></span>';
+        echo '<p class="description">Format depends on surface: <code>ticket#NNN</code> · <code>task#NNN</code> · <code>subscriber#NNN</code> · <code>derived#slug</code>. Type or pick.</p>';
+        echo '</td></tr>';
+
+        echo '</tbody></table>';
+
+        echo '<p class="submit" style="margin:6px 0 14px"><button type="submit" class="button button-primary">Trace</button></p>';
+
+        // ---------- Browser ----------
+        echo '<div class="sa-orch-browse" style="margin:0 0 1.5em; padding:10px 14px; background:#fff; border:1px solid #dcdcde; max-width:900px">';
+        echo '<h3 style="margin:0 0 8px; font-size:13px; text-transform:uppercase; letter-spacing:0.05em; color:#50575e">Browse candidates</h3>';
+        echo '<input type="search" id="sa-orch-filter" placeholder="filter by ID or label…" style="width:100%; max-width:560px" autocomplete="off" />';
+        echo '<div id="sa-orch-candidate-help" class="description" style="margin:6px 0">Pick a surface to load candidates.</div>';
+        echo '<ul id="sa-orch-candidate-list" style="margin:0; padding:0; list-style:none; max-height:360px; overflow:auto; border:1px solid #f0f0f1; border-radius:3px"></ul>';
+        echo '<p class="description" style="margin:8px 0 0"><em>Click any row to fill the Demand ref field. Ref is also free-form for advanced use; format is validated when you type.</em></p>';
+        echo '</div>';
+
+        // ---------- Inline JSON + JS ----------
+        $payload = [
+            'candidates' => $candidates,
+            'patterns'   => $patterns,
+        ];
+        echo '<script>window.SA_ORCH_PICKER = ' . wp_json_encode( $payload ) . ';</script>';
+        echo '<script>' . self::picker_inline_js() . '</script>';
+
+        echo '</form>';
+    }
+
+    /**
+     * Vanilla-JS controller for the picker. No jQuery dependency.
+     * Wires: surface change → repopulate browser; filter input → live filter;
+     * candidate click → fill ref input; ref input → pattern hint.
+     */
+    private static function picker_inline_js() {
+        return <<<'JS'
+(function () {
+  var data = window.SA_ORCH_PICKER || { candidates: {}, patterns: {} };
+  var surfaceSel = document.getElementById('demand_surface_select');
+  var refInput   = document.getElementById('demand_ref_input');
+  var filterInp  = document.getElementById('sa-orch-filter');
+  var listEl     = document.getElementById('sa-orch-candidate-list');
+  var helpEl     = document.getElementById('sa-orch-candidate-help');
+  var statusEl   = document.getElementById('sa-orch-ref-status');
+  if (!surfaceSel || !refInput || !listEl || !helpEl || !filterInp) return;
+
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, function (c) {
+      return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
+    });
+  }
+
+  function renderCandidates() {
+    var surface = surfaceSel.value;
+    var query   = (filterInp.value || '').trim().toLowerCase();
+    listEl.innerHTML = '';
+
+    if (!surface) {
+      helpEl.textContent = 'Pick a surface to load candidates.';
+      filterInp.disabled = true;
+      return;
+    }
+    filterInp.disabled = false;
+    var pool = (data.candidates || {})[surface] || [];
+    if (!pool.length) {
+      helpEl.textContent = 'No candidates known for this surface.';
+      return;
+    }
+
+    var matches = pool;
+    if (query) {
+      matches = pool.filter(function (c) {
+        return c.ref.toLowerCase().indexOf(query) !== -1
+          || (c.label || '').toLowerCase().indexOf(query) !== -1;
+      });
+    }
+
+    helpEl.textContent = matches.length + ' / ' + pool.length + ' candidate'
+      + (pool.length === 1 ? '' : 's')
+      + (query ? ' matching "' + query + '"' : '');
+
+    var frag = document.createDocumentFragment();
+    matches.slice(0, 200).forEach(function (c) {
+      var li = document.createElement('li');
+      li.style.padding = '5px 8px';
+      li.style.cursor = 'pointer';
+      li.style.borderBottom = '1px solid #f0f0f1';
+      li.style.lineHeight = '1.4';
+      var tag = c.is_test
+        ? '<span style="background:#fff2c2;border:1px solid #c9a300;border-radius:3px;padding:0 5px;font-size:11px;margin-right:6px;color:#7a5b00">TEST</span>'
+        : '';
+      li.innerHTML = tag + '<code>' + escapeHtml(c.ref) + '</code>'
+        + (c.label ? ' — ' + escapeHtml(c.label) : '');
+      li.addEventListener('mouseover', function () { li.style.background = '#f6f7f7'; });
+      li.addEventListener('mouseout',  function () { if (!li.classList.contains('selected')) li.style.background = ''; });
+      li.addEventListener('click', function () {
+        refInput.value = c.ref;
+        Array.prototype.forEach.call(
+          listEl.querySelectorAll('li.selected'),
+          function (e) { e.classList.remove('selected'); e.style.background = ''; }
+        );
+        li.classList.add('selected');
+        li.style.background = '#fff7c2';
+        validateRef();
+        refInput.focus();
+      });
+      frag.appendChild(li);
+    });
+    listEl.appendChild(frag);
+  }
+
+  function validateRef() {
+    var surface = surfaceSel.value;
+    var ref     = refInput.value.trim();
+    if (!surface || !ref) {
+      statusEl.textContent = '';
+      return;
+    }
+    var pattern = (data.patterns || {})[surface];
+    if (!pattern) {
+      statusEl.textContent = '';
+      return;
+    }
+    if ((new RegExp(pattern)).test(ref)) {
+      statusEl.textContent = '✓ valid format';
+      statusEl.style.color = '#0a7d24';
+    } else {
+      statusEl.textContent = '✗ does not match expected pattern';
+      statusEl.style.color = '#a02b1f';
+    }
+  }
+
+  surfaceSel.addEventListener('change', function () {
+    filterInp.value = '';
+    renderCandidates();
+    validateRef();
+  });
+  filterInp.addEventListener('input', renderCandidates);
+  refInput.addEventListener('input',  validateRef);
+
+  // Initial state (e.g. arrived via permalink with both fields preset).
+  renderCandidates();
+  validateRef();
+})();
+JS;
+    }
+
+    /* ---------- Candidate fetchers (per surface) ---------- */
+
+    /** Fluent Support tickets, SA-ORCH-TEST pinned first. Cap 50. */
+    private static function candidates_fluent_support() {
+        global $wpdb;
+        $rows = $wpdb->get_results(
+            "SELECT id, title FROM {$wpdb->prefix}fs_tickets
+             ORDER BY (title LIKE '[SA-ORCH-TEST]%') DESC, id DESC
+             LIMIT 50"
+        );
+        $out = [];
+        foreach ( (array) $rows as $r ) {
+            $title = (string) $r->title;
+            $out[] = [
+                'ref'     => 'ticket#' . (int) $r->id,
+                'label'   => self::truncate( $title, 80 ),
+                'is_test' => ( strpos( $title, '[SA-ORCH-TEST]' ) === 0 ),
+            ];
+        }
+        return $out;
+    }
+
+    /** Fluent Boards tasks, most-recent first. Cap 50. */
+    private static function candidates_fluent_boards() {
+        global $wpdb;
+        // Defensive: Fluent Boards may not be installed.
+        $exists = $wpdb->get_var( $wpdb->prepare( "SHOW TABLES LIKE %s", $wpdb->prefix . 'fbs_tasks' ) );
+        if ( ! $exists ) return [];
+        $rows = $wpdb->get_results(
+            "SELECT id, title FROM {$wpdb->prefix}fbs_tasks
+             ORDER BY id DESC LIMIT 50"
+        );
+        $out = [];
+        foreach ( (array) $rows as $r ) {
+            $title = (string) ( $r->title ?? '' );
+            $out[] = [
+                'ref'     => 'task#' . (int) $r->id,
+                'label'   => self::truncate( $title, 80 ),
+                'is_test' => ( strpos( $title, '[SA-ORCH-TEST]' ) === 0 ),
+            ];
+        }
+        return $out;
+    }
+
+    /** FluentCRM subscribers, most-recent first. Cap 50. Label = full_name|email. */
+    private static function candidates_fluentcrm() {
+        global $wpdb;
+        $exists = $wpdb->get_var( $wpdb->prepare( "SHOW TABLES LIKE %s", $wpdb->prefix . 'fc_subscribers' ) );
+        if ( ! $exists ) return [];
+        $rows = $wpdb->get_results(
+            "SELECT id, full_name, email FROM {$wpdb->prefix}fc_subscribers
+             ORDER BY id DESC LIMIT 50"
+        );
+        $out = [];
+        foreach ( (array) $rows as $r ) {
+            $name  = trim( (string) ( $r->full_name ?? '' ) );
+            $email = (string) ( $r->email ?? '' );
+            $label = $name !== '' ? ( $name . ( $email ? " <{$email}>" : '' ) ) : $email;
+            $out[] = [
+                'ref'     => 'subscriber#' . (int) $r->id,
+                'label'   => self::truncate( $label, 80 ),
+                'is_test' => false,
+            ];
+        }
+        return $out;
+    }
+
+    /**
+     * 'derived' surface has no underlying surface table — list every distinct
+     * derived demand_ref ever recorded in arbitrations or acceptance events.
+     */
+    private static function candidates_derived() {
+        global $wpdb;
+        $arb = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'arbitration';
+        $evt = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'acceptance_event';
+        $rows = $wpdb->get_results(
+            "SELECT demand_ref, MAX(last_at) AS last_at FROM (
+                 SELECT demand_ref, MAX(created_at)  AS last_at FROM {$arb} WHERE demand_surface='derived' GROUP BY demand_ref
+                 UNION ALL
+                 SELECT demand_ref, MAX(observed_at) AS last_at FROM {$evt} WHERE demand_surface='derived' GROUP BY demand_ref
+             ) sub
+             GROUP BY demand_ref
+             ORDER BY last_at DESC LIMIT 50"
+        );
+        $out = [];
+        foreach ( (array) $rows as $r ) {
+            $out[] = [
+                'ref'     => (string) $r->demand_ref,
+                'label'   => '(derived demand, no surface row)',
+                'is_test' => false,
+            ];
+        }
+        return $out;
+    }
+
+    /**
+     * Quick-select list: SA-ORCH-TEST tickets pinned, then most-recently-traced
+     * demands across all surfaces (by max(arbitration.created_at, event.observed_at)).
+     */
+    private static function quick_select_demands( $limit = 10 ) {
+        global $wpdb;
+        $arb = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'arbitration';
+        $evt = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'acceptance_event';
+
+        $rows = $wpdb->get_results(
+            "SELECT demand_surface, demand_ref, MAX(last_at) AS last_at FROM (
+                 SELECT demand_surface, demand_ref, MAX(created_at)  AS last_at FROM {$arb} GROUP BY demand_surface, demand_ref
+                 UNION ALL
+                 SELECT demand_surface, demand_ref, MAX(observed_at) AS last_at FROM {$evt} GROUP BY demand_surface, demand_ref
+             ) sub
+             GROUP BY demand_surface, demand_ref
+             ORDER BY last_at DESC LIMIT 30"
+        );
+        if ( empty( $rows ) ) return [];
+
+        // Resolve labels + is_test per row.
+        $out = [];
+        foreach ( $rows as $r ) {
+            $surface = (string) $r->demand_surface;
+            $ref     = (string) $r->demand_ref;
+            list( $label, $is_test ) = self::resolve_label( $surface, $ref );
+            $out[] = [
+                'surface' => $surface,
+                'ref'     => $ref,
+                'label'   => $label,
+                'is_test' => $is_test,
+                'last_at' => (string) $r->last_at,
+            ];
+        }
+
+        // Pin SA-ORCH-TEST first; preserve last_at ordering within each group.
+        usort( $out, function ( $a, $b ) {
+            if ( $a['is_test'] !== $b['is_test'] ) return $a['is_test'] ? -1 : 1;
+            return strcmp( $b['last_at'], $a['last_at'] );
+        } );
+
+        return array_slice( $out, 0, (int) $limit );
+    }
+
+    /** Resolve a (surface, ref) to a human label + is_test flag. Best-effort, tolerant of missing tables. */
+    private static function resolve_label( $surface, $ref ) {
+        global $wpdb;
+
+        if ( $surface === 'fluent-support' && preg_match( '/^ticket#(\d+)$/', $ref, $m ) ) {
+            $title = (string) $wpdb->get_var( $wpdb->prepare(
+                "SELECT title FROM {$wpdb->prefix}fs_tickets WHERE id=%d", (int) $m[1]
+            ) );
+            return [ self::truncate( $title, 80 ), strpos( $title, '[SA-ORCH-TEST]' ) === 0 ];
+        }
+        if ( $surface === 'fluent-boards' && preg_match( '/^task#(\d+)$/', $ref, $m ) ) {
+            if ( $wpdb->get_var( $wpdb->prepare( "SHOW TABLES LIKE %s", $wpdb->prefix . 'fbs_tasks' ) ) ) {
+                $title = (string) $wpdb->get_var( $wpdb->prepare(
+                    "SELECT title FROM {$wpdb->prefix}fbs_tasks WHERE id=%d", (int) $m[1]
+                ) );
+                return [ self::truncate( $title, 80 ), strpos( $title, '[SA-ORCH-TEST]' ) === 0 ];
+            }
+        }
+        if ( $surface === 'fluentcrm' && preg_match( '/^subscriber#(\d+)$/', $ref, $m ) ) {
+            if ( $wpdb->get_var( $wpdb->prepare( "SHOW TABLES LIKE %s", $wpdb->prefix . 'fc_subscribers' ) ) ) {
+                $row = $wpdb->get_row( $wpdb->prepare(
+                    "SELECT full_name, email FROM {$wpdb->prefix}fc_subscribers WHERE id=%d", (int) $m[1]
+                ) );
+                if ( $row ) {
+                    $name  = trim( (string) $row->full_name );
+                    $email = (string) $row->email;
+                    $label = $name !== '' ? ( $name . ( $email ? " <{$email}>" : '' ) ) : $email;
+                    return [ self::truncate( $label, 80 ), false ];
+                }
+            }
+        }
+        if ( $surface === 'derived' ) {
+            return [ '(derived demand, no surface row)', false ];
+        }
+        return [ '', false ];
+    }
+
+    private static function truncate( $s, $n ) {
+        $s = (string) $s;
+        if ( function_exists( 'mb_strlen' ) && function_exists( 'mb_substr' ) ) {
+            return mb_strlen( $s ) > $n ? ( mb_substr( $s, 0, $n - 1 ) . '…' ) : $s;
+        }
+        return strlen( $s ) > $n ? ( substr( $s, 0, $n - 1 ) . '…' ) : $s;
+    }
+
+    private static function render_trace_results( array $data ) {
+        $arbs   = $data['arbitrations'] ?? [];
+        $links  = $data['plan_links']   ?? [];
+        $events = $data['acceptance']   ?? [];
+
+        echo '<h2>Closure</h2>';
+        echo '<table class="widefat striped" style="max-width:600px"><tbody>';
+        echo '<tr><th scope="row" style="width:40%">closure_state_basic</th><td><code>' . esc_html( (string) ( $data['closure_state_basic'] ?? '' ) ) . '</code></td></tr>';
+        echo '<tr><th scope="row">closure_state_role_aware</th><td><code>' . esc_html( (string) ( $data['closure_state_role_aware'] ?? '' ) ) . '</code></td></tr>';
+        $auth      = $data['closure_authority_valid'] ?? null;
+        $auth_disp = $auth === null ? 'null' : ( $auth ? 'true' : 'false' );
+        echo '<tr><th scope="row">closure_authority_valid</th><td><code>' . esc_html( $auth_disp ) . '</code></td></tr>';
+        echo '</tbody></table>';
+
+        // === Deterministic Trace Audit (layer 2 — rules-based) ===
+        self::render_reasoning_review( $data );
+
+        echo '<h2>Arbitrations <span class="count">(' . count( $arbs ) . ')</span></h2>';
+        if ( empty( $arbs ) ) {
+            echo '<p><em>No arbitrations recorded for this demand.</em></p>';
+        } else {
+            echo '<table class="widefat striped"><thead><tr>';
+            echo '<th>ID</th><th>Hash</th><th>Projection Type</th><th>Truth Class</th><th>Actor</th><th>Correlation</th><th>Created (UTC)</th><th>Asterion</th>';
+            echo '</tr></thead><tbody>';
+            foreach ( $arbs as $a ) {
+                echo '<tr>';
+                echo '<td>' . (int) $a->id . '</td>';
+                echo '<td><code>' . esc_html( substr( (string) $a->hash, 0, 12 ) ) . '…</code></td>';
+                echo '<td>' . esc_html( (string) $a->projection_type ) . '</td>';
+                echo '<td>' . esc_html( (string) $a->truth_class ) . '</td>';
+                echo '<td>' . esc_html( (string) ( $a->actor_user_id ?? '—' ) ) . '</td>';
+                echo '<td><code>' . esc_html( substr( (string) $a->correlation_id, 0, 8 ) ) . '…</code></td>';
+                echo '<td>' . esc_html( (string) $a->created_at ) . '</td>';
+                echo '<td><code>' . esc_html( (string) $a->asterion_path ) . '</code></td>';
+                echo '</tr>';
+                echo '<tr><td></td><td colspan="7"><strong>Rationale:</strong> ' . esc_html( (string) $a->rationale ) . '</td></tr>';
+            }
+            echo '</tbody></table>';
+        }
+
+        echo '<h2>Plan Links <span class="count">(' . count( $links ) . ')</span></h2>';
+        if ( empty( $links ) ) {
+            echo '<p><em>No plan links — this Demand has no Plan refs (consistent with <code>scope-direct-no-plan</code> or <code>no-plan</code> arbitration).</em></p>';
+        } else {
+            echo '<table class="widefat striped"><thead><tr>';
+            echo '<th>ID</th><th>Arbitration</th><th>Plan Surface</th><th>Plan Ref</th><th>Link Kind</th><th>Created (UTC)</th>';
+            echo '</tr></thead><tbody>';
+            foreach ( $links as $l ) {
+                echo '<tr>';
+                echo '<td>' . (int) $l->id . '</td>';
+                echo '<td>' . (int) $l->arbitration_id . '</td>';
+                echo '<td>' . esc_html( (string) $l->plan_surface ) . '</td>';
+                echo '<td><code>' . esc_html( (string) $l->plan_ref ) . '</code></td>';
+                echo '<td>' . esc_html( (string) $l->link_kind ) . '</td>';
+                echo '<td>' . esc_html( (string) $l->created_at ) . '</td>';
+                echo '</tr>';
+            }
+            echo '</tbody></table>';
+        }
+
+        echo '<h2>Acceptance Events <span class="count">(' . count( $events ) . ')</span></h2>';
+        if ( empty( $events ) ) {
+            echo '<p><em>No acceptance events.</em></p>';
+        } else {
+            echo '<table class="widefat striped"><thead><tr>';
+            echo '<th>ID</th><th>Event Type</th><th>Actor Role</th><th>Actor</th><th>Truth Class</th><th>Prior</th><th>Observed (UTC)</th><th>Asterion</th>';
+            echo '</tr></thead><tbody>';
+            foreach ( $events as $e ) {
+                echo '<tr>';
+                echo '<td>' . (int) $e->id . '</td>';
+                echo '<td>' . esc_html( (string) $e->event_type ) . '</td>';
+                echo '<td>' . esc_html( (string) $e->actor_role ) . '</td>';
+                echo '<td>' . esc_html( (string) ( $e->actor_user_id ?? '—' ) ) . '</td>';
+                echo '<td>' . esc_html( (string) $e->truth_class ) . '</td>';
+                echo '<td>' . esc_html( (string) ( $e->prior_event_id ?? '—' ) ) . '</td>';
+                echo '<td>' . esc_html( (string) $e->observed_at ) . '</td>';
+                echo '<td><code>' . esc_html( (string) $e->asterion_path ) . '</code></td>';
+                echo '</tr>';
+                if ( ! empty( $e->details ) ) {
+                    echo '<tr><td></td><td colspan="7"><strong>Details:</strong> ' . esc_html( (string) $e->details ) . '</td></tr>';
+                }
+            }
+            echo '</tbody></table>';
+        }
+    }
+
+    /**
+     * Deterministic Trace Audit block.
+     *
+     * Local rules-based audit over the trace data. No API calls, no LLM, no
+     * persistence. Recomputed on every page load.
+     *
+     * This is the FLOOR of the review stack:
+     *   1. Trace data
+     *   2. Deterministic Trace Audit  ← this section
+     *   3. Strategy LLM Review        (future; will sit above this audit)
+     *   4. Human arbitration          (final meaning; always wins)
+     */
+    private static function render_reasoning_review( array $data ) {
+        $r = SA_Orch_Reasoning::evaluate( $data );
+
+        echo '<h2>Deterministic Trace Audit <span class="count">(rules-based, mode: ' . esc_html( (string) ( $r['mode'] ?? 'deterministic' ) ) . ')</span></h2>';
+        echo '<p><em>Local rules-based audit — repeatable, no API, no LLM. Computed on each page load. Floor of a four-layer stack: ';
+        echo '<strong>(1) Trace data</strong> &rarr; <strong>(2) this Deterministic Trace Audit</strong> &rarr; <strong>(3) Strategy LLM Review</strong> (future) &rarr; <strong>(4) Human arbitration</strong> (final).</em></p>';
+
+        $color_map = [ 'high' => '#0a7d24', 'medium' => '#a76b00', 'low' => '#a02b1f', 'n/a' => '#666' ];
+        $color     = $color_map[ $r['closure_confidence'] ] ?? '#666';
+
+        echo '<table class="widefat striped" style="max-width:900px"><tbody>';
+
+        echo '<tr><th scope="row" style="width:25%">Summary</th><td>' . esc_html( $r['summary'] ) . '</td></tr>';
+
+        echo '<tr><th scope="row">Closure confidence</th><td>';
+        echo '<strong style="color:' . esc_attr( $color ) . '">' . esc_html( strtoupper( (string) $r['closure_confidence'] ) ) . '</strong>';
+        echo ' &mdash; ' . esc_html( $r['closure_confidence_explanation'] );
+        echo '</td></tr>';
+
+        // Needs Human Arbitration — prominent row
+        echo '<tr><th scope="row">Needs Human Arbitration</th><td>';
+        if ( ! empty( $r['needs_human_arbitration'] ) ) {
+            echo '<strong style="color:#a02b1f">&#9888; YES &mdash; ' . esc_html( (string) $r['human_arbitration_message'] ) . '</strong>';
+            echo '<p style="margin:6px 0 0">Triggered by:</p>';
+            echo '<ul style="margin:0; padding-left:1.2em">';
+            foreach ( (array) $r['human_arbitration_triggers'] as $t ) {
+                echo '<li>' . esc_html( $t ) . '</li>';
+            }
+            echo '</ul>';
+        } else {
+            echo '<em>No &mdash; none of the deterministic escalation triggers fired.</em>';
+        }
+        echo '</td></tr>';
+
+        $render_list = function ( $label, $items ) {
+            echo '<tr><th scope="row">' . esc_html( $label ) . '</th><td>';
+            if ( empty( $items ) ) {
+                echo '<em>(none)</em>';
+            } else {
+                echo '<ul style="margin:0; padding-left:1.2em">';
+                foreach ( $items as $i ) {
+                    echo '<li>' . esc_html( $i ) . '</li>';
+                }
+                echo '</ul>';
+            }
+            echo '</td></tr>';
+        };
+
+        $render_list( 'Inconsistencies',        $r['inconsistencies'] );
+        $render_list( 'Potential scope drift',  $r['scope_drift'] );
+        $render_list( 'Notes',                  $r['notes'] );
+
+        echo '</tbody></table>';
+
+        echo '<p style="margin-top:8px"><em>Layer 3 — Strategy LLM Review — sits below this section. The audit remains as a sanity-check / fallback layer underneath any LLM verdict.</em></p>';
+
+        // --- Strategy Review (v0.5) ---
+        self::render_strategy_review( $data, $r );
+    }
+
+    /**
+     * Strategy LLM Review block (layer 3).
+     *
+     * Consumes the trace + the deterministic audit; delegates to the active
+     * provider via SA_Orch_Strategy::review(). Strategy Review is advisory:
+     * it cannot override closure_state or needs_human_arbitration.
+     */
+    private static function render_strategy_review( array $data, array $deterministic_audit ) {
+        $strategy = SA_Orch_Strategy::review( $data, $deterministic_audit );
+
+        $provider_id        = (string) ( $strategy['provider_id']            ?? 'simulated' );
+        $provider_name      = (string) ( $strategy['provider_name']          ?? 'Simulated (no API call)' );
+        $configured_id      = (string) ( $strategy['configured_provider_id'] ?? $provider_id );
+        $configured_name    = (string) ( $strategy['configured_provider_name'] ?? $provider_name );
+        $fallback_used      = ! empty( $strategy['fallback_used'] );
+        $provider_err       = $strategy['provider_error'] ?? null;
+
+        $heading_suffix = $fallback_used
+            ? '(layer 3 — used: ' . esc_html( $provider_id ) . ', configured: ' . esc_html( $configured_id ) . ' &mdash; <strong style="color:#a76b00">FALLBACK</strong>)'
+            : '(layer 3 — provider: ' . esc_html( $provider_id ) . ')';
+        echo '<h2>Strategy Review (simulated LLM) <span class="count">' . $heading_suffix . '</span></h2>';
+        echo '<p><em>Layer 3 of the review stack. Provider in use: <code>' . esc_html( $provider_name ) . '</code>. ';
+        if ( $fallback_used ) {
+            echo 'Configured provider (<code>' . esc_html( $configured_name ) . '</code>) failed and was replaced by the simulated fallback. ';
+        }
+        echo 'Compares its interpretation against the deterministic audit. ';
+        echo '<strong>Strategy Review cannot override <code>closure_state</code> or the <code>needs_human_arbitration</code> flag</strong> — those remain governed by the deterministic audit and ultimately by human arbitration.</em></p>';
+
+        if ( $provider_err ) {
+            echo '<div class="notice notice-warning"><p><strong>Provider error (configured: <code>' . esc_html( $configured_id ) . '</code>):</strong> ' . esc_html( $provider_err ) . ' &mdash; fell back to <code>simulated</code>.</p></div>';
+        }
+
+        // Color hints
+        $color_map_conf  = [ 'high' => '#0a7d24', 'medium' => '#a76b00', 'low' => '#a02b1f' ];
+        $color_map_agree = [ 'true' => '#0a7d24', 'partial' => '#a76b00', 'false' => '#a02b1f' ];
+        $strat_conf      = (string) ( $strategy['confidence']            ?? 'low' );
+        $strat_agree     = (string) ( $strategy['agreement_with_audit']  ?? 'partial' );
+        $strat_color     = $color_map_conf[ $strat_conf ]   ?? '#666';
+        $agree_color     = $color_map_agree[ $strat_agree ] ?? '#666';
+
+        echo '<table class="widefat striped" style="max-width:900px"><tbody>';
+
+        echo '<tr><th scope="row" style="width:25%">Summary</th><td>' . esc_html( (string) ( $strategy['summary'] ?? '' ) ) . '</td></tr>';
+
+        echo '<tr><th scope="row">Agreement with Deterministic Audit</th><td>';
+        echo '<strong style="color:' . esc_attr( $agree_color ) . '">' . esc_html( strtoupper( $strat_agree ) ) . '</strong>';
+        echo '</td></tr>';
+
+        echo '<tr><th scope="row">Additional risks (not caught by audit)</th><td>';
+        $risks = (array) ( $strategy['additional_risks'] ?? [] );
+        if ( empty( $risks ) ) {
+            echo '<em>(none)</em>';
+        } else {
+            echo '<ul style="margin:0; padding-left:1.2em">';
+            foreach ( $risks as $r ) {
+                echo '<li>' . esc_html( (string) $r ) . '</li>';
+            }
+            echo '</ul>';
+        }
+        echo '</td></tr>';
+
+        echo '<tr><th scope="row">Suggested next action</th><td>' . esc_html( (string) ( $strategy['suggested_next_action'] ?? '' ) ) . '</td></tr>';
+
+        echo '<tr><th scope="row">Confidence</th><td>';
+        echo '<strong style="color:' . esc_attr( $strat_color ) . '">' . esc_html( strtoupper( $strat_conf ) ) . '</strong>';
+        echo '</td></tr>';
+
+        echo '</tbody></table>';
+
+        // Visual side-by-side comparison
+        self::render_audit_strategy_comparison( $deterministic_audit, $strategy );
+    }
+
+    /**
+     * Side-by-side comparison of Deterministic Audit (layer 2) and Strategy Review (layer 3).
+     */
+    private static function render_audit_strategy_comparison( array $audit, array $strategy ) {
+        $color_map_conf  = [ 'high' => '#0a7d24', 'medium' => '#a76b00', 'low' => '#a02b1f', 'n/a' => '#666' ];
+
+        $audit_conf  = (string) ( $audit['closure_confidence']    ?? 'n/a' );
+        $strat_conf  = (string) ( $strategy['confidence']         ?? 'low' );
+        $audit_inc   = count( (array) ( $audit['inconsistencies'] ?? [] ) );
+        $audit_drift = count( (array) ( $audit['scope_drift']     ?? [] ) );
+        $strat_extra = count( (array) ( $strategy['additional_risks'] ?? [] ) );
+        $needs_hum   = ! empty( $audit['needs_human_arbitration'] );
+
+        echo '<h3 style="margin-top:1.2em">Deterministic Audit &harr; Strategy Review (side-by-side)</h3>';
+        echo '<table class="widefat striped" style="max-width:900px"><thead><tr>';
+        echo '<th style="width:25%">&nbsp;</th>';
+        echo '<th>Deterministic Audit (layer 2)</th>';
+        echo '<th>Strategy Review (layer 3)</th>';
+        echo '</tr></thead><tbody>';
+
+        $audit_conf_color = $color_map_conf[ $audit_conf ] ?? '#666';
+        $strat_conf_color = $color_map_conf[ $strat_conf ] ?? '#666';
+
+        echo '<tr><th scope="row">Confidence</th>';
+        echo '<td><strong style="color:' . esc_attr( $audit_conf_color ) . '">' . esc_html( strtoupper( $audit_conf ) ) . '</strong></td>';
+        echo '<td><strong style="color:' . esc_attr( $strat_conf_color ) . '">' . esc_html( strtoupper( $strat_conf ) ) . '</strong></td>';
+        echo '</tr>';
+
+        echo '<tr><th scope="row">Findings counted</th>';
+        echo '<td>' . (int) $audit_inc . ' inconsistenc' . ( $audit_inc === 1 ? 'y' : 'ies' ) . ', ' . (int) $audit_drift . ' scope-drift indicator' . ( $audit_drift === 1 ? '' : 's' ) . '</td>';
+        echo '<td>' . (int) $strat_extra . ' additional risk' . ( $strat_extra === 1 ? '' : 's' ) . '</td>';
+        echo '</tr>';
+
+        echo '<tr><th scope="row">Closure authority</th>';
+        echo '<td>' . ( $needs_hum ? '<strong>flagged needs_human_arbitration = YES</strong>' : 'no escalation flag' ) . '</td>';
+        echo '<td><em>cannot override the audit</em></td>';
+        echo '</tr>';
+
+        echo '<tr><th scope="row">Mode / character</th>';
+        echo '<td>rules-based, repeatable</td>';
+        echo '<td>interpretive, narrative (' . esc_html( (string) ( $strategy['provider_id'] ?? 'simulated' ) ) . ')</td>';
+        echo '</tr>';
+
+        echo '</tbody></table>';
+
+        echo '<p style="margin-top:8px"><em>Reminder: <code>closure_state_basic</code>, <code>closure_state_role_aware</code>, <code>closure_authority_valid</code>, and <code>needs_human_arbitration</code> are governed by the deterministic audit (layer 2) and ultimately by human arbitration (layer 4). Strategy Review is advisory.</em></p>';
+    }
+
+    /* ---------- Recent Arbitrations ---------- */
+
+    public static function render_arbitrations() {
+        if ( ! current_user_can( self::CAP ) ) wp_die( 'Insufficient permissions.' );
+        global $wpdb;
+        $p = $wpdb->prefix . SA_ORCH_DB_PREFIX;
+
+        $rows = $wpdb->get_results(
+            "SELECT id, demand_surface, demand_ref, projection_type, truth_class, actor_user_id, created_at
+             FROM {$p}arbitration
+             ORDER BY created_at DESC, id DESC LIMIT 20"
+        );
+
+        echo '<div class="wrap">';
+        echo '<h1>Recent Arbitrations</h1>';
+        echo '<p>Last 20 arbitration records, newest first. Click <strong>Trace</strong> to walk the full chain.</p>';
+
+        if ( empty( $rows ) ) {
+            echo '<p><em>No arbitrations recorded yet.</em></p>';
+        } else {
+            echo '<table class="widefat striped"><thead><tr>';
+            echo '<th>ID</th><th>Demand</th><th>Projection Type</th><th>Truth Class</th><th>Actor</th><th>Created (UTC)</th><th>Action</th>';
+            echo '</tr></thead><tbody>';
+            foreach ( $rows as $r ) {
+                $trace_url = admin_url( 'admin.php?page=' . self::PARENT_SLUG
+                    . '&demand_surface=' . urlencode( $r->demand_surface )
+                    . '&demand_ref='     . urlencode( $r->demand_ref ) );
+                echo '<tr>';
+                echo '<td>' . (int) $r->id . '</td>';
+                echo '<td><code>' . esc_html( $r->demand_surface . ' / ' . $r->demand_ref ) . '</code></td>';
+                echo '<td>' . esc_html( (string) $r->projection_type ) . '</td>';
+                echo '<td>' . esc_html( (string) $r->truth_class ) . '</td>';
+                echo '<td>' . esc_html( (string) ( $r->actor_user_id ?? '—' ) ) . '</td>';
+                echo '<td>' . esc_html( (string) $r->created_at ) . '</td>';
+                echo '<td><a href="' . esc_url( $trace_url ) . '">Trace</a></td>';
+                echo '</tr>';
+            }
+            echo '</tbody></table>';
+        }
+
+        echo '</div>';
+    }
+
+    /* ---------- Language Model Providers (settings page) ---------- */
+
+    public static function render_llm_settings() {
+        if ( ! current_user_can( self::CAP ) ) wp_die( 'Insufficient permissions.' );
+
+        $message = '';
+        if ( $_SERVER['REQUEST_METHOD'] === 'POST' ) {
+            check_admin_referer( 'sa_orch_llm_settings' );
+            SA_Orch_LLM_Settings::save( wp_unslash( $_POST ) );
+            $message = 'Settings saved.';
+        }
+
+        $settings = SA_Orch_LLM_Settings::get();
+        $choices  = SA_Orch_LLM_Providers::get_provider_choices();
+        $token_label = SA_Orch_LLM_Settings::token_status_label();
+
+        echo '<div class="wrap">';
+        echo '<h1>Language Model Providers</h1>';
+
+        if ( $message ) {
+            echo '<div class="notice notice-success is-dismissible"><p>' . esc_html( $message ) . '</p></div>';
+        }
+
+        echo '<p>Configure the provider used by the Strategy Review (layer 3 of the review stack: trace data &rarr; deterministic audit &rarr; <strong>strategy review</strong> &rarr; human arbitration).</p>';
+        echo '<p><strong>Local-dev posture:</strong> secrets are stored in <code>wp_options</code>. Tokens are never displayed back &mdash; saving with a blank token field preserves the existing value. This storage layer is the attachment seam for a future SA-Core key vault; replacing it later will not change the consumer surface.</p>';
+
+        echo '<form method="post">';
+        wp_nonce_field( 'sa_orch_llm_settings' );
+
+        echo '<table class="form-table" role="presentation"><tbody>';
+
+        echo '<tr><th scope="row">Enabled</th><td>';
+        echo '<label><input type="checkbox" name="enabled" value="1"' . checked( ! empty( $settings['enabled'] ), true, false ) . ' /> Use the selected provider for Strategy Review.</label>';
+        echo '<p class="description">When unchecked, Strategy Review falls back to the simulated provider regardless of the dropdown selection.</p>';
+        echo '</td></tr>';
+
+        echo '<tr><th scope="row"><label for="sa_orch_provider">Provider</label></th><td>';
+        echo '<select id="sa_orch_provider" name="provider">';
+        foreach ( $choices as $id => $label ) {
+            echo '<option value="' . esc_attr( $id ) . '"' . selected( $settings['provider'], $id, false ) . '>' . esc_html( $label ) . '</option>';
+        }
+        echo '</select>';
+        echo '<p class="description">Only <code>simulated</code> is functional in v0.5. Other providers are listed as inert placeholders to surface the seam.</p>';
+        echo '</td></tr>';
+
+        echo '<tr><th scope="row"><label for="sa_orch_model">Model name</label></th><td>';
+        echo '<input type="text" id="sa_orch_model" name="model" value="' . esc_attr( $settings['model'] ) . '" class="regular-text" placeholder="e.g. gpt-4o, claude-sonnet-4-5, llama-3.1-70b" />';
+        echo '<p class="description">Free-form. Future providers may validate against their own catalog.</p>';
+        echo '</td></tr>';
+
+        echo '<tr><th scope="row"><label for="sa_orch_api_base_url">API base URL</label></th><td>';
+        echo '<input type="text" id="sa_orch_api_base_url" name="api_base_url" value="' . esc_attr( $settings['api_base_url'] ) . '" class="regular-text" placeholder="e.g. https://api.openai.com/v1" />';
+        echo '<p class="description">Used by HTTP-backed providers. Ignored by the simulated provider.</p>';
+        echo '</td></tr>';
+
+        echo '<tr><th scope="row"><label for="sa_orch_api_token">API token / key</label></th><td>';
+        echo '<input type="password" id="sa_orch_api_token" name="api_token" value="" class="regular-text" autocomplete="new-password" placeholder="enter token to set or update; leave blank to preserve" />';
+        echo '<p class="description">' . esc_html( $token_label ) . ' Tokens are stored in <code>wp_options</code> for local dev only and are never displayed back through the UI. Leave the field blank to keep the existing value.</p>';
+        echo '</td></tr>';
+
+        echo '</tbody></table>';
+
+        echo '<p class="submit"><button type="submit" class="button button-primary">Save Settings</button></p>';
+        echo '</form>';
+
+        echo '<hr />';
+
+        echo '<h2>Status</h2>';
+        echo '<table class="widefat striped" style="max-width:600px"><tbody>';
+        echo '<tr><th scope="row" style="width:40%">Active provider (resolved)</th><td><code>' . esc_html( SA_Orch_LLM_Providers::get_active_provider()->id() ) . '</code></td></tr>';
+        echo '<tr><th scope="row">Settings.enabled</th><td><code>' . ( ! empty( $settings['enabled'] ) ? 'true' : 'false' ) . '</code></td></tr>';
+        echo '<tr><th scope="row">Settings.provider</th><td><code>' . esc_html( (string) $settings['provider'] ) . '</code></td></tr>';
+        echo '<tr><th scope="row">Settings.model</th><td><code>' . esc_html( (string) $settings['model'] ?: '—' ) . '</code></td></tr>';
+        echo '<tr><th scope="row">Settings.api_base_url</th><td><code>' . esc_html( (string) $settings['api_base_url'] ?: '—' ) . '</code></td></tr>';
+        echo '<tr><th scope="row">Settings.api_token</th><td>' . ( SA_Orch_LLM_Settings::has_token() ? '<code>***** (set)</code>' : '<code>(not set)</code>' ) . '</td></tr>';
+        echo '</tbody></table>';
+
+        echo '<p style="margin-top:8px"><em>v0.5 ships with the <code>simulated</code> provider only — no external API call is made by this plugin under any settings configuration. Adding real providers (OpenAI, Anthropic, local model endpoint, custom HTTP) is a matter of implementing <code>SA_Orch_LLM_Provider_Interface</code> and adding a case to <code>SA_Orch_LLM_Providers::instantiate()</code>.</em></p>';
+
+        echo '</div>';
+    }
+
+    /* ---------- Acceptance Events ---------- */
+
+    public static function render_events() {
+        if ( ! current_user_can( self::CAP ) ) wp_die( 'Insufficient permissions.' );
+        global $wpdb;
+        $p = $wpdb->prefix . SA_ORCH_DB_PREFIX;
+
+        $rows = $wpdb->get_results(
+            "SELECT id, event_type, actor_role, demand_surface, demand_ref, observed_at, truth_class, actor_user_id
+             FROM {$p}acceptance_event
+             ORDER BY observed_at DESC, id DESC LIMIT 20"
+        );
+
+        echo '<div class="wrap">';
+        echo '<h1>Acceptance Events</h1>';
+        echo '<p>Last 20 acceptance events, newest first. Append-only — these rows are never updated or deleted.</p>';
+
+        if ( empty( $rows ) ) {
+            echo '<p><em>No acceptance events recorded yet.</em></p>';
+        } else {
+            echo '<table class="widefat striped"><thead><tr>';
+            echo '<th>ID</th><th>Event Type</th><th>Actor Role</th><th>Actor</th><th>Demand</th><th>Truth Class</th><th>Observed (UTC)</th><th>Action</th>';
+            echo '</tr></thead><tbody>';
+            foreach ( $rows as $r ) {
+                $trace_url = admin_url( 'admin.php?page=' . self::PARENT_SLUG
+                    . '&demand_surface=' . urlencode( $r->demand_surface )
+                    . '&demand_ref='     . urlencode( $r->demand_ref ) );
+                echo '<tr>';
+                echo '<td>' . (int) $r->id . '</td>';
+                echo '<td>' . esc_html( (string) $r->event_type ) . '</td>';
+                echo '<td>' . esc_html( (string) $r->actor_role ) . '</td>';
+                echo '<td>' . esc_html( (string) ( $r->actor_user_id ?? '—' ) ) . '</td>';
+                echo '<td><code>' . esc_html( $r->demand_surface . ' / ' . $r->demand_ref ) . '</code></td>';
+                echo '<td>' . esc_html( (string) $r->truth_class ) . '</td>';
+                echo '<td>' . esc_html( (string) $r->observed_at ) . '</td>';
+                echo '<td><a href="' . esc_url( $trace_url ) . '">Trace</a></td>';
+                echo '</tr>';
+            }
+            echo '</tbody></table>';
+        }
+
+        echo '</div>';
+    }
+}

sa-orchestration/includes/class-sa-arbitration.php

@@ -0,0 +1,174 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+class SA_Orch_Arbitration {
+
+    /**
+     * Write an arbitration record + optional plan_link rows.
+     *
+     * Required:
+     *   - demand_surface  (string)  e.g. 'fluent-support'
+     *   - demand_ref      (string)  e.g. 'ticket#12'
+     *   - rationale       (non-empty string)
+     *   - projection_type (string)  e.g. 'scope-direct-no-plan'
+     *
+     * Optional:
+     *   - actor_user_id  (int; default current user)
+     *   - correlation_id (string; default UUID v4)
+     *   - causation_id   (string|null)
+     *   - truth_class    (string; default 'canonical')
+     *   - plan_refs      (array of [ surface, ref, link_kind? ])
+     *
+     * Returns array on success, WP_Error on failure.
+     */
+    public static function write( array $args ) {
+        global $wpdb;
+
+        $demand_surface  = isset( $args['demand_surface'] )  ? trim( (string) $args['demand_surface'] )  : '';
+        $demand_ref      = isset( $args['demand_ref'] )      ? trim( (string) $args['demand_ref'] )      : '';
+        $rationale       = isset( $args['rationale'] )       ? trim( (string) $args['rationale'] )       : '';
+        $projection_type = isset( $args['projection_type'] ) ? trim( (string) $args['projection_type'] ) : '';
+
+        if ( $demand_surface === '' || $demand_ref === '' ) {
+            return new WP_Error( 'missing_demand', 'demand_surface and demand_ref are required' );
+        }
+        if ( $rationale === '' ) {
+            return new WP_Error( 'missing_rationale', 'rationale is required (mandatory per SARA discipline)' );
+        }
+        if ( $projection_type === '' ) {
+            return new WP_Error( 'missing_projection_type', 'projection_type is required' );
+        }
+        if ( ! in_array( $demand_surface, SA_Orch_Bridge_Fluent::known_surfaces(), true ) ) {
+            return new WP_Error( 'unknown_surface', "demand_surface '$demand_surface' is not in known surface vocabulary" );
+        }
+        if ( ! SA_Orch_Bridge_Fluent::validate( $demand_surface, $demand_ref ) ) {
+            return new WP_Error( 'invalid_demand_ref', "demand_ref does not resolve: {$demand_surface}/{$demand_ref}" );
+        }
+
+        $actor_user_id = isset( $args['actor_user_id'] ) ? (int) $args['actor_user_id'] : get_current_user_id();
+        if ( $actor_user_id === 0 ) { $actor_user_id = null; }
+
+        $correlation_id = isset( $args['correlation_id'] ) && $args['correlation_id'] !== ''
+            ? (string) $args['correlation_id']
+            : wp_generate_uuid4();
+        $causation_id   = isset( $args['causation_id'] ) && $args['causation_id'] !== ''
+            ? (string) $args['causation_id']
+            : null;
+        $truth_class    = isset( $args['truth_class'] ) && $args['truth_class'] !== ''
+            ? (string) $args['truth_class']
+            : 'canonical';
+
+        $plan_refs = isset( $args['plan_refs'] ) && is_array( $args['plan_refs'] ) ? $args['plan_refs'] : [];
+
+        // Validate plan_refs each
+        foreach ( $plan_refs as $i => $pr ) {
+            $ps  = isset( $pr['surface'] ) ? trim( (string) $pr['surface'] ) : '';
+            $prr = isset( $pr['ref'] )     ? trim( (string) $pr['ref'] )     : '';
+            if ( $ps === '' || $prr === '' ) {
+                return new WP_Error( 'invalid_plan_ref', "plan_refs[$i] missing surface or ref" );
+            }
+            if ( ! in_array( $ps, SA_Orch_Bridge_Fluent::known_surfaces(), true ) ) {
+                return new WP_Error( 'unknown_surface', "plan_refs[$i].surface '$ps' is not known" );
+            }
+            if ( ! SA_Orch_Bridge_Fluent::validate( $ps, $prr ) ) {
+                return new WP_Error( 'invalid_plan_ref', "plan_refs[$i] does not resolve: $ps/$prr" );
+            }
+        }
+
+        $created_at = current_time( 'mysql', true );
+        $hash       = self::compute_hash( $demand_surface, $demand_ref, $created_at, $actor_user_id, $correlation_id );
+
+        // Asterion-first: ledger entry written before any DB row.
+        $frontmatter = [
+            'kind'            => 'arbitration',
+            'hash'            => $hash,
+            'demand_surface'  => $demand_surface,
+            'demand_ref'      => $demand_ref,
+            'projection_type' => $projection_type,
+            'actor_user_id'   => $actor_user_id,
+            'correlation_id'  => $correlation_id,
+            'causation_id'    => $causation_id,
+            'truth_class'     => $truth_class,
+            'plan_refs'       => array_map( function ( $pr ) {
+                return ( $pr['surface'] ?? '' ) . ':' . ( $pr['ref'] ?? '' );
+            }, $plan_refs ),
+            'created_at'      => $created_at,
+        ];
+
+        $body = "## Rationale\n\n" . $rationale . "\n";
+
+        $rel_path = SA_Orch_Asterion::write( 'arbitration', $hash, $frontmatter, $body );
+        if ( is_wp_error( $rel_path ) ) {
+            return $rel_path;
+        }
+
+        // Now insert the runtime cache row.
+        $table = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'arbitration';
+        $ok = $wpdb->insert( $table, [
+            'hash'            => $hash,
+            'demand_surface'  => $demand_surface,
+            'demand_ref'      => $demand_ref,
+            'rationale'       => $rationale,
+            'projection_type' => $projection_type,
+            'actor_user_id'   => $actor_user_id,
+            'correlation_id'  => $correlation_id,
+            'causation_id'    => $causation_id,
+            'truth_class'     => $truth_class,
+            'asterion_path'   => $rel_path,
+            'created_at'      => $created_at,
+        ] );
+
+        if ( $ok === false ) {
+            return new WP_Error( 'db_insert_failed', $wpdb->last_error, [ 'asterion_path' => $rel_path ] );
+        }
+
+        $arbitration_id = (int) $wpdb->insert_id;
+
+        $link_ids = [];
+        foreach ( $plan_refs as $pr ) {
+            $link_id = SA_Orch_Link::write( [
+                'arbitration_id' => $arbitration_id,
+                'plan_surface'   => $pr['surface'],
+                'plan_ref'       => $pr['ref'],
+                'link_kind'      => $pr['link_kind'] ?? 'derived',
+            ] );
+            if ( is_wp_error( $link_id ) ) {
+                return $link_id;
+            }
+            $link_ids[] = $link_id;
+        }
+
+        // v0.6.0: notify projection / side-effect listeners. Decoupled — listeners
+        // (e.g. SA_Orch_Projection_Fluent_Support) react via WordPress action hooks.
+        do_action( 'sa_orch_arbitration_written', [
+            'id'              => $arbitration_id,
+            'hash'            => $hash,
+            'demand_surface'  => $demand_surface,
+            'demand_ref'      => $demand_ref,
+            'projection_type' => $projection_type,
+            'truth_class'     => $truth_class,
+            'plan_link_ids'   => $link_ids,
+            'correlation_id'  => $correlation_id,
+            'asterion_path'   => $rel_path,
+        ] );
+
+        return [
+            'id'             => $arbitration_id,
+            'hash'           => $hash,
+            'asterion_path'  => $rel_path,
+            'plan_link_ids'  => $link_ids,
+            'correlation_id' => $correlation_id,
+        ];
+    }
+
+    private static function compute_hash( $demand_surface, $demand_ref, $created_at, $actor_user_id, $correlation_id ) {
+        $material = implode( '|', [
+            $demand_surface,
+            $demand_ref,
+            $created_at,
+            (int) $actor_user_id,
+            $correlation_id,
+        ] );
+        return substr( hash( 'sha256', $material ), 0, 32 );
+    }
+}

sa-orchestration/includes/class-sa-asterion-explorer.php

@@ -0,0 +1,263 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Asterion Explorer — read-only admin surface for the canonical spec pack.
+ *
+ * Source of truth: F:/SleeperAgents/SA-orchestration/Archvie/sa-core/docs/specs/
+ * (filterable via 'sa_orch_asterion_spec_root').
+ *
+ * This is a MIRROR of the repo. The repo remains authoritative.
+ *   - read-only in WP
+ *   - no edits
+ *   - no consolidation
+ *   - no reclassification
+ *   - no mixing with other MD sources
+ *
+ * Distinct from SA_Orch_Asterion (the dormant ledger writer that targets
+ * wp-content/sa-asterion/). The Explorer is human-facing canonical doctrine.
+ * The ledger (when activated) is system-generated event records. Different
+ * surfaces, different concerns; they coexist without entanglement.
+ *
+ * Mirror mechanism: live filesystem read at request time.
+ *   - No filesystem copy — no drift potential
+ *   - No indexed snapshot table — no DB writes
+ *   - Repo is automatically authoritative because there is no second copy
+ *
+ * Sara awareness: NONE in this Board. Deferred to a future Sara Retrieval
+ * Layer Board. The Explorer is the human-facing truth surface; cross-agent
+ * retrieval is a separate concern with its own design constraints.
+ */
+class SA_Orch_Asterion_Explorer {
+
+    const SUBMENU_SLUG = 'sa-orchestration-asterion';
+
+    /** Default repo path on this dev machine. Filterable. Override per-deploy via the filter. */
+    const DEFAULT_SPEC_ROOT = 'F:/SleeperAgents/SA-orchestration/Archvie/sa-core/docs/specs';
+
+    /**
+     * Absolute path to the spec pack root, normalized for this OS.
+     * Filter: sa_orch_asterion_spec_root (string $absolute_path)
+     */
+    public static function spec_root(): string {
+        $root = apply_filters( 'sa_orch_asterion_spec_root', self::DEFAULT_SPEC_ROOT );
+        return rtrim( str_replace( '\\', '/', (string) $root ), '/' );
+    }
+
+    /** Hook into admin_menu via the existing SA_Orch_Admin parent. */
+    public static function register_menu() {
+        add_submenu_page(
+            SA_Orch_Admin::PARENT_SLUG,
+            'Asterion',
+            'Asterion',
+            SA_Orch_Admin::CAP,
+            self::SUBMENU_SLUG,
+            [ __CLASS__, 'render_page' ]
+        );
+    }
+
+    /**
+     * Render the explorer page: file tree on the left, MD render on the right.
+     */
+    public static function render_page() {
+        if ( ! current_user_can( SA_Orch_Admin::CAP ) ) {
+            wp_die( __( 'Insufficient permissions.', 'sa-orchestration' ) );
+        }
+
+        $root = self::spec_root();
+        $tree = self::build_tree( $root );
+
+        // Selected file from query string. Validated below; never touched
+        // without going through validate_relative_path() first.
+        $requested = isset( $_GET['file'] ) ? wp_unslash( (string) $_GET['file'] ) : '';
+        $resolved  = $requested !== '' ? self::validate_relative_path( $requested ) : null;
+
+        echo '<div class="wrap sa-asterion-wrap">';
+        echo '<h1>Asterion <span class="sa-asterion-tag">read-only canonical truth surface</span></h1>';
+        echo '<p class="sa-asterion-meta">Source: <code>' . esc_html( $root ) . '</code> &nbsp;·&nbsp; Repo is authoritative. No edits from WP.</p>';
+
+        echo self::inline_styles();
+
+        echo '<div class="sa-asterion-explorer">';
+
+        // ---- Tree ----
+        echo '<aside class="sa-asterion-tree">';
+        if ( empty( $tree ) ) {
+            echo '<p class="sa-asterion-empty">No .md files found at the configured spec root. Verify <code>sa_orch_asterion_spec_root</code> filter / default path is reachable from the WP install.</p>';
+        } else {
+            self::render_tree_html( $tree, '', $resolved !== null ? $resolved['relative'] : '' );
+        }
+        echo '</aside>';
+
+        // ---- Content ----
+        echo '<section class="sa-asterion-content">';
+        if ( $requested !== '' && $resolved === null ) {
+            echo '<div class="sa-asterion-error"><strong>Invalid file path.</strong> The requested file is outside the spec root, has a non-.md extension, contains path traversal, or does not exist.</div>';
+        } elseif ( $resolved === null ) {
+            echo '<div class="sa-asterion-placeholder">Select a file from the tree to view its contents.</div>';
+        } else {
+            $rendered = self::render_markdown_file( $resolved['absolute'] );
+            if ( $rendered === null ) {
+                echo '<div class="sa-asterion-error"><strong>Read failed.</strong> The file resolved but could not be read.</div>';
+            } else {
+                echo '<div class="sa-asterion-breadcrumb"><code>' . esc_html( $resolved['relative'] ) . '</code></div>';
+                echo '<article class="sa-asterion-md">' . $rendered . '</article>';
+            }
+        }
+        echo '</section>';
+
+        echo '</div>'; // .sa-asterion-explorer
+        echo '</div>'; // .wrap
+    }
+
+    /**
+     * Build a nested array tree of the spec pack.
+     * Returns: [ 'dirs' => [ name => sub-tree ], 'files' => [ name => relative_path ] ]
+     */
+    private static function build_tree( string $root ): array {
+        if ( ! is_dir( $root ) ) {
+            return [];
+        }
+        return self::walk( $root, '' );
+    }
+
+    private static function walk( string $abs, string $rel_prefix ): array {
+        $dirs  = [];
+        $files = [];
+        $entries = @scandir( $abs );
+        if ( $entries === false ) {
+            return [ 'dirs' => [], 'files' => [] ];
+        }
+        foreach ( $entries as $entry ) {
+            if ( $entry === '.' || $entry === '..' ) continue;
+            $abs_path = $abs . '/' . $entry;
+            $rel_path = $rel_prefix === '' ? $entry : $rel_prefix . '/' . $entry;
+            if ( is_dir( $abs_path ) ) {
+                $dirs[ $entry ] = self::walk( $abs_path, $rel_path );
+            } elseif ( is_file( $abs_path ) && substr( strtolower( $entry ), -3 ) === '.md' ) {
+                $files[ $entry ] = $rel_path;
+            }
+        }
+        ksort( $dirs );
+        ksort( $files );
+        return [ 'dirs' => $dirs, 'files' => $files ];
+    }
+
+    private static function render_tree_html( array $tree, string $current_dir_rel, string $selected ) {
+        echo '<ul class="sa-asterion-list">';
+        foreach ( (array) ( $tree['dirs'] ?? [] ) as $name => $sub ) {
+            echo '<li class="sa-asterion-dir"><span class="sa-asterion-dir-label">' . esc_html( $name ) . '/</span>';
+            self::render_tree_html( $sub, ( $current_dir_rel === '' ? $name : $current_dir_rel . '/' . $name ), $selected );
+            echo '</li>';
+        }
+        foreach ( (array) ( $tree['files'] ?? [] ) as $name => $rel ) {
+            $url      = add_query_arg( [
+                'page' => self::SUBMENU_SLUG,
+                'file' => $rel,
+            ], admin_url( 'admin.php' ) );
+            $is_sel   = ( $rel === $selected );
+            $cls      = 'sa-asterion-file' . ( $is_sel ? ' sa-asterion-file-selected' : '' );
+            echo '<li class="' . esc_attr( $cls ) . '"><a href="' . esc_url( $url ) . '">' . esc_html( $name ) . '</a></li>';
+        }
+        echo '</ul>';
+    }
+
+    /**
+     * Validate a relative path against the spec root. Returns
+     *   [ 'relative' => normalized, 'absolute' => realpath ]
+     * or null on any failure (path traversal, wrong extension, outside root,
+     * not a file).
+     *
+     * Public so other surfaces (Board #28 Sara file binding;
+     * Board #30 Asterion projection — both reuse) can validate without
+     * re-implementing the rules.
+     */
+    public static function validate_relative_path( string $relative ): ?array {
+        // Normalize separators
+        $relative = str_replace( '\\', '/', $relative );
+
+        // Reject any obvious traversal or absolute paths
+        if ( strpos( $relative, '..' ) !== false ) return null;
+        if ( $relative === '' )                     return null;
+        if ( $relative[0] === '/' )                 return null;
+        if ( preg_match( '#^[A-Za-z]:#', $relative ) ) return null;
+
+        // Whitelist .md extension only
+        if ( substr( strtolower( $relative ), -3 ) !== '.md' ) return null;
+
+        $root_real = realpath( self::spec_root() );
+        if ( $root_real === false ) return null;
+        $root_real = str_replace( '\\', '/', $root_real );
+
+        $candidate = realpath( self::spec_root() . '/' . $relative );
+        if ( $candidate === false ) return null;
+        $candidate = str_replace( '\\', '/', $candidate );
+
+        // Final containment check: candidate must be inside root
+        if ( strpos( $candidate, $root_real . '/' ) !== 0 ) return null;
+        if ( ! is_file( $candidate ) ) return null;
+
+        // Re-derive normalized relative from the realpath for display
+        $normalized_rel = ltrim( substr( $candidate, strlen( $root_real ) ), '/' );
+
+        return [
+            'relative' => $normalized_rel,
+            'absolute' => $candidate,
+        ];
+    }
+
+    /**
+     * Read the file from disk and render via Parsedown in safe mode.
+     * Returns rendered HTML, or null on read failure.
+     */
+    private static function render_markdown_file( string $absolute ): ?string {
+        $content = @file_get_contents( $absolute );
+        if ( $content === false ) return null;
+
+        if ( ! class_exists( 'Parsedown' ) ) {
+            $vendor = dirname( __DIR__ ) . '/vendor/Parsedown.php';
+            if ( file_exists( $vendor ) ) {
+                require_once $vendor;
+            }
+        }
+        if ( ! class_exists( 'Parsedown' ) ) {
+            // Last-resort fallback: HTML-escape and render in <pre>. Honest if ugly.
+            return '<pre class="sa-asterion-fallback">' . esc_html( $content ) . '</pre>';
+        }
+
+        $pd = new Parsedown();
+        if ( method_exists( $pd, 'setSafeMode' ) ) {
+            $pd->setSafeMode( true );
+        }
+        return $pd->text( $content );
+    }
+
+    private static function inline_styles(): string {
+        // Scoped styles. Keeping it inline so the Board ships in one file.
+        return '<style>
+            .sa-asterion-wrap h1 .sa-asterion-tag { font-size:11px; padding:2px 6px; background:#f0f0f1; color:#646970; border-radius:3px; vertical-align:middle; font-weight:normal; margin-left:8px; }
+            .sa-asterion-meta { color:#646970; font-size:12px; }
+            .sa-asterion-explorer { display:flex; gap:16px; margin-top:12px; align-items:flex-start; }
+            .sa-asterion-tree { flex:0 0 280px; max-height:80vh; overflow:auto; background:#fff; border:1px solid #c3c4c7; border-radius:4px; padding:12px 8px; }
+            .sa-asterion-content { flex:1 1 auto; min-width:0; background:#fff; border:1px solid #c3c4c7; border-radius:4px; padding:16px 24px; }
+            .sa-asterion-list { margin:0; padding-left:14px; list-style:none; }
+            .sa-asterion-list ul { padding-left:14px; }
+            .sa-asterion-dir-label { font-weight:600; color:#1d2327; }
+            .sa-asterion-file a { display:block; padding:2px 4px; text-decoration:none; color:#2271b1; }
+            .sa-asterion-file a:hover { background:#f6f7f7; }
+            .sa-asterion-file-selected a { background:#dcdcde; color:#1d2327; font-weight:600; }
+            .sa-asterion-breadcrumb { font-size:12px; color:#646970; margin-bottom:12px; padding-bottom:8px; border-bottom:1px solid #f0f0f1; }
+            .sa-asterion-placeholder, .sa-asterion-empty { color:#646970; font-style:italic; }
+            .sa-asterion-error { background:#fcf0f1; border-left:4px solid #d63638; padding:10px 12px; color:#7a1f23; }
+            .sa-asterion-md { line-height:1.6; }
+            .sa-asterion-md h1, .sa-asterion-md h2, .sa-asterion-md h3 { margin-top:1.4em; }
+            .sa-asterion-md pre { background:#1d2327; color:#f6f7f7; padding:12px; border-radius:4px; overflow:auto; }
+            .sa-asterion-md code { background:#f0f0f1; padding:1px 5px; border-radius:3px; font-size:13px; }
+            .sa-asterion-md pre code { background:transparent; padding:0; color:inherit; }
+            .sa-asterion-md table { border-collapse:collapse; margin:1em 0; }
+            .sa-asterion-md th, .sa-asterion-md td { border:1px solid #c3c4c7; padding:6px 10px; }
+            .sa-asterion-md blockquote { border-left:4px solid #c3c4c7; margin:1em 0; padding:4px 14px; color:#50575e; }
+            .sa-asterion-fallback { white-space:pre-wrap; }
+        </style>';
+    }
+}

sa-orchestration/includes/class-sa-asterion-projection.php

@@ -0,0 +1,478 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Asterion Projection — Board #30
+ *
+ * Asterion's website-facing query surface, separate from Sara.
+ *
+ * Sara interprets. Asterion verifies. Two distinct surfaces, same source.
+ *
+ * Asterion responses are:
+ *   - grounded in the canonical MD spec corpus (Archvie/sa-core/docs/specs/)
+ *   - cite specific files (and excerpts) by name
+ *   - refuse to speculate beyond the source
+ *   - return "no canonical reference found" when corpus does not contain the answer
+ *
+ * No write capability anywhere. Read-only by construction.
+ *
+ * Architecture:
+ *   - REST endpoint /sa-orch/v1/asterion/query
+ *   - Keyword search across spec corpus + LLM-framed citation answer
+ *   - Reuses SA_Orch_Asterion_Explorer::spec_root() and validate_relative_path()
+ *   - Reuses LLM provider stack (SA_Orch_LLM_Settings, wp_remote_post)
+ *   - Reuses wp_sa_token_log (Board #16) for usage accounting
+ *   - Distinct system prompt (librarian role; structurally different shape from Sara)
+ *
+ * Front-end: assets/asterion-bubble.js + assets/asterion-bubble.css (separate
+ * floating button, top-right, distinct visual identity from Sara).
+ */
+class SA_Orch_Asterion_Projection {
+
+    const HANDLE_JS  = 'sa-orch-asterion-bubble';
+    const HANDLE_CSS = 'sa-orch-asterion-bubble';
+    const REQUEST_TIMEOUT = 30;
+
+    /** Number of excerpts to return from corpus search. */
+    const TOP_K = 5;
+
+    /** Max chars per excerpt window included in the LLM prompt.
+     *  Wide enough to give the LLM real context around the match — file headers and
+     *  one-paragraph blurbs aren't enough to ground a Truth-Class-style answer. */
+    const EXCERPT_CHARS = 1800;
+
+    /* -------------------- Hooks -------------------- */
+
+    public static function register_hooks() {
+        add_action( 'admin_enqueue_scripts', [ __CLASS__, 'maybe_enqueue' ] );
+    }
+
+    public static function register_routes() {
+        register_rest_route( 'sa-orch/v1', '/asterion/query', [
+            'methods'             => 'POST',
+            'callback'            => [ __CLASS__, 'rest_query' ],
+            'permission_callback' => function () {
+                return current_user_can( 'manage_options' );
+            },
+            'args' => [
+                'query'         => [ 'type' => 'string', 'required' => true ],
+                'asterion_file' => [ 'type' => 'string', 'required' => false ],
+            ],
+        ] );
+    }
+
+    public static function maybe_enqueue( $hook ) {
+        if ( ! current_user_can( 'manage_options' ) ) return;
+
+        $page = isset( $_GET['page'] ) ? sanitize_text_field( wp_unslash( $_GET['page'] ) ) : '';
+
+        // Asterion bubble: any SA-Orchestration admin page (the Explorer is a subpage,
+        // but Asterion is also useful from Demand Trace / Acceptance Events).
+        if ( strpos( $page, 'sa-orchestration' ) !== 0 ) return;
+
+        wp_enqueue_style(
+            self::HANDLE_CSS,
+            SA_ORCH_URL . 'assets/asterion-bubble.css',
+            [],
+            SA_ORCH_VERSION
+        );
+
+        wp_enqueue_script(
+            self::HANDLE_JS,
+            SA_ORCH_URL . 'assets/asterion-bubble.js',
+            [],
+            SA_ORCH_VERSION,
+            true
+        );
+
+        wp_localize_script( self::HANDLE_JS, 'SA_ORCH_ASTERION', [
+            'rest_url' => esc_url_raw( rest_url( 'sa-orch/v1/asterion/query' ) ),
+            'nonce'    => wp_create_nonce( 'wp_rest' ),
+            'page'     => $page,
+        ] );
+    }
+
+    /* -------------------- REST handler -------------------- */
+
+    public static function rest_query( WP_REST_Request $request ) {
+        $query         = (string) $request->get_param( 'query' );
+        $asterion_file = sanitize_text_field( (string) $request->get_param( 'asterion_file' ) );
+
+        if ( trim( $query ) === '' ) {
+            return new WP_REST_Response( [
+                'error'   => 'empty_query',
+                'message' => 'query is required',
+            ], 400 );
+        }
+
+        $result = self::query( $query, $asterion_file );
+        if ( is_wp_error( $result ) ) {
+            return new WP_REST_Response( [
+                'error'   => $result->get_error_code(),
+                'message' => $result->get_error_message(),
+            ], 502 );
+        }
+
+        return new WP_REST_Response( $result, 200 );
+    }
+
+    /* -------------------- Core query -------------------- */
+
+    /**
+     * Run a corpus query and return a structured Asterion response.
+     *
+     * Response shape:
+     *   {
+     *     answer:    string,    // citation-grounded answer or "no canonical reference found"
+     *     citations: array,     // [{ file, excerpt }, ...]
+     *     scope:     string,    // "single_file:<rel>" | "spec_corpus" | "no_corpus"
+     *     usage:     array|null,
+     *     log_id:    int|null
+     *   }
+     */
+    public static function query( string $query, string $asterion_file = '' ) {
+        if ( ! class_exists( 'SA_Orch_Asterion_Explorer' ) ) {
+            return new WP_Error( 'no_corpus', 'Asterion Explorer not loaded.' );
+        }
+
+        $root = SA_Orch_Asterion_Explorer::spec_root();
+        if ( ! is_dir( $root ) ) {
+            return [
+                'answer'    => 'no canonical reference found in the spec corpus (corpus root unreachable)',
+                'citations' => [],
+                'scope'     => 'no_corpus',
+                'usage'     => null,
+                'log_id'    => null,
+            ];
+        }
+
+        // Determine search scope.
+        $scope    = 'spec_corpus';
+        $bound_md = null;
+        if ( $asterion_file !== '' ) {
+            $resolved = SA_Orch_Asterion_Explorer::validate_relative_path( $asterion_file );
+            if ( is_array( $resolved ) ) {
+                $bound_md = $resolved;
+                $scope    = 'single_file:' . $resolved['relative'];
+            }
+        }
+
+        // Retrieve excerpts.
+        $excerpts = $bound_md
+            ? self::search_single_file( $bound_md['absolute'], $bound_md['relative'], $query )
+            : self::search_corpus( $root, $query );
+
+        // No matches → refuse to speculate.
+        if ( empty( $excerpts ) ) {
+            return [
+                'answer'    => 'no canonical reference found in the spec corpus',
+                'citations' => [],
+                'scope'     => $scope,
+                'usage'     => null,
+                'log_id'    => null,
+            ];
+        }
+
+        // Frame with LLM (Model B). If LLM is disabled or fails, fall through
+        // to raw-excerpt mode so the surface still works.
+        $framed = self::frame_with_llm( $query, $excerpts, $scope );
+        if ( is_array( $framed ) ) {
+            return $framed + [
+                'citations' => $excerpts,
+                'scope'     => $scope,
+            ];
+        }
+
+        // Fallback: raw excerpts as the "answer" when LLM unavailable.
+        $answer_lines = [ 'Citation-only mode (LLM unavailable). Raw excerpts:' ];
+        foreach ( $excerpts as $i => $ex ) {
+            $answer_lines[] = sprintf( '[%d] %s', $i + 1, $ex['file'] );
+        }
+        return [
+            'answer'    => implode( "\n", $answer_lines ),
+            'citations' => $excerpts,
+            'scope'     => $scope,
+            'usage'     => null,
+            'log_id'    => null,
+        ];
+    }
+
+    /* -------------------- Search -------------------- */
+
+    /**
+     * Search the entire spec corpus for terms in $query.
+     * Returns up to TOP_K excerpts ranked by hit score.
+     */
+    private static function search_corpus( string $root, string $query ): array {
+        $terms = self::extract_terms( $query );
+        if ( empty( $terms ) ) return [];
+
+        $hits = [];
+        self::walk_corpus( $root, '', function ( $abs, $rel ) use ( $terms, &$hits ) {
+            $content = @file_get_contents( $abs );
+            if ( $content === false ) return;
+            $score = 0;
+            foreach ( $terms as $t ) {
+                $score += substr_count( strtolower( $content ), $t );
+            }
+            if ( $score > 0 ) {
+                $hits[] = [
+                    'file'    => $rel,
+                    'score'   => $score,
+                    'excerpt' => self::best_excerpt( $content, $terms ),
+                ];
+            }
+        } );
+
+        usort( $hits, function ( $a, $b ) { return $b['score'] - $a['score']; } );
+        $hits = array_slice( $hits, 0, self::TOP_K );
+
+        $out = [];
+        foreach ( $hits as $h ) {
+            $out[] = [ 'file' => $h['file'], 'excerpt' => $h['excerpt'] ];
+        }
+        return $out;
+    }
+
+    /**
+     * Search a single bound MD file.
+     */
+    private static function search_single_file( string $abs, string $rel, string $query ): array {
+        $content = @file_get_contents( $abs );
+        if ( $content === false ) return [];
+
+        $terms = self::extract_terms( $query );
+        if ( empty( $terms ) ) return [];
+
+        $score = 0;
+        foreach ( $terms as $t ) {
+            $score += substr_count( strtolower( $content ), $t );
+        }
+        if ( $score === 0 ) return [];
+
+        return [ [
+            'file'    => $rel,
+            'excerpt' => self::best_excerpt( $content, $terms ),
+        ] ];
+    }
+
+    private static function walk_corpus( string $abs, string $rel_prefix, callable $cb ) {
+        $entries = @scandir( $abs );
+        if ( $entries === false ) return;
+        foreach ( $entries as $e ) {
+            if ( $e === '.' || $e === '..' ) continue;
+            $a = $abs . '/' . $e;
+            $r = $rel_prefix === '' ? $e : $rel_prefix . '/' . $e;
+            if ( is_dir( $a ) ) {
+                self::walk_corpus( $a, $r, $cb );
+            } elseif ( is_file( $a ) && substr( strtolower( $e ), -3 ) === '.md' ) {
+                $cb( $a, $r );
+            }
+        }
+    }
+
+    /**
+     * Extract lowercased search terms from the query.
+     * Strips stopwords/punctuation; minimum 3-char tokens.
+     */
+    private static function extract_terms( string $query ): array {
+        $q = strtolower( $query );
+        $q = preg_replace( '/[^a-z0-9_\-\s]/', ' ', $q );
+        $tokens = preg_split( '/\s+/', $q, -1, PREG_SPLIT_NO_EMPTY );
+        $stop = [ 'the','and','but','for','are','was','were','have','has','had','will',
+                  'with','this','that','from','what','which','about','they','them',
+                  'their','our','your','his','her','its','some','any','all','can',
+                  'how','why','when','where','who','whom','does','did','done','not',
+                  'into','onto','off','out','only','also','each','more','less','very',
+                  'such','than','then','than','these','those','say','says','said' ];
+        $out = [];
+        foreach ( $tokens as $t ) {
+            if ( strlen( $t ) < 3 ) continue;
+            if ( in_array( $t, $stop, true ) ) continue;
+            $out[ $t ] = true;
+        }
+        return array_keys( $out );
+    }
+
+    /**
+     * Find the best excerpt window in $content given $terms.
+     *
+     * Strategy: pick the position with the highest local term-density across a
+     * sliding window — not just the first match. File headers and credit blurbs
+     * often contain isolated keyword hits; the actual definition is further down.
+     * Windowing on density beats first-match for citation quality.
+     */
+    private static function best_excerpt( string $content, array $terms ): string {
+        $lower    = strtolower( $content );
+        $len      = strlen( $lower );
+        if ( $len === 0 ) return '';
+
+        // Collect all match positions for any term.
+        $positions = [];
+        foreach ( $terms as $t ) {
+            $off = 0;
+            while ( ( $p = strpos( $lower, $t, $off ) ) !== false ) {
+                $positions[] = $p;
+                $off = $p + max( 1, strlen( $t ) );
+            }
+        }
+        if ( empty( $positions ) ) {
+            // No match — fall back to first chars
+            return function_exists( 'mb_substr' )
+                ? mb_substr( $content, 0, self::EXCERPT_CHARS )
+                : substr( $content, 0, self::EXCERPT_CHARS );
+        }
+        sort( $positions );
+
+        // Slide a window across positions; pick the position whose window
+        // contains the most match positions (density).
+        $window = self::EXCERPT_CHARS;
+        $best_pos   = $positions[0];
+        $best_count = 0;
+        foreach ( $positions as $p ) {
+            $count = 0;
+            foreach ( $positions as $q ) {
+                if ( $q >= $p && $q < $p + $window ) $count++;
+                if ( $q >= $p + $window ) break;
+            }
+            if ( $count > $best_count ) {
+                $best_count = $count;
+                $best_pos   = $p;
+            }
+        }
+
+        // Center window on best_pos (back off slightly so match isn't at edge)
+        $half  = (int) ( $window / 4 ); // back off 25%, not 50% — anchor near top of window
+        $start = max( 0, $best_pos - $half );
+        $exc   = function_exists( 'mb_substr' )
+            ? mb_substr( $content, $start, $window )
+            : substr( $content, $start, $window );
+        if ( $start > 0 )                       $exc = '… ' . $exc;
+        if ( $start + $window < strlen( $content ) ) $exc .= ' …';
+        return $exc;
+    }
+
+    /* -------------------- LLM framing -------------------- */
+
+    /**
+     * Frame the excerpts as a librarian-tone, citation-grounded answer.
+     * Returns array { answer, usage, log_id } on success, null on failure.
+     */
+    private static function frame_with_llm( string $query, array $excerpts, string $scope ) {
+        if ( ! class_exists( 'SA_Orch_LLM_Settings' ) ) return null;
+        $settings = SA_Orch_LLM_Settings::get();
+        if ( empty( $settings['enabled'] ) || empty( $settings['api_token'] )
+             || empty( $settings['api_base_url'] ) || empty( $settings['model'] ) ) {
+            return null;
+        }
+
+        $url = rtrim( (string) $settings['api_base_url'], '/' ) . '/chat/completions';
+
+        $excerpt_block = "Excerpts retrieved from the spec corpus (verbatim; do not invent beyond these):\n\n";
+        foreach ( $excerpts as $i => $ex ) {
+            $n = $i + 1;
+            $excerpt_block .= "[CITATION {$n}] file: {$ex['file']}\n";
+            $excerpt_block .= "----\n";
+            $excerpt_block .= $ex['excerpt'] . "\n";
+            $excerpt_block .= "----\n\n";
+        }
+
+        $messages = [
+            [ 'role' => 'system', 'content' => self::system_prompt() ],
+            [ 'role' => 'user',   'content' => $excerpt_block . "User question:\n\n" . $query ],
+        ];
+
+        $payload = [
+            'model'           => (string) $settings['model'],
+            'messages'        => $messages,
+            'response_format' => [ 'type' => 'json_object' ],
+            'temperature'     => 0.1,
+        ];
+
+        $response = wp_remote_post( $url, [
+            'headers' => [
+                'Authorization' => 'Bearer ' . (string) $settings['api_token'],
+                'Content-Type'  => 'application/json',
+            ],
+            'body'    => wp_json_encode( $payload ),
+            'timeout' => self::REQUEST_TIMEOUT,
+        ] );
+
+        if ( is_wp_error( $response ) ) return null;
+        $code = (int) wp_remote_retrieve_response_code( $response );
+        if ( $code < 200 || $code >= 300 ) return null;
+
+        $body     = (string) wp_remote_retrieve_body( $response );
+        $envelope = json_decode( $body, true );
+        if ( ! is_array( $envelope ) || ! isset( $envelope['choices'][0]['message']['content'] ) ) return null;
+
+        $content = (string) $envelope['choices'][0]['message']['content'];
+        $parsed  = json_decode( $content, true );
+        if ( ! is_array( $parsed ) ) return null;
+
+        $answer = isset( $parsed['answer'] ) ? (string) $parsed['answer'] : '';
+        if ( $answer === '' ) {
+            $answer = 'no canonical reference found in the spec corpus';
+        }
+
+        // Token log
+        $usage  = isset( $envelope['usage'] ) && is_array( $envelope['usage'] ) ? $envelope['usage'] : null;
+        $log_id = null;
+        if ( $usage !== null && class_exists( 'SA_Orch_Token_Log' ) ) {
+            $log_id = SA_Orch_Token_Log::record(
+                'asterion',
+                (string) $settings['model'],
+                $usage,
+                (int) get_current_user_id()
+            );
+            $log_id = $log_id > 0 ? $log_id : null;
+        }
+
+        return [
+            'answer' => $answer,
+            'usage'  => $usage,
+            'log_id' => $log_id,
+        ];
+    }
+
+    /**
+     * Asterion's system prompt — librarian role.
+     * Structurally distinct from Sara's prompt:
+     *   - no interpretation tone, no synthesis, no advice
+     *   - citation-grounded, refusal-to-speculate, file-named
+     *   - returns { answer: string } JSON; no summary/suggestion/draft/notes
+     */
+    public static function system_prompt(): string {
+        return "ASTERION — canonical librarian for the SA-Core spec corpus.\n"
+             . "\n"
+             . "You are NOT Sara. You are NOT an interpreter. You are NOT an advisor.\n"
+             . "You are the verifier: a strict, citation-grounded surface over\n"
+             . "Archvie/sa-core/docs/specs/. Your job is to ground every claim in\n"
+             . "specific source excerpts that have been provided to you, and to\n"
+             . "refuse if the answer is not present in those excerpts.\n"
+             . "\n"
+             . "TONE\n"
+             . "  - Direct. Citation-led. No interpretive framing. No synthesis tone.\n"
+             . "  - No \"I think\", no \"likely\", no \"probably\", no advisory voice.\n"
+             . "  - Reference the corpus by file name + section. Use phrases like\n"
+             . "    \"per 02-invariants.md, I2 ...\" — name the file and the labeled\n"
+             . "    element.\n"
+             . "\n"
+             . "OUTPUT (strict JSON; no other keys)\n"
+             . "  { \"answer\": string }\n"
+             . "\n"
+             . "RULES\n"
+             . "  - If the excerpts contain the answer: state it directly and cite the\n"
+             . "    file(s) and labeled elements (I1, I2, R-O-1, named sections). Quote\n"
+             . "    short phrases verbatim where it adds verifiability.\n"
+             . "  - If the excerpts do NOT contain the answer (the question is off-topic,\n"
+             . "    or the corpus is silent): set answer to exactly:\n"
+             . "      \"no canonical reference found in the spec corpus\"\n"
+             . "    Do not speculate. Do not extrapolate. Do not invent.\n"
+             . "  - You may NOT introduce concepts not present in the excerpts.\n"
+             . "  - You may NOT advise the user on what to do.\n"
+             . "  - You may NOT use Sara's structured 4-key shape. Only { \"answer\" }.\n"
+             . "\n"
+             . "Sara interprets. You verify. The Human arbitrates.\n";
+    }
+}

sa-orchestration/includes/class-sa-asterion.php

@@ -0,0 +1,82 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+class SA_Orch_Asterion {
+
+    /**
+     * Root directory for the Asterion ledger.
+     * Default: WP_CONTENT_DIR/sa-asterion. Filterable.
+     */
+    public static function root() {
+        $default = WP_CONTENT_DIR . '/sa-asterion';
+        return apply_filters( 'sa_orch_asterion_root', $default );
+    }
+
+    /**
+     * Asterion-first write. The .md file is the canonical record.
+     * Returns relative path (e.g. "arbitration/<hash>.md") or WP_Error.
+     */
+    public static function write( $kind, $hash, array $frontmatter, $body ) {
+        $root = self::root();
+        if ( ! is_dir( $root ) && ! wp_mkdir_p( $root ) ) {
+            return new WP_Error( 'asterion_mkdir_failed', "Could not create root: $root" );
+        }
+
+        $kind_safe = sanitize_file_name( $kind );
+        $hash_safe = sanitize_file_name( $hash );
+
+        $kind_dir = $root . '/' . $kind_safe;
+        if ( ! is_dir( $kind_dir ) && ! wp_mkdir_p( $kind_dir ) ) {
+            return new WP_Error( 'asterion_mkdir_failed', "Could not create kind dir: $kind_dir" );
+        }
+
+        $rel = $kind_safe . '/' . $hash_safe . '.md';
+        $abs = $root . '/' . $rel;
+
+        if ( file_exists( $abs ) ) {
+            return new WP_Error( 'asterion_collision', "Ledger entry already exists: $rel" );
+        }
+
+        $contents = "---\n" . self::build_frontmatter( $frontmatter ) . "---\n\n" . $body . "\n";
+
+        $written = @file_put_contents( $abs, $contents, LOCK_EX );
+        if ( $written === false ) {
+            return new WP_Error( 'asterion_write_failed', "Could not write $abs" );
+        }
+
+        return $rel;
+    }
+
+    private static function build_frontmatter( array $fm ) {
+        $out = '';
+        foreach ( $fm as $k => $v ) {
+            if ( is_array( $v ) ) {
+                if ( empty( $v ) ) {
+                    $out .= "{$k}: []\n";
+                } else {
+                    $out .= "{$k}:\n";
+                    foreach ( $v as $item ) {
+                        $out .= "  - " . self::yaml_scalar( $item ) . "\n";
+                    }
+                }
+            } else {
+                $out .= "{$k}: " . self::yaml_scalar( $v ) . "\n";
+            }
+        }
+        return $out;
+    }
+
+    private static function yaml_scalar( $v ) {
+        if ( $v === null )    return '~';
+        if ( is_bool( $v ) )  return $v ? 'true' : 'false';
+        if ( is_int( $v ) )   return (string) $v;
+        if ( is_float( $v ) ) return (string) $v;
+
+        $s = (string) $v;
+        // Quote strings that contain YAML-special chars or whitespace edges
+        if ( $s === '' || preg_match( '/[:#\-\?&\*\!\|>\'"%@`\{\}\[\],\n]/', $s ) || $s !== trim( $s ) ) {
+            return '"' . str_replace( [ '\\', '"' ], [ '\\\\', '\\"' ], $s ) . '"';
+        }
+        return $s;
+    }
+}

sa-orchestration/includes/class-sa-attention-bridge.php

@@ -0,0 +1,399 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Attention Bridge — emit-only MVP.
+ *
+ * Cross-site attention routing channel. The local site (RCM) emits
+ * structured context packets to a configured oversight URL. The
+ * receiving side is OUT OF SCOPE for this Board — emit-only MVP.
+ *
+ * Architectural rules (stakeholder, locked):
+ *   Attention is portable. Authority is local. Oversight is routed.
+ *   Local site owns its operational truth.
+ *   SleeperAgents owns oversight routing.
+ *   SA-Core governs the exchange.
+ *
+ * Doctrine constraints honored:
+ *   - User-triggered emission ONLY. No auto-emit. No Sara coupling.
+ *   - Bearer-token auth for the outbound POST (shared secret).
+ *   - Schema versioning baked into the payload: 'sa.attention.v1'.
+ *   - Log-only storage: wp_sa_attention_log captures what was sent + whether it arrived.
+ *   - "Don't overbuild." This file does emit + log. Nothing else.
+ *
+ * Configuration (wp-config.php constants — required):
+ *   define('SA_SITE_ID',             'rcm');
+ *   define('SA_ATTENTION_TARGET_URL', 'https://sleeperagents.org/wp-json/oversight/v1/attention');
+ *   define('SA_ATTENTION_TOKEN',     'shared-secret-here');
+ *
+ * Optional:
+ *   define('SA_TENANT', 'org-slug');  // single-field tenant per locked spec
+ *
+ * Each constant is also filterable for testing / runtime override:
+ *   sa_orch_attention_site_id, sa_orch_attention_target_url,
+ *   sa_orch_attention_token, sa_orch_attention_tenant
+ */
+class SA_Orch_Attention_Bridge {
+
+    const SCHEMA_VERSION = 'sa.attention.v1';
+
+    const HANDLE_JS  = 'sa-orch-attention-bridge';
+    const HANDLE_CSS = 'sa-orch-attention-bridge';
+
+    /** Hook registration — REST + admin enqueue. */
+    public static function register_hooks() {
+        add_action( 'rest_api_init',         [ __CLASS__, 'register_rest_routes' ] );
+        add_action( 'admin_enqueue_scripts', [ __CLASS__, 'maybe_enqueue' ] );
+    }
+
+    /**
+     * REST endpoints:
+     *   POST /sa-orch/v1/attention/emit          — always (production-safe)
+     *   POST /sa-orch/v1/attention/dev-receive   — local/development only (mock 200 receiver)
+     */
+    public static function register_rest_routes() {
+        register_rest_route( 'sa-orch/v1', '/attention/emit', [
+            'methods'             => 'POST',
+            'callback'            => [ __CLASS__, 'emit' ],
+            'permission_callback' => function () {
+                return current_user_can( 'manage_options' );
+            },
+            'args'                => [
+                'surface' => [ 'required' => false, 'type' => 'string', 'sanitize_callback' => 'sanitize_text_field' ],
+                'ref'     => [ 'required' => false, 'type' => 'string', 'sanitize_callback' => 'sanitize_text_field' ],
+                'page'    => [ 'required' => false, 'type' => 'string', 'sanitize_callback' => 'sanitize_text_field' ],
+                // 'mode' selects which target the dev verification flow exercises.
+                // Currently accepted: 'default' (the configured / scaffold-failure target)
+                // and 'success_mock' (routes to the dev-receive endpoint, dev-only).
+                // In non-dev environments, 'success_mock' silently falls back to default.
+                'mode'    => [ 'required' => false, 'type' => 'string', 'sanitize_callback' => 'sanitize_key' ],
+            ],
+        ] );
+
+        // Dev-only mock receiver. Registered ONLY when the environment is
+        // explicitly local or development. In production this route does not
+        // exist — the registration itself is gated, not just the handler.
+        if ( class_exists( 'SA_Orch_Env' ) && SA_Orch_Env::is_local_or_dev() ) {
+            register_rest_route( 'sa-orch/v1', '/attention/dev-receive', [
+                'methods'             => 'POST',
+                'callback'            => [ __CLASS__, 'dev_receive' ],
+                // No capability check — this is a dev mock for self-call testing.
+                // The whole route is only registered in dev environments.
+                'permission_callback' => '__return_true',
+            ] );
+        }
+    }
+
+    /**
+     * Dev-only mock receiver. Returns HTTP 200 with a confirmation body so
+     * the success path can be exercised end-to-end without a real oversight
+     * site standing up. Defense in depth: handler also bails if env is not
+     * dev (in case the route somehow survives a misconfigured deploy).
+     */
+    public static function dev_receive( WP_REST_Request $request ) {
+        if ( ! class_exists( 'SA_Orch_Env' ) || ! SA_Orch_Env::is_local_or_dev() ) {
+            return new WP_Error(
+                'dev_receive_not_available',
+                'dev-receive is only available in local/development environments.',
+                [ 'status' => 404 ]
+            );
+        }
+        return rest_ensure_response( [
+            'received'    => true,
+            'env'         => SA_Orch_Env::type(),
+            'message'     => 'Dev mock receiver acknowledged the attention packet.',
+            'received_at' => gmdate( 'c' ),
+        ] );
+    }
+
+    /**
+     * Read configuration with classification-aware precedence:
+     *
+     *   1. Defined constant       (production-safe; human-authorized)
+     *   2. Filter override        (testing override; same shape as the constant)
+     *   3. Dev scaffold default   (only when env is local/development; clearly
+     *                              non-production values; no real privileged
+     *                              system exposed; tokens labeled dev-only)
+     *   4. Empty string           (production with no constants set; emit will
+     *                              fail with attention_config_missing — preserved
+     *                              behavior for the unconfigured production case)
+     *
+     * Per the Environment Configuration Classification rule, dev scaffolding
+     * is allowed because:
+     *   - the values are clearly non-production (sa-dev-local / discard-port URL / dev-only token)
+     *   - no real external privileged system is exposed (target is unreachable)
+     *   - the token is explicitly labeled dev-only
+     *   - the env must be EXPLICITLY local/development (default 'production' never scaffolds)
+     */
+    public static function get_config(): array {
+        $defaults = self::dev_scaffold_defaults();
+        return [
+            'site_id'    => self::resolve_value( 'SA_SITE_ID',             'sa_orch_attention_site_id',    $defaults['site_id'] ),
+            'target_url' => self::resolve_value( 'SA_ATTENTION_TARGET_URL', 'sa_orch_attention_target_url', $defaults['target_url'] ),
+            'token'      => self::resolve_value( 'SA_ATTENTION_TOKEN',      'sa_orch_attention_token',      $defaults['token'] ),
+            'tenant'     => self::resolve_value( 'SA_TENANT',               'sa_orch_attention_tenant',     $defaults['tenant'] ),
+        ];
+    }
+
+    /**
+     * Resolve a single config value. Constants beat filters beat dev scaffolds
+     * beat empty. The dev_default is only non-empty when env is local/dev.
+     */
+    private static function resolve_value( string $constant_name, string $filter_name, string $dev_default ): string {
+        if ( defined( $constant_name ) ) {
+            return (string) constant( $constant_name );
+        }
+        $filtered = apply_filters( $filter_name, '' );
+        if ( $filtered !== '' && $filtered !== null ) {
+            return (string) $filtered;
+        }
+        return $dev_default;
+    }
+
+    /**
+     * Dev-mode scaffolds. Empty in production. Populated in local/dev only.
+     *
+     * Values chosen to be unambiguously non-production:
+     *   site_id    — 'sa-dev-local' (slug clearly marks origin as dev)
+     *   target_url — '<scheme>://<host>:9/sa-attention-dev-null' derived from
+     *                home_url() so the scaffold scales with the install's own
+     *                hostname (works on wordpress.localhost, dev.example.com,
+     *                etc.). Port 9 is the IANA discard service; reliably
+     *                refuses connections regardless of host. No real system
+     *                is exposed; emit attempts cleanly fail with status=failed.
+     *   token      — 'dev-only-not-a-real-secret' (string self-labels its kind)
+     *   tenant     — 'dev-tenant'
+     */
+    private static function dev_scaffold_defaults(): array {
+        if ( ! class_exists( 'SA_Orch_Env' ) || ! SA_Orch_Env::is_local_or_dev() ) {
+            return [ 'site_id' => '', 'target_url' => '', 'token' => '', 'tenant' => '' ];
+        }
+        return [
+            'site_id'    => 'sa-dev-local',
+            'target_url' => self::dev_failure_target_url(),
+            'token'      => 'dev-only-not-a-real-secret',
+            'tenant'     => 'dev-tenant',
+        ];
+    }
+
+    /**
+     * Compute the dev failure-target URL from the install's own host.
+     * Scales with deploy: same code yields wordpress.localhost:9 in local
+     * dev, dev.example.com:9 in remote dev, etc. Production never calls this.
+     */
+    private static function dev_failure_target_url(): string {
+        $parts  = wp_parse_url( home_url() );
+        $scheme = $parts['scheme'] ?? 'http';
+        $host   = $parts['host']   ?? '127.0.0.1';
+        return $scheme . '://' . $host . ':9/sa-attention-dev-null';
+    }
+
+    /**
+     * The URL of the dev mock receiver — same install, REST endpoint at
+     * sa-orch/v1/attention/dev-receive. Returns empty string in non-dev
+     * environments so the success-mock mode silently falls back to default.
+     */
+    private static function dev_success_mock_url(): string {
+        if ( ! class_exists( 'SA_Orch_Env' ) || ! SA_Orch_Env::is_local_or_dev() ) {
+            return '';
+        }
+        return rest_url( 'sa-orch/v1/attention/dev-receive' );
+    }
+
+    /**
+     * Resolve the outbound target URL given the configured target and the
+     * caller-requested mode. Returns:
+     *   [ url, mode_label ]
+     * mode_label is a short human-readable string for UI display:
+     *   'configured'         — the configured / scaffold-failure target
+     *   'dev failure target' — same as 'configured' when env is dev (annotated)
+     *   'dev success mock'   — the dev-receive URL (only when env is dev)
+     */
+    private static function resolve_outbound_target( string $configured_url, string $mode ): array {
+        $is_dev = class_exists( 'SA_Orch_Env' ) && SA_Orch_Env::is_local_or_dev();
+
+        if ( $mode === 'success_mock' ) {
+            $mock = self::dev_success_mock_url();
+            if ( $is_dev && $mock !== '' ) {
+                return [ $mock, 'dev success mock' ];
+            }
+            // Production / non-dev silently falls back to configured. Production
+            // safety: success_mock has no effect outside dev.
+        }
+        return [
+            $configured_url,
+            $is_dev ? 'dev failure target' : 'configured',
+        ];
+    }
+
+    /**
+     * Build the v1 attention payload. Pure function — no I/O.
+     */
+    public static function build_payload( array $cfg, array $input ): array {
+        $user      = wp_get_current_user();
+        $user_id   = isset( $user->ID )         ? (int) $user->ID         : 0;
+        $user_name = isset( $user->user_login ) ? (string) $user->user_login : '';
+
+        return [
+            'schema_version' => self::SCHEMA_VERSION,
+            'site_id'        => (string) $cfg['site_id'],
+            'tenant'         => (string) $cfg['tenant'],
+            'surface'        => isset( $input['surface'] ) && $input['surface'] !== '' ? (string) $input['surface'] : null,
+            'ref'            => isset( $input['ref'] )     && $input['ref']     !== '' ? (string) $input['ref']     : null,
+            'page'           => isset( $input['page'] )    && $input['page']    !== '' ? (string) $input['page']    : null,
+            'user'           => [
+                'id'    => $user_id,
+                'login' => $user_name,
+            ],
+            'observed_at'    => gmdate( 'c' ),
+        ];
+    }
+
+    /**
+     * REST emit handler. Assembles payload, POSTs to target URL with bearer auth,
+     * logs the attempt to wp_sa_attention_log. Returns the result to the caller
+     * so the UI can render success/error feedback.
+     */
+    public static function emit( WP_REST_Request $request ) {
+        $cfg = self::get_config();
+
+        // Required-config check. Surface missing config explicitly so the
+        // operator knows what to set, rather than silently failing.
+        $missing = [];
+        if ( $cfg['site_id']    === '' ) $missing[] = 'SA_SITE_ID';
+        if ( $cfg['target_url'] === '' ) $missing[] = 'SA_ATTENTION_TARGET_URL';
+        if ( $cfg['token']      === '' ) $missing[] = 'SA_ATTENTION_TOKEN';
+        if ( $missing ) {
+            return new WP_Error(
+                'attention_config_missing',
+                'Attention Bridge configuration missing: ' . implode( ', ', $missing )
+                . '. Define these constants in wp-config.php.',
+                [ 'status' => 500 ]
+            );
+        }
+
+        $input = [
+            'surface' => (string) $request->get_param( 'surface' ),
+            'ref'     => (string) $request->get_param( 'ref' ),
+            'page'    => (string) $request->get_param( 'page' ),
+        ];
+
+        $payload = self::build_payload( $cfg, $input );
+
+        // Resolve which target this emit hits. 'success_mock' routes to the
+        // dev-receive endpoint (dev-only); otherwise the configured target.
+        $mode = (string) $request->get_param( 'mode' );
+        list( $outbound_url, $mode_label ) = self::resolve_outbound_target( $cfg['target_url'], $mode );
+
+        // POST with bearer auth. wp_remote_post handles transport errors gracefully.
+        $resp = wp_remote_post( $outbound_url, [
+            'method'  => 'POST',
+            'timeout' => 10,
+            'headers' => [
+                'Authorization'         => 'Bearer ' . $cfg['token'],
+                'Content-Type'          => 'application/json',
+                'X-SA-Schema-Version'   => self::SCHEMA_VERSION,
+            ],
+            'body'    => wp_json_encode( $payload ),
+        ] );
+
+        $http_status      = null;
+        $response_excerpt = null;
+        $error_message    = null;
+        if ( is_wp_error( $resp ) ) {
+            $error_message = $resp->get_error_message();
+        } else {
+            $http_status      = (int) wp_remote_retrieve_response_code( $resp );
+            $body             = (string) wp_remote_retrieve_body( $resp );
+            $response_excerpt = function_exists( 'mb_substr' ) ? mb_substr( $body, 0, 500 ) : substr( $body, 0, 500 );
+        }
+
+        // Determine status. Distinguishes "the receiver accepted the packet" from
+        // "the attempt was made but did not arrive cleanly". This is the difference
+        // between an attempted-emission log and a successful-receipt log; we
+        // explicitly want the former so the operator can audit transport reality.
+        //
+        //   success — HTTP 2xx received from the configured target
+        //   failed  — anything else: transport error (connection/DNS/timeout) OR
+        //             a non-2xx HTTP response (4xx/5xx etc.)
+        //
+        // 'blocked_config' is intentionally NOT used here. Config validation
+        // failed earlier returns a WP_Error with no I/O; no row is written.
+        $is_2xx = ( $error_message === null && $http_status !== null && $http_status >= 200 && $http_status < 300 );
+        $status = $is_2xx ? 'success' : 'failed';
+
+        // Log the attempt. Log-only — no analytics, no aggregation, no replay.
+        // target_url logs the actual URL hit (which is the resolved outbound,
+        // not necessarily the configured one — so dev success_mock attempts
+        // are honestly recorded as having gone to the dev-receive endpoint).
+        global $wpdb;
+        $tbl = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'attention_log';
+        $wpdb->insert( $tbl, [
+            'site_id'          => (string) $cfg['site_id'],
+            'surface'          => $payload['surface'],
+            'ref'              => $payload['ref'],
+            'target_url'       => (string) $outbound_url,
+            'payload_json'     => wp_json_encode( $payload ),
+            'status'           => $status,
+            'http_status'      => $http_status,
+            'response_excerpt' => $response_excerpt,
+            'error_message'    => $error_message,
+            'recorded_at'      => current_time( 'mysql', true ),
+        ] );
+        $log_id = (int) $wpdb->insert_id;
+
+        return rest_ensure_response( [
+            'log_id'           => $log_id,
+            'status'           => $status,
+            'http_status'      => $http_status,
+            'response_excerpt' => $response_excerpt,
+            'error_message'    => $error_message,
+            'payload'          => $payload,         // echo back so UI can confirm what went out
+            'mode_label'       => $mode_label,      // 'dev failure target' / 'dev success mock' / 'configured'
+            'target_url'       => $outbound_url,    // the URL actually hit, for UI display
+            'ok'               => $is_2xx,
+        ] );
+    }
+
+    /**
+     * Enqueue the floating "Send Attention" button on the same admin
+     * surfaces where Sara appears, gated to manage_options.
+     * Sara's bubble lives bottom-right; this button lives bottom-left.
+     */
+    public static function maybe_enqueue( $hook ) {
+        if ( ! current_user_can( 'manage_options' ) ) {
+            return;
+        }
+        $page = isset( $_GET['page'] ) ? sanitize_text_field( wp_unslash( $_GET['page'] ) ) : '';
+        $is_target = (
+            $page === 'fluent-boards'
+            || $page === 'fluent-support'
+            || strpos( $page, 'sa-orchestration' ) === 0
+        );
+        if ( ! $is_target ) {
+            return;
+        }
+
+        wp_enqueue_script(
+            self::HANDLE_JS,
+            SA_ORCH_URL . 'assets/attention-bridge.js',
+            [],
+            SA_ORCH_VERSION,
+            true
+        );
+
+        $cfg    = self::get_config();
+        $is_dev = class_exists( 'SA_Orch_Env' ) && SA_Orch_Env::is_local_or_dev();
+        wp_localize_script( self::HANDLE_JS, 'SA_ORCH_ATTENTION', [
+            'rest_url'   => esc_url_raw( rest_url( 'sa-orch/v1/attention/emit' ) ),
+            'nonce'      => wp_create_nonce( 'wp_rest' ),
+            'page'       => $page,
+            'site_id'    => $cfg['site_id'],   // for display only — not used as auth
+            'configured' => $cfg['site_id'] !== '' && $cfg['target_url'] !== '' && $cfg['token'] !== '',
+            'is_dev'     => $is_dev,           // Board #21 dev verification: when true, a second
+                                                // "Send to dev mock" button appears alongside
+                                                // the default "Send Attention". Production never
+                                                // sees this flag; the second button never renders.
+        ] );
+    }
+}

sa-orchestration/includes/class-sa-bridge-fluent.php

@@ -0,0 +1,88 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Logical bridge to Fluent (and other) surface tables.
+ * Closed enumeration — extending requires touching this class.
+ * Per SA-Core invariants I1 + I8: no DB-level FK to surface tables.
+ */
+class SA_Orch_Bridge_Fluent {
+
+    /**
+     * Resolve a (surface, ref) to the underlying surface row, or null.
+     * The 'derived' surface intentionally returns null — it has no row.
+     */
+    public static function resolve( $surface, $ref ) {
+        global $wpdb;
+
+        if ( $surface === 'derived' ) {
+            return null;
+        }
+
+        if ( $surface === 'fluent-support' && preg_match( '/^ticket#(\d+)$/', $ref, $m ) ) {
+            return $wpdb->get_row( $wpdb->prepare(
+                "SELECT * FROM {$wpdb->prefix}fs_tickets WHERE id = %d",
+                (int) $m[1]
+            ) );
+        }
+
+        if ( $surface === 'fluent-boards' && preg_match( '/^task#(\d+)$/', $ref, $m ) ) {
+            return $wpdb->get_row( $wpdb->prepare(
+                "SELECT * FROM {$wpdb->prefix}fbs_tasks WHERE id = %d",
+                (int) $m[1]
+            ) );
+        }
+
+        if ( $surface === 'fluentcrm' && preg_match( '/^subscriber#(\d+)$/', $ref, $m ) ) {
+            return $wpdb->get_row( $wpdb->prepare(
+                "SELECT * FROM {$wpdb->prefix}fc_subscribers WHERE id = %d",
+                (int) $m[1]
+            ) );
+        }
+
+        return null;
+    }
+
+    /**
+     * True if the surface/ref pair points to a real row OR is the
+     * 'derived' surface (legitimately rowless). False otherwise.
+     */
+    public static function validate( $surface, $ref ) {
+        if ( $surface === 'derived' ) {
+            return $ref !== '' && preg_match( '/^derived#[A-Za-z0-9_\-]+$/', $ref );
+        }
+        return self::resolve( $surface, $ref ) !== null;
+    }
+
+    /** Recognized surface vocabulary (closed set). */
+    public static function known_surfaces() {
+        return [ 'fluent-support', 'fluent-boards', 'fluentcrm', 'derived' ];
+    }
+
+    /**
+     * Surface adapter factory.
+     *
+     * Returns the adapter for a given surface, or null if no adapter is
+     * registered yet. Adapters are the safe path to surface data —
+     * external schema knowledge is bounded to the adapter file. Direct
+     * $wpdb access to surface tables in callers is the legacy path; new
+     * code should route through the adapter.
+     *
+     * v0.7.0 shipped one adapter (fluent-boards). Board #18 added
+     * fluent-support to the contract. fluentcrm and derived still resolve
+     * via the legacy paths in resolve() / validate() above; that carryover
+     * stays until those surfaces are ported (deferred Board #18 scope).
+     */
+    public static function adapter_for( string $surface ): ?SA_Orch_Surface_Adapter {
+        switch ( $surface ) {
+            case 'fluent-boards':
+                return new SA_Orch_Adapter_FluentBoards();
+            case 'fluent-support':
+                return new SA_Orch_Adapter_FluentSupport();
+            // Deferred (later Board):
+            // case 'fluentcrm': return new SA_Orch_Adapter_FluentCRM();
+            // case 'derived':   return new SA_Orch_Adapter_Derived();
+        }
+        return null;
+    }
+}

sa-orchestration/includes/class-sa-demand-registry.php

@@ -0,0 +1,81 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Demand Registration Hook.
+ *
+ * A surface object (ticket, task, subscriber) is NOT automatically a
+ * Demand. It exists operationally on its surface (Fluent Support, Fluent
+ * Boards, FluentCRM) but is invisible to Asterion's trace/audit/closure
+ * logic until explicitly registered.
+ *
+ * This class provides that registration. It writes an arbitration row
+ * (the canonical first entry of a Demand lifecycle) through the surface
+ * adapter — never via direct $wpdb access to surface tables.
+ *
+ * v1 surface: a single static method, callable from PHP. Future:
+ * an admin UI button or REST endpoint can wrap this.
+ *
+ * Demand Registration Boundary (per doctrine):
+ *   - Unregistered surface objects remain operational but do NOT
+ *     participate in trace, audit, or closure logic.
+ *   - They are referred to as "untracked demand candidates" until
+ *     registered.
+ */
+class SA_Orch_Demand_Registry {
+
+    /**
+     * Register a surface object as an Asterion Demand.
+     *
+     * @param string $surface           Surface id (must have a registered adapter).
+     * @param string $ref               Surface-specific ref (must validate via adapter).
+     * @param string $rationale         Human-readable rationale for arbitration.
+     * @param string $projection_type   Default 'scope-direct-no-plan'; see SA_Orch_Arbitration::write.
+     * @param string $truth_class       Default 'canonical'.
+     *
+     * @return array|WP_Error  Arbitration row data on success; WP_Error on failure.
+     */
+    public static function register(
+        string $surface,
+        string $ref,
+        string $rationale,
+        string $projection_type = 'scope-direct-no-plan',
+        string $truth_class = 'canonical'
+    ) {
+        $adapter = SA_Orch_Bridge_Fluent::adapter_for( $surface );
+        if ( ! $adapter ) {
+            return new WP_Error(
+                'no_adapter',
+                "No surface adapter registered for '{$surface}'."
+            );
+        }
+        if ( ! $adapter->validate( $ref ) ) {
+            return new WP_Error(
+                'invalid_ref',
+                "Ref '{$ref}' does not resolve under the '{$surface}' adapter."
+            );
+        }
+
+        return SA_Orch_Arbitration::write( [
+            'demand_surface'  => $surface,
+            'demand_ref'      => $ref,
+            'rationale'       => $rationale,
+            'projection_type' => $projection_type,
+            'truth_class'     => $truth_class,
+        ] );
+    }
+
+    /**
+     * Convenience: is this surface object already registered as a Demand?
+     * Returns true if at least one arbitration exists for the (surface, ref) pair.
+     */
+    public static function is_registered( string $surface, string $ref ): bool {
+        global $wpdb;
+        $arb_table = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'arbitration';
+        $count = (int) $wpdb->get_var( $wpdb->prepare(
+            "SELECT COUNT(*) FROM {$arb_table} WHERE demand_surface = %s AND demand_ref = %s",
+            $surface, $ref
+        ) );
+        return $count > 0;
+    }
+}

sa-orchestration/includes/class-sa-env.php

@@ -0,0 +1,53 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Environment classification helper.
+ *
+ * Implements the SA-Orch Environment Configuration Classification rule:
+ *
+ *   production secrets        — human-authorized only (no scaffolding)
+ *   development placeholders  — Asterion may scaffold (non-secret)
+ *   local test routing        — Asterion may scaffold (non-secret)
+ *   deploy-time constants     — Asterion may scaffold (non-secret)
+ *
+ * The line: production credentials are never auto-written. Dev/local
+ * placeholders MAY be scaffolded when the environment is *explicitly*
+ * marked local or development AND the value is clearly non-production.
+ *
+ * Source of truth for "is this local/dev":
+ *   1. WP_ENVIRONMENT_TYPE constant (WordPress canonical)
+ *   2. WP_ENVIRONMENT_TYPE environment variable (WordPress canonical)
+ *   3. Default: 'production' (safe by default)
+ *
+ * Filterable via 'sa_orch_env_type' for testing only — never used to
+ * change production behavior in real deployments.
+ */
+class SA_Orch_Env {
+
+    /**
+     * Return the current environment type. One of:
+     *   'local' | 'development' | 'staging' | 'production'
+     * Defaults to 'production' when unable to determine — production-safe.
+     */
+    public static function type(): string {
+        if ( ! function_exists( 'wp_get_environment_type' ) ) {
+            $base = 'production';
+        } else {
+            $base = (string) wp_get_environment_type();
+        }
+        // Filter for testing scenarios; production code paths never set this.
+        return (string) apply_filters( 'sa_orch_env_type', $base );
+    }
+
+    /** True iff env is explicitly local OR development. */
+    public static function is_local_or_dev(): bool {
+        $t = self::type();
+        return $t === 'local' || $t === 'development';
+    }
+
+    /** True iff env is production (the default; assume-prod-when-unsure). */
+    public static function is_production(): bool {
+        return self::type() === 'production';
+    }
+}

sa-orchestration/includes/class-sa-fluent-state.php

@@ -0,0 +1,178 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Fluent state wrapper — the single canonical entry point for orchestration-
+ * driven task movement.
+ *
+ * Why this exists:
+ *   Direct ORM stage updates ($task->stage_id = X; $task->save();) bypass
+ *   Fluent's lifecycle behavior. Specifically, they do NOT fire:
+ *     - do_action('fluent_boards/task_stage_updated', $task, $oldStageId)
+ *   which feeds:
+ *     - ActivityHandler@logTaskStageUpdatedActivity (the audit log)
+ *     - NotificationHandler@changeStageNotification (emails)
+ *     - StageChangedTrigger (FluentCRM automations)
+ *   They also leave 'status' and 'last_completed_at' stale relative to the
+ *   stage's default_task_status setting.
+ *
+ * The default path (move_task) keeps the system in sync. The gated path
+ * (move_task_silent) preserves the same state correctness but suppresses the
+ * action — for context repair / migration / latent-checks that should not
+ * generate notifications. Both paths use Fluent's own Task::close() and
+ * Task::reopen() primitives so the canonical timestamp behavior is honored.
+ *
+ * Direct ORM ($task->save() with no helpers) remains available as an
+ * implicit escape hatch for ad-hoc surgery; nothing in this class blocks it.
+ * The choice is at the call site.
+ *
+ * Architectural rule recorded:
+ *   - Protocol comment is canonical for lifecycle (Proposed/Approved/
+ *     In Progress/Blocked/Complete/Accepted).
+ *   - Fluent stage_id + status are projections of that lifecycle.
+ *   - This wrapper keeps the projection true.
+ */
+class SA_Orch_Fluent_State {
+
+    /**
+     * Move a task to a new stage and fire Fluent's lifecycle behavior.
+     *
+     * Behavior:
+     *   - reads old stage_id
+     *   - sets new stage_id, saves
+     *   - aligns status + last_completed_at via Task::close() / Task::reopen()
+     *     based on the new stage's default_task_status setting
+     *   - fires do_action('fluent_boards/task_stage_updated', $task, $oldStageId)
+     *
+     * Idempotent: if old == new stage_id, no-op returns true.
+     * Returns false if task or stage not found.
+     */
+    public static function move_task( int $task_id, int $new_stage_id, array $opts = [] ): bool {
+        return self::do_move( $task_id, $new_stage_id, true /* fire events */ );
+    }
+
+    /**
+     * Same as move_task() but does NOT fire 'fluent_boards/task_stage_updated'.
+     *
+     * Use cases (developer choice — explicitly opt-in):
+     *   - Backfilling drifted state without spamming notifications
+     *   - Repair operations during migration
+     *   - Latent-check passes outside the project board concept
+     *
+     * State correctness (status, last_completed_at) is still maintained.
+     * Only the side-channel notifications/automations are suppressed.
+     */
+    public static function move_task_silent( int $task_id, int $new_stage_id, array $opts = [] ): bool {
+        return self::do_move( $task_id, $new_stage_id, false /* suppress events */ );
+    }
+
+    /**
+     * Internal mover. Single code path; the only difference between move_task
+     * and move_task_silent is whether the action fires at the end.
+     *
+     * When $fire_events = true (default move_task path), the Description
+     * Contract gates from Board #27 also apply:
+     *   - Pre-Work gate: blocks Open → In Progress when description is empty
+     *   - Completion gate: blocks In Progress → Complete when description
+     *     lacks acceptance language ('accept', 'criteria', 'done when',
+     *     'pass when' — case-insensitive substring; deterministic, no NLP).
+     * The silent variant explicitly bypasses both gates — it's the gated
+     * developer-choice path for context repair / migration.
+     */
+    private static function do_move( int $task_id, int $new_stage_id, bool $fire_events ): bool {
+        $task = \FluentBoards\App\Models\Task::find( $task_id );
+        if ( ! $task ) {
+            return false;
+        }
+
+        $old_stage_id = (int) $task->stage_id;
+        if ( $old_stage_id === $new_stage_id ) {
+            // Idempotent no-op. Stage is already where requested.
+            return true;
+        }
+
+        $stage = \FluentBoards\App\Models\Stage::find( $new_stage_id );
+        if ( ! $stage ) {
+            return false;
+        }
+
+        // Board #27 — Description Contract gates. Apply only on default path.
+        if ( $fire_events && ! self::description_contract_passes( $task, $new_stage_id ) ) {
+            return false;
+        }
+
+        // Move the stage first so subsequent close()/reopen() observers see
+        // the new stage as the source of truth.
+        $task->stage_id = $new_stage_id;
+        $task->save();
+
+        // Align status + last_completed_at to the new stage's contract.
+        // Task::close() and Task::reopen() are Fluent's own primitives and
+        // handle the timestamp invariants correctly.
+        $default_status = $stage->defaultTaskStatus();
+        if ( $default_status === 'closed' && $task->status !== 'closed' ) {
+            $task->close();
+        } elseif ( $default_status === 'open' && $task->status === 'closed' ) {
+            $task->reopen();
+        }
+
+        if ( $fire_events ) {
+            do_action( 'fluent_boards/task_stage_updated', $task, $old_stage_id );
+        }
+
+        return true;
+    }
+
+    /**
+     * Board #27 — Description Contract gates.
+     *
+     * Returns true if the transition is allowed. Returns false (with
+     * error_log entry explaining why) if the gate blocks.
+     *
+     * Stage IDs (board 16):
+     *   131 = Open / Approved / [QUEUE]
+     *   132 = In Progress
+     *   133 = Completed
+     *
+     * Gate logic:
+     *   - Moving INTO 132 (In Progress)  → Pre-Work gate: description must be non-empty
+     *   - Moving INTO 133 (Completed)    → Completion gate: description must contain
+     *                                      one of 'accept', 'criteria', 'done when',
+     *                                      'pass when' (case-insensitive substring)
+     *   - Other stage moves              → no gate
+     *
+     * Both gates are bypassed by move_task_silent() (the gated escape hatch from #19).
+     */
+    private static function description_contract_passes( $task, int $new_stage_id ): bool {
+        $description = isset( $task->description ) ? trim( (string) $task->description ) : '';
+
+        if ( $new_stage_id === 132 ) {
+            if ( $description === '' ) {
+                error_log( "[SA-Orch #27] move_task blocked: task #{$task->id} has empty description; cannot move to In Progress. Use move_task_silent() to bypass for repair/migration." );
+                return false;
+            }
+            return true;
+        }
+
+        if ( $new_stage_id === 133 ) {
+            if ( $description === '' ) {
+                error_log( "[SA-Orch #27] move_task blocked: task #{$task->id} has empty description; cannot move to Complete. Use move_task_silent() to bypass." );
+                return false;
+            }
+            $lower    = strtolower( $description );
+            $patterns = [ 'accept', 'criteria', 'done when', 'pass when' ];
+            $hit      = false;
+            foreach ( $patterns as $p ) {
+                if ( strpos( $lower, $p ) !== false ) { $hit = true; break; }
+            }
+            if ( ! $hit ) {
+                error_log( "[SA-Orch #27] move_task blocked: task #{$task->id} description lacks acceptance language (one of: 'accept', 'criteria', 'done when', 'pass when'); cannot move to Complete. Use move_task_silent() to bypass." );
+                return false;
+            }
+            return true;
+        }
+
+        // Other stage moves: no gate.
+        return true;
+    }
+}

sa-orchestration/includes/class-sa-link.php

@@ -0,0 +1,38 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+class SA_Orch_Link {
+
+    public static function write( array $args ) {
+        global $wpdb;
+
+        $arbitration_id = isset( $args['arbitration_id'] ) ? (int) $args['arbitration_id'] : 0;
+        $plan_surface   = isset( $args['plan_surface'] )   ? trim( (string) $args['plan_surface'] )   : '';
+        $plan_ref       = isset( $args['plan_ref'] )       ? trim( (string) $args['plan_ref'] )       : '';
+        $link_kind      = isset( $args['link_kind'] )      ? trim( (string) $args['link_kind'] )      : 'derived';
+
+        if ( $arbitration_id === 0 ) {
+            return new WP_Error( 'missing_arbitration_id', 'arbitration_id is required' );
+        }
+        if ( $plan_surface === '' || $plan_ref === '' ) {
+            return new WP_Error( 'missing_plan_ref', 'plan_surface and plan_ref are required' );
+        }
+
+        $created_at = current_time( 'mysql', true );
+
+        $table = $wpdb->prefix . SA_ORCH_DB_PREFIX . 'arbitration_plan_link';
+        $ok = $wpdb->insert( $table, [
+            'arbitration_id' => $arbitration_id,
+            'plan_surface'   => $plan_surface,
+            'plan_ref'       => $plan_ref,
+            'link_kind'      => $link_kind,
+            'created_at'     => $created_at,
+        ] );
+
+        if ( $ok === false ) {
+            return new WP_Error( 'db_insert_failed', $wpdb->last_error );
+        }
+
+        return (int) $wpdb->insert_id;
+    }
+}

sa-orchestration/includes/class-sa-llm-provider-openai.php

@@ -0,0 +1,171 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * OpenAI Strategy LLM provider.
+ *
+ * Calls the OpenAI Chat Completions API (or any OpenAI-compatible endpoint:
+ * Azure OpenAI, OpenRouter, vLLM, llama.cpp server, etc.) and returns the
+ * same five-key shape the simulated provider returns.
+ *
+ * Pre-flight: throws if enabled=false, token missing, model missing, or
+ * api_base_url missing. The Strategy orchestrator catches the throw and
+ * falls back to the simulated provider, recording the error in
+ * `provider_error` for UI display.
+ *
+ * Network: uses wp_remote_post with a 30-second timeout. HTTP errors and
+ * malformed JSON also throw, triggering the same fallback.
+ *
+ * Contract enforcement: the prompt tells the model that closure_state and
+ * needs_human_arbitration are authoritative and must not be overridden.
+ * Returned JSON is also clamped server-side to the contract shape, so a
+ * misbehaving model cannot inject unexpected fields.
+ */
+class SA_Orch_LLM_Provider_OpenAI implements SA_Orch_LLM_Provider_Interface {
+
+    const REQUEST_TIMEOUT = 30;
+    const RESPONSE_BODY_PREVIEW_BYTES = 240;
+
+    public function id(): string             { return 'openai'; }
+    public function name(): string           { return 'OpenAI'; }
+    public function requires_api_key(): bool { return true; }
+
+    public function review_trace( array $trace, array $deterministic_audit ): array {
+        $settings = SA_Orch_LLM_Settings::get();
+
+        if ( empty( $settings['enabled'] ) ) {
+            throw new \RuntimeException( 'OpenAI provider: settings.enabled is false.' );
+        }
+        if ( empty( $settings['api_token'] ) ) {
+            throw new \RuntimeException( 'OpenAI provider: no api_token configured.' );
+        }
+        if ( empty( $settings['api_base_url'] ) ) {
+            throw new \RuntimeException( 'OpenAI provider: no api_base_url configured.' );
+        }
+        if ( empty( $settings['model'] ) ) {
+            throw new \RuntimeException( 'OpenAI provider: no model configured.' );
+        }
+
+        $url = rtrim( (string) $settings['api_base_url'], '/' ) . '/chat/completions';
+
+        $payload = [
+            'model'    => (string) $settings['model'],
+            'messages' => [
+                [ 'role' => 'system', 'content' => $this->system_prompt() ],
+                [ 'role' => 'user',   'content' => $this->user_prompt( $trace, $deterministic_audit ) ],
+            ],
+            'response_format' => [ 'type' => 'json_object' ],
+            'temperature'     => 0.3,
+        ];
+
+        $response = wp_remote_post( $url, [
+            'headers' => [
+                'Authorization' => 'Bearer ' . (string) $settings['api_token'],
+                'Content-Type'  => 'application/json',
+            ],
+            'body'    => wp_json_encode( $payload ),
+            'timeout' => self::REQUEST_TIMEOUT,
+        ] );
+
+        if ( is_wp_error( $response ) ) {
+            throw new \RuntimeException( 'OpenAI provider: network error — ' . $response->get_error_message() );
+        }
+
+        $code = (int) wp_remote_retrieve_response_code( $response );
+        if ( $code < 200 || $code >= 300 ) {
+            $excerpt = substr( (string) wp_remote_retrieve_body( $response ), 0, self::RESPONSE_BODY_PREVIEW_BYTES );
+            throw new \RuntimeException( "OpenAI provider: HTTP {$code} — {$excerpt}" );
+        }
+
+        $body     = (string) wp_remote_retrieve_body( $response );
+        $envelope = json_decode( $body, true );
+        if ( ! is_array( $envelope ) || ! isset( $envelope['choices'][0]['message']['content'] ) ) {
+            $excerpt = substr( $body, 0, self::RESPONSE_BODY_PREVIEW_BYTES );
+            throw new \RuntimeException( "OpenAI provider: response missing choices[0].message.content — {$excerpt}" );
+        }
+
+        $content = (string) $envelope['choices'][0]['message']['content'];
+        $parsed  = json_decode( $content, true );
+        if ( ! is_array( $parsed ) ) {
+            $excerpt = substr( $content, 0, self::RESPONSE_BODY_PREVIEW_BYTES );
+            throw new \RuntimeException( "OpenAI provider: model output is not valid JSON — {$excerpt}" );
+        }
+
+        return $this->clamp_to_contract( $parsed );
+    }
+
+    /* ---------- internals ---------- */
+
+    private function system_prompt(): string {
+        return 'You are the Strategy LLM Review layer for the SA-Orchestration plugin '
+            . '(a WordPress alignment layer above Fluent Support / Boards / CRM). '
+            . 'You receive (a) trace data for a single Demand and (b) the output of a deterministic '
+            . 'rules-based audit already computed for the same trace. Produce a brief, interpretive '
+            . "strategy review that complements — never replaces — the audit.\n\n"
+            . "Hard constraints:\n"
+            . "1. The deterministic audit's closure_state_* fields and needs_human_arbitration are authoritative. "
+            . "You MUST NOT contradict or override them. If needs_human_arbitration is true, your suggested_next_action "
+            . "MUST include escalation guidance.\n"
+            . "2. Return ONLY a JSON object with this exact shape:\n"
+            . '   {"summary": string, "agreement_with_audit": "true" | "false" | "partial", '
+            . '"additional_risks": [string, ...], "suggested_next_action": string, '
+            . '"confidence": "low" | "medium" | "high"}' . "\n"
+            . "3. summary: 2–4 sentences of narrative interpretation (not just a recount of fields).\n"
+            . "4. agreement_with_audit: 'true' if you see no risks the audit missed; 'partial' if you add risk dimensions; "
+            . "'false' only if you genuinely disagree with a finding (rare).\n"
+            . "5. additional_risks: items the deterministic audit may not have caught (stale affirmation, plan complexity, "
+            . "pattern shortcuts, semantic drift, etc.). Empty array if none.\n"
+            . "6. suggested_next_action: a single concrete next step.\n"
+            . "7. confidence: 'low' / 'medium' / 'high' — your confidence in the closure status given the trace and audit.\n"
+            . "8. CONSERVATIVE FLOOR: If no acceptance events exist OR the deterministic audit's closure_confidence is 'n/a', "
+            . "you MUST return confidence: 'low'. 'medium' and 'high' are not allowed when closure cannot be evaluated.";
+    }
+
+    private function user_prompt( array $trace, array $audit ): string {
+        $trace_payload = [
+            'demand'                   => $trace['demand']                   ?? null,
+            'arbitrations'             => $trace['arbitrations']             ?? [],
+            'plan_links'               => $trace['plan_links']               ?? [],
+            'acceptance'               => $trace['acceptance']               ?? [],
+            'closure_state_basic'      => $trace['closure_state_basic']      ?? null,
+            'closure_state_role_aware' => $trace['closure_state_role_aware'] ?? null,
+            'closure_authority_valid'  => $trace['closure_authority_valid']  ?? null,
+        ];
+        $audit_payload = [
+            'summary'                        => $audit['summary']                        ?? '',
+            'inconsistencies'                => $audit['inconsistencies']                ?? [],
+            'scope_drift'                    => $audit['scope_drift']                    ?? [],
+            'notes'                          => $audit['notes']                          ?? [],
+            'closure_confidence'             => $audit['closure_confidence']             ?? 'n/a',
+            'closure_confidence_explanation' => $audit['closure_confidence_explanation'] ?? '',
+            'needs_human_arbitration'        => $audit['needs_human_arbitration']        ?? false,
+            'human_arbitration_triggers'     => $audit['human_arbitration_triggers']     ?? [],
+        ];
+
+        return "TRACE:\n"
+            . wp_json_encode( $trace_payload, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) . "\n\n"
+            . "DETERMINISTIC AUDIT:\n"
+            . wp_json_encode( $audit_payload, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) . "\n\n"
+            . "Return your strategy review as JSON.";
+    }
+
+    /**
+     * Clamp the model's JSON output to the contract shape. A misbehaving model
+     * cannot inject extra fields or wrong types into the consumer surface.
+     */
+    private function clamp_to_contract( array $parsed ): array {
+        return [
+            'summary' => isset( $parsed['summary'] ) ? (string) $parsed['summary'] : '',
+            'agreement_with_audit' => in_array( $parsed['agreement_with_audit'] ?? '', [ 'true', 'false', 'partial' ], true )
+                ? (string) $parsed['agreement_with_audit']
+                : 'partial',
+            'additional_risks' => is_array( $parsed['additional_risks'] ?? null )
+                ? array_values( array_map( 'strval', $parsed['additional_risks'] ) )
+                : [],
+            'suggested_next_action' => isset( $parsed['suggested_next_action'] ) ? (string) $parsed['suggested_next_action'] : '',
+            'confidence' => in_array( $parsed['confidence'] ?? '', [ 'low', 'medium', 'high' ], true )
+                ? (string) $parsed['confidence']
+                : 'low',
+        ];
+    }
+}

sa-orchestration/includes/class-sa-llm-provider-simulated.php

@@ -0,0 +1,217 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Simulated Strategy LLM provider.
+ *
+ * No external API call. Pattern-based heuristic expansion of the trace +
+ * deterministic audit, written to feel LLM-like (interpretive narrative,
+ * additional risk identification, suggested next action) without making
+ * any network request.
+ *
+ * Always available as the fallback provider.
+ */
+class SA_Orch_LLM_Provider_Simulated implements SA_Orch_LLM_Provider_Interface {
+
+    public function id(): string             { return 'simulated'; }
+    public function name(): string           { return 'Simulated (no API call)'; }
+    public function requires_api_key(): bool { return false; }
+
+    public function review_trace( array $trace, array $deterministic_audit ): array {
+        $arbs       = isset( $trace['arbitrations'] ) ? (array) $trace['arbitrations'] : [];
+        $links      = isset( $trace['plan_links'] )   ? (array) $trace['plan_links']   : [];
+        $events     = isset( $trace['acceptance'] )   ? (array) $trace['acceptance']   : [];
+        $authority  = $trace['closure_authority_valid'] ?? null;
+
+        $audit_conf = $deterministic_audit['closure_confidence']   ?? 'n/a';
+        $needs_hum  = ! empty( $deterministic_audit['needs_human_arbitration'] );
+
+        $summary           = $this->build_narrative( $arbs, $links, $events, $trace, $deterministic_audit );
+        $additional_risks  = $this->identify_additional_risks( $arbs, $links, $events, $trace );
+        $agreement         = $this->determine_agreement( $additional_risks, $deterministic_audit );
+        $next_action       = $this->suggest_next_action( $audit_conf, $trace, $needs_hum, count( $additional_risks ) );
+        $confidence        = $this->compute_confidence( $audit_conf, count( $additional_risks ), $needs_hum );
+
+        return [
+            'summary'               => $summary,
+            'agreement_with_audit'  => $agreement,
+            'additional_risks'      => $additional_risks,
+            'suggested_next_action' => $next_action,
+            'confidence'            => $confidence,
+        ];
+    }
+
+    /* ---------- internals ---------- */
+
+    private function build_narrative( $arbs, $links, $events, $trace, $audit ) {
+        $arb_n   = count( $arbs );
+        $event_n = count( $events );
+        $closure_basic = $trace['closure_state_basic'] ?? null;
+        $authority     = $trace['closure_authority_valid'] ?? null;
+
+        if ( $arb_n === 0 && $event_n === 0 ) {
+            return "No trace data found for this Demand reference. The system has no record of the Demand passing through arbitration or acceptance — the surface_ref may be wrong, or this Demand has not yet been arbitrated.";
+        }
+
+        $patterns = [];
+        foreach ( $arbs as $a ) {
+            if ( ( $a->truth_class ?? null ) === 'derived' )                       $patterns['derived']    = true;
+            if ( ( $a->projection_type ?? null ) === 'scope-direct-no-plan' )      $patterns['no_plan']    = true;
+        }
+        if ( $arb_n > 1 )                                                          $patterns['multi_arb']  = true;
+        if ( $authority === false )                                                $patterns['agent_self'] = true;
+
+        $had_dispute = false;
+        foreach ( $events as $e ) {
+            if ( ( $e->event_type ?? null ) === 'acceptance_disputed' ) { $had_dispute = true; break; }
+        }
+        if ( $had_dispute )                                                        $patterns['dispute']    = true;
+        if ( $closure_basic === 'closed' && $authority === true && ! $had_dispute ) $patterns['clean']     = true;
+        if ( is_string( $closure_basic ) && strpos( $closure_basic, 'open:' ) === 0 ) $patterns['open']    = true;
+
+        $bits = [];
+
+        // Opening sentence — lead with the dominant pattern
+        if ( isset( $patterns['agent_self'] ) ) {
+            $bits[] = "The closure pattern here is concerning: the same role that claimed the result also affirmed acceptance, bypassing the originating stakeholder.";
+        } elseif ( isset( $patterns['derived'] ) && $event_n === 0 ) {
+            $bits[] = "The Demand was reconstructed from Plan-side evidence rather than captured at the originating surface. With no acceptance events on record, there is no evidence that the actual stakeholder agrees this Plan addresses their need.";
+        } elseif ( isset( $patterns['open'] ) && isset( $patterns['dispute'] ) ) {
+            $bits[] = "The Demand was claimed resolved but disputed; the dispute remains unresolved. The surface state may signal in-progress, but the strategic reality is that the original demand-constraint is unmet.";
+        } elseif ( isset( $patterns['open'] ) ) {
+            $bits[] = "The Demand is in-flight: the claim and acceptance steps are not yet complete.";
+        } elseif ( isset( $patterns['clean'] ) ) {
+            $bits[] = "This Demand followed a routine path: scoped, executed, and confirmed by the stakeholder.";
+        } else {
+            $bits[] = "The Demand chain has " . $arb_n . " arbitration" . ( $arb_n === 1 ? '' : 's' )
+                . " and " . $event_n . " acceptance event" . ( $event_n === 1 ? '' : 's' ) . " on record.";
+        }
+
+        // Mid-narrative annotations
+        if ( isset( $patterns['no_plan'] ) && isset( $patterns['clean'] ) ) {
+            $bits[] = "The Plan layer was bypassed (`scope-direct-no-plan`), suggesting an inline operational fix rather than a tracked work unit. Appropriate for small UX changes, but a recurring pattern would erode the Plan layer's value as a work-tracking signal.";
+        }
+        if ( isset( $patterns['multi_arb'] ) ) {
+            $bits[] = "Multiple arbitrations on this Demand suggest the scope was re-interpreted at least once. Each re-arbitration is an opportunity for meaning to drift from the original demand-constraint.";
+        }
+        if ( isset( $patterns['dispute'] ) && ! isset( $patterns['open'] ) ) {
+            $bits[] = "A dispute appeared earlier in the chain but was followed by an affirmation. Verify the dispute root cause was actually addressed, not merely time-elapsed.";
+        }
+
+        // Closing strategic verdict
+        if ( ! empty( $audit['needs_human_arbitration'] ) ) {
+            $bits[] = "Strategy interpretation: this trace requires human arbitration before closure can be trusted. The deterministic audit has flagged this; Strategy Review concurs.";
+        } elseif ( isset( $patterns['clean'] ) ) {
+            $bits[] = "Strategy interpretation: routine resolution. No further action required.";
+        } else {
+            $bits[] = "Strategy interpretation: defer to the deterministic audit's confidence rating before treating this Demand as resolved.";
+        }
+
+        return implode( ' ', $bits );
+    }
+
+    private function identify_additional_risks( $arbs, $links, $events, $trace ) {
+        $risks = [];
+
+        // Scope-direct-no-plan as a recurring shortcut
+        foreach ( $arbs as $a ) {
+            if ( ( $a->projection_type ?? null ) === 'scope-direct-no-plan' ) {
+                $risks[] = "Pattern shortcut watch: 'scope-direct-no-plan' arbitration may indicate a class of Demand that routinely bypasses Plan tracking. Recommend monitoring its frequency to catch systemic Plan-layer underuse.";
+                break;
+            }
+        }
+
+        // Reconstruction-then-affirmation
+        $has_derived = false;
+        foreach ( $arbs as $a ) {
+            if ( ( $a->truth_class ?? null ) === 'derived' ) { $has_derived = true; break; }
+        }
+        $has_affirm = false;
+        foreach ( $events as $e ) {
+            if ( ( $e->event_type ?? null ) === 'acceptance_affirmed' ) { $has_affirm = true; break; }
+        }
+        if ( $has_derived && $has_affirm ) {
+            $risks[] = "Reconstruction-then-affirmation: the Demand was reconstructed from Plan-side evidence and later affirmed. Verify the affirming actor saw the original Demand intent, not just the Plan they were asked to validate.";
+        }
+
+        // Stale affirmation: long gap between claim and affirm
+        $claim_time = null;
+        $affirm_time = null;
+        foreach ( $events as $e ) {
+            if ( ( $e->event_type ?? null ) === 'result_claimed' && $claim_time === null ) {
+                $claim_time = strtotime( (string) $e->observed_at );
+            }
+            if ( ( $e->event_type ?? null ) === 'acceptance_affirmed' ) {
+                $affirm_time = strtotime( (string) $e->observed_at );
+            }
+        }
+        if ( $claim_time && $affirm_time ) {
+            $delta_days = ( $affirm_time - $claim_time ) / 86400;
+            if ( $delta_days > 30 ) {
+                $risks[] = sprintf(
+                    "Stale affirmation: %d days between result_claimed and acceptance_affirmed. The stakeholder's confirmation may not reflect current state.",
+                    (int) round( $delta_days )
+                );
+            }
+        }
+
+        // Plan complexity
+        if ( count( $links ) > 2 ) {
+            $risks[] = "Plan complexity: this Demand fans out to " . count( $links ) . " plan refs. Verify each sub-plan is individually traceable to the original demand-constraint.";
+        }
+
+        // Long event chain
+        if ( count( $events ) >= 4 ) {
+            $risks[] = "State-transition complexity: " . count( $events ) . " acceptance events on this Demand. Each transition is an opportunity for meaning to drift; review for chain coherence.";
+        }
+
+        return $risks;
+    }
+
+    private function determine_agreement( $additional_risks, $audit ) {
+        // The simulated layer reads the same data — it does not contradict the audit's
+        // factual findings. Agreement is 'true' when nothing additional is identified;
+        // 'partial' when extra risk dimensions are added but the audit's findings stand.
+        if ( count( $additional_risks ) === 0 ) {
+            return 'true';
+        }
+        return 'partial';
+    }
+
+    private function suggest_next_action( $audit_conf, $trace, $needs_hum, $extra_risk_count ) {
+        if ( $needs_hum ) {
+            return "Escalate to human arbiter. The deterministic audit has flagged this trace as requiring human review; Strategy Review concurs that closure cannot be trusted without it.";
+        }
+
+        $closure_basic = $trace['closure_state_basic'] ?? null;
+
+        if ( $audit_conf === 'high' && $extra_risk_count === 0 ) {
+            return "No further action needed; routine closure.";
+        }
+        if ( $audit_conf === 'high' && $extra_risk_count > 0 ) {
+            return "Closure is sound. Optionally surface the additional risks above to the relevant stakeholders for awareness; no blocking action required.";
+        }
+        if ( $audit_conf === 'medium' ) {
+            return "Closure is sound but with notable history. Recommend a follow-up audit in 30 days to confirm the resolution held.";
+        }
+        if ( $audit_conf === 'low' && $closure_basic === 'closed' ) {
+            return "Closure is recorded but not authoritative. Drive to stakeholder affirmation before treating as final.";
+        }
+        if ( $audit_conf === 'low' && is_string( $closure_basic ) && strpos( $closure_basic, 'open:' ) === 0 ) {
+            return "Demand is open. Drive to result_claimed and stakeholder affirmation; or escalate if blocked.";
+        }
+        if ( $audit_conf === 'n/a' ) {
+            return "Demand has no acceptance events. Either drive through claim → affirmation, or close as scope-direct-no-plan if no work is owed.";
+        }
+        return "Review the deterministic audit's recommendations and the human-arbitration flag before next action.";
+    }
+
+    private function compute_confidence( $audit_conf, $extra_risk_count, $needs_hum ) {
+        if ( $needs_hum )                                            return 'low';
+        if ( $audit_conf === 'high' && $extra_risk_count === 0 )      return 'high';
+        if ( $audit_conf === 'high' && $extra_risk_count <= 2 )       return 'medium';
+        if ( $audit_conf === 'medium' )                              return 'medium';
+        if ( $audit_conf === 'n/a' )                                 return 'low';
+        return 'low';
+    }
+}

sa-orchestration/includes/class-sa-llm-providers.php

@@ -0,0 +1,67 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Provider registry + active-provider resolver.
+ *
+ * v0.5 ships with the `simulated` provider only. Future providers attach by
+ * extending the provider catalog — `get_provider_choices()` for the dropdown,
+ * `instantiate()` for the factory branch.
+ *
+ * If the saved provider id is not enabled or is unknown, the registry falls
+ * back to `simulated`. This guarantees Strategy Review always returns a result
+ * even if the operator's configured provider is unreachable.
+ */
+class SA_Orch_LLM_Providers {
+
+    /**
+     * Catalog of provider id → human label, for the settings dropdown.
+     * Only the simulated provider is wired up in v0.5; the others are listed
+     * as inert placeholders so the operator can see the seam.
+     */
+    public static function get_provider_choices(): array {
+        return [
+            'simulated' => 'Simulated (no API call) — heuristic expansion of deterministic audit',
+            'openai'    => 'OpenAI (Chat Completions; works with any OpenAI-compatible endpoint)',
+            'anthropic' => 'Anthropic (not implemented yet)',
+            'local'     => 'Local model endpoint (not implemented yet)',
+            'custom'    => 'Custom HTTP endpoint (not implemented yet)',
+        ];
+    }
+
+    /**
+     * Resolve the active provider. Falls back to simulated when:
+     *   - settings.enabled is false
+     *   - settings.provider is unknown
+     *   - the configured provider's class is not yet implemented
+     */
+    public static function get_active_provider(): SA_Orch_LLM_Provider_Interface {
+        $settings = SA_Orch_LLM_Settings::get();
+
+        if ( empty( $settings['enabled'] ) ) {
+            return new SA_Orch_LLM_Provider_Simulated();
+        }
+
+        $instance = self::instantiate( (string) ( $settings['provider'] ?? '' ) );
+        if ( $instance instanceof SA_Orch_LLM_Provider_Interface ) {
+            return $instance;
+        }
+
+        // Fallback
+        return new SA_Orch_LLM_Provider_Simulated();
+    }
+
+    private static function instantiate( $id ): ?SA_Orch_LLM_Provider_Interface {
+        switch ( $id ) {
+            case 'simulated':
+                return new SA_Orch_LLM_Provider_Simulated();
+            case 'openai':
+                return new SA_Orch_LLM_Provider_OpenAI();
+            // Future: add cases here as providers land.
+            // case 'anthropic': return new SA_Orch_LLM_Provider_Anthropic();
+            // case 'local':     return new SA_Orch_LLM_Provider_Local();
+            // case 'custom':    return new SA_Orch_LLM_Provider_Custom();
+        }
+        return null;
+    }
+}

sa-orchestration/includes/class-sa-llm-settings.php

@@ -0,0 +1,62 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * LLM provider settings.
+ *
+ * Stored in a single WordPress option (`sa_orch_llm_settings`).
+ * Local-dev posture only. Tokens are never displayed back; saving with an
+ * empty token field preserves the existing token.
+ *
+ * Future: this layer is the attachment seam — when a real key vault /
+ * SA-Core secret handling is wired up, replace the wp_options storage here
+ * without changing the consumer surface (get(), has_token()).
+ */
+class SA_Orch_LLM_Settings {
+
+    const OPTION = 'sa_orch_llm_settings';
+
+    public static function get(): array {
+        $defaults = [
+            'enabled'      => false,
+            'provider'     => 'simulated',
+            'model'        => '',
+            'api_base_url' => '',
+            'api_token'    => '',
+        ];
+        $stored = get_option( self::OPTION, [] );
+        if ( ! is_array( $stored ) ) $stored = [];
+        return wp_parse_args( $stored, $defaults );
+    }
+
+    /**
+     * Save settings. Token field preserves the existing value when input is empty.
+     */
+    public static function save( array $input ): void {
+        $current = self::get();
+        $new = [
+            'enabled'      => ! empty( $input['enabled'] ),
+            'provider'     => sanitize_key( $input['provider'] ?? 'simulated' ),
+            'model'        => sanitize_text_field( $input['model'] ?? '' ),
+            'api_base_url' => esc_url_raw( $input['api_base_url'] ?? '' ),
+            'api_token'    => ! empty( $input['api_token'] )
+                ? (string) $input['api_token']
+                : (string) $current['api_token'],
+        ];
+        update_option( self::OPTION, $new );
+    }
+
+    public static function has_token(): bool {
+        $s = self::get();
+        return ! empty( $s['api_token'] );
+    }
+
+    /**
+     * Public-facing label for the saved-token state. Never returns the value itself.
+     */
+    public static function token_status_label(): string {
+        return self::has_token()
+            ? '[token is set; leave blank to preserve, enter a new value to update]'
+            : '[no token saved]';
+    }
+}

sa-orchestration/includes/class-sa-migrations.php

@@ -0,0 +1,161 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+class SA_Orch_Migrations {
+
+    public static function install() {
+        global $wpdb;
+
+        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+        $charset = $wpdb->get_charset_collate();
+        $p       = $wpdb->prefix . SA_ORCH_DB_PREFIX;
+
+        // wp_sa_arbitration
+        $sql_arb = "CREATE TABLE {$p}arbitration (
+            id              BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            hash            VARCHAR(64) NOT NULL,
+            demand_surface  VARCHAR(64) NOT NULL,
+            demand_ref      VARCHAR(255) NOT NULL,
+            rationale       TEXT NOT NULL,
+            projection_type VARCHAR(64) NOT NULL,
+            actor_user_id   BIGINT UNSIGNED DEFAULT NULL,
+            correlation_id  VARCHAR(64) NOT NULL,
+            causation_id    VARCHAR(64) DEFAULT NULL,
+            truth_class     VARCHAR(32) NOT NULL DEFAULT 'canonical',
+            asterion_path   VARCHAR(255) DEFAULT NULL,
+            created_at      DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY uniq_hash (hash),
+            KEY idx_demand   (demand_surface, demand_ref),
+            KEY idx_corr     (correlation_id),
+            KEY idx_created  (created_at)
+        ) $charset;";
+
+        // wp_sa_arbitration_plan_link
+        $sql_link = "CREATE TABLE {$p}arbitration_plan_link (
+            id              BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            arbitration_id  BIGINT UNSIGNED NOT NULL,
+            plan_surface    VARCHAR(64) NOT NULL,
+            plan_ref        VARCHAR(255) NOT NULL,
+            link_kind       VARCHAR(32) NOT NULL DEFAULT 'derived',
+            created_at      DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            KEY idx_arb     (arbitration_id),
+            KEY idx_plan    (plan_surface, plan_ref)
+        ) $charset;";
+
+        // wp_sa_acceptance_event
+        $sql_acc = "CREATE TABLE {$p}acceptance_event (
+            id              BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            hash            VARCHAR(64) NOT NULL,
+            demand_surface  VARCHAR(64) NOT NULL,
+            demand_ref      VARCHAR(255) NOT NULL,
+            event_type      VARCHAR(32) NOT NULL,
+            prior_event_id  BIGINT UNSIGNED DEFAULT NULL,
+            actor_user_id   BIGINT UNSIGNED DEFAULT NULL,
+            actor_role      VARCHAR(32) NOT NULL,
+            details         TEXT DEFAULT NULL,
+            truth_class     VARCHAR(32) NOT NULL DEFAULT 'canonical',
+            asterion_path   VARCHAR(255) DEFAULT NULL,
+            observed_at     DATETIME NOT NULL,
+            recorded_at     DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY uniq_hash (hash),
+            KEY idx_demand_time (demand_surface, demand_ref, observed_at),
+            KEY idx_event_type  (event_type)
+        ) $charset;";
+
+        // wp_sa_attention_log — Board #21 (Attention Bridge REST).
+        //
+        // SEMANTICS: this is an ATTEMPTED-EMISSION log, NOT a successful-receipt log.
+        // A row records that an emit was attempted; the 'status' column tells you
+        // whether the receiver accepted it.
+        //
+        // status enum (Board #21 rev2):
+        //   'success'        — outbound POST returned HTTP 2xx; receiver accepted the packet
+        //   'failed'         — transport error (connection refused, DNS, timeout) OR non-2xx HTTP response
+        //   'blocked_config' — RESERVED. Currently never written. If config validation fails,
+        //                      no log row is created at all (validation precedes any I/O). The value
+        //                      is reserved for future use cases (e.g. partial-config emission attempts).
+        //
+        // NOT a query/analytics store. Captures:
+        //   - what was attempted (full payload_json)
+        //   - whether it arrived (status + http_status + response_excerpt OR error_message)
+        // Per stakeholder spec: "Did packet arrive? What did it contain?"
+        $sql_attn = "CREATE TABLE {$p}attention_log (
+            id              BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            site_id         VARCHAR(64) NOT NULL,
+            surface         VARCHAR(64) DEFAULT NULL,
+            ref             VARCHAR(255) DEFAULT NULL,
+            target_url      VARCHAR(512) NOT NULL,
+            payload_json    TEXT NOT NULL,
+            status          VARCHAR(16) DEFAULT NULL,
+            http_status     INT DEFAULT NULL,
+            response_excerpt TEXT DEFAULT NULL,
+            error_message   TEXT DEFAULT NULL,
+            recorded_at     DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            KEY idx_site_time (site_id, recorded_at),
+            KEY idx_status    (status)
+        ) $charset;";
+
+        // wp_sa_token_log — Board #16 (Token + Usage Visibility).
+        // Append-only audit of LLM invocations. Each call writes one row.
+        // (comment_kind, comment_id) is filled in later by the future
+        // invocation surface; until then, all rows have nulls there and
+        // the Board #23 filter callback returns false for all comments.
+        $sql_token = "CREATE TABLE {$p}token_log (
+            id              BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            user_id         BIGINT UNSIGNED DEFAULT NULL,
+            provider        VARCHAR(64) NOT NULL,
+            model           VARCHAR(128) DEFAULT NULL,
+            prompt_tokens   INT UNSIGNED DEFAULT 0,
+            completion_tokens INT UNSIGNED DEFAULT 0,
+            total_tokens    INT UNSIGNED DEFAULT 0,
+            comment_kind    VARCHAR(32) DEFAULT NULL,
+            comment_id      BIGINT UNSIGNED DEFAULT NULL,
+            invoked_at      DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            KEY idx_user_time (user_id, invoked_at),
+            KEY idx_comment   (comment_kind, comment_id)
+        ) $charset;";
+
+        // wp_sa_actor_handoff — Board #23 (Actor Handoff Log).
+        // Two-axis attribution log. Records who "pressed send" for an
+        // actor-authored comment. Strictly additive — does NOT touch
+        // fbs_comments / fs_conversations.
+        $sql_handoff = "CREATE TABLE {$p}actor_handoff (
+            id              BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            comment_kind    VARCHAR(32) NOT NULL,
+            comment_id      BIGINT UNSIGNED NOT NULL,
+            committed_by_user_id BIGINT UNSIGNED NOT NULL,
+            recorded_at     DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            KEY idx_comment   (comment_kind, comment_id),
+            KEY idx_committer (committed_by_user_id, recorded_at)
+        ) $charset;";
+
+        dbDelta( $sql_arb );
+        dbDelta( $sql_link );
+        dbDelta( $sql_acc );
+        dbDelta( $sql_attn );
+        dbDelta( $sql_handoff );
+        dbDelta( $sql_token );
+
+        // Asterion ledger root
+        $root = SA_Orch_Asterion::root();
+        if ( ! is_dir( $root ) ) {
+            wp_mkdir_p( $root );
+        }
+        $marker = $root . '/.sa-asterion';
+        if ( ! file_exists( $marker ) ) {
+            file_put_contents(
+                $marker,
+                "Asterion ledger root for SA-Orchestration plugin.\n"
+                . "Canonical-at-write store. Runtime DB at {$wpdb->prefix}{$p}* is a cache.\n"
+                . "If runtime != Asterion, runtime is the lie.\n"
+            );
+        }
+    }
+}

sa-orchestration/includes/class-sa-projection-fluent-support.php

@@ -0,0 +1,521 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Partial projection: SA-Orchestration → Fluent Support.
+ *
+ * Augments tickets with [SA-Orch]-namespaced metadata and conversation entries.
+ * NEVER touches Fluent's native ticket fields (status, resolved_at, closed_by,
+ * title, content, customer_id, etc.). Removable cleanly without breaking Fluent.
+ *
+ * v0.6.1 — refined UX:
+ *   - Two conversation entries per ticket (was: 1 + N + 1):
+ *       1. Tracking marker (created once, never updated, not pinned).
+ *       2. State summary (upserts in place; pinned only when needs review).
+ *   - Per-event entries removed; full event history lives in the admin trace.
+ *   - Needs-Human folds into the state summary with a clear "Action:" line.
+ *   - Phrasing rewritten for native voice (less jargon, fewer field-name leaks).
+ *
+ * Augmentations written:
+ *
+ *   1. Meta on the ticket (via wp_fs_meta with object_type='ticket'):
+ *        _sa_orch_arbitration_hash    — most recent arbitration hash for this Demand.
+ *        _sa_orch_needs_human         — 'true' | 'false'.
+ *        _sa_orch_closure_authority   — stakeholder | agent | system | inferred | (empty).
+ *
+ *   2. Tracking marker conversation (one per ticket, ensure-once, never updated).
+ *
+ *   3. State summary conversation (one per ticket, upserts in place). Header
+ *      reflects current state ("Closed", "Result claimed",
+ *      "Needs review — disputed", etc.). When needs review, body includes an
+ *      actionable "Action:" line and the entry is pinned (is_important=yes).
+ *
+ * Identification on removal:
+ *   - All meta keys begin with `_sa_orch_`.
+ *   - All conversation entries have source = `sa-orch`.
+ *
+ * Removability:
+ *   SA_Orch_Projection_Fluent_Support::remove_all_for_ticket( $id )  — single ticket
+ *   SA_Orch_Projection_Fluent_Support::remove_all()                  — global cleanup
+ *
+ * Hook contract:
+ *   `sa_orch_arbitration_written`      — fired by SA_Orch_Arbitration::write
+ *   `sa_orch_acceptance_event_written` — fired by SA_Orch_Acceptance::write
+ *   This class subscribes to both and triggers project_ticket() when the
+ *   demand_surface is fluent-support.
+ */
+class SA_Orch_Projection_Fluent_Support {
+
+    const META_PREFIX = '_sa_orch_';
+    const CONV_SOURCE = 'sa-orch';
+    const TRACKED_KEY = 'sa-orch-tracked-';
+    const STATE_KEY   = 'sa-orch-state-';
+
+    /** Default fallback person_id for system entries. Overridden if a real person matches actor_user_id. */
+    private static $system_person_id = null;
+
+    /** Wired in sa-orchestration.php on the WP `init` action. */
+    public static function register_hooks() {
+        add_action( 'sa_orch_arbitration_written',      [ __CLASS__, 'on_arbitration_written' ] );
+        add_action( 'sa_orch_acceptance_event_written', [ __CLASS__, 'on_acceptance_written' ] );
+    }
+
+    public static function on_arbitration_written( $payload ) {
+        if ( ! is_array( $payload ) ) return;
+        $surface = $payload['demand_surface'] ?? '';
+        $ref     = $payload['demand_ref']     ?? '';
+        if ( $surface !== 'fluent-support' ) return;
+        if ( ! preg_match( '/^ticket#(\d+)$/', (string) $ref, $m ) ) return;
+        try { self::project_ticket( (int) $m[1] ); }
+        catch ( \Throwable $e ) { error_log( 'SA-Orch projection (fluent-support) failed: ' . $e->getMessage() ); }
+    }
+
+    public static function on_acceptance_written( $payload ) {
+        if ( ! is_array( $payload ) ) return;
+        $surface = $payload['demand_surface'] ?? '';
+        $ref     = $payload['demand_ref']     ?? '';
+        if ( $surface !== 'fluent-support' ) return;
+        if ( ! preg_match( '/^ticket#(\d+)$/', (string) $ref, $m ) ) return;
+        try { self::project_ticket( (int) $m[1] ); }
+        catch ( \Throwable $e ) { error_log( 'SA-Orch projection (fluent-support) failed: ' . $e->getMessage() ); }
+    }
+
+    /**
+     * Project all SA-Orch state for a Demand-bound ticket as Fluent Support
+     * augmentations. Idempotent — safe to call any number of times.
+     */
+    public static function project_ticket( $ticket_id ) {
+        global $wpdb;
+
+        $report = [
+            'ticket_id'       => (int) $ticket_id,
+            'meta_written'    => 0,
+            'tracked_written' => false,
+            'tracked_updated' => false,
+            'state_inserted'  => false,
+            'state_updated'   => false,
+            'legacy_pruned'   => 0,
+            'skipped_reason'  => null,
+        ];
+
+        $ticket = $wpdb->get_row( $wpdb->prepare(
+            "SELECT id FROM {$wpdb->prefix}fs_tickets WHERE id = %d",
+            $ticket_id
+        ) );
+        if ( ! $ticket ) {
+            $report['skipped_reason'] = 'ticket-not-found';
+            return $report;
+        }
+
+        $surface = 'fluent-support';
+        $ref     = 'ticket#' . (int) $ticket_id;
+
+        $arbitrations = $wpdb->get_results( $wpdb->prepare(
+            "SELECT id, hash, truth_class, projection_type FROM {$wpdb->prefix}sa_arbitration
+             WHERE demand_surface = %s AND demand_ref = %s ORDER BY created_at, id",
+            $surface, $ref
+        ) );
+        $events = $wpdb->get_results( $wpdb->prepare(
+            "SELECT * FROM {$wpdb->prefix}sa_acceptance_event
+             WHERE demand_surface = %s AND demand_ref = %s ORDER BY observed_at, id",
+            $surface, $ref
+        ) );
+
+        if ( empty( $arbitrations ) && empty( $events ) ) {
+            self::remove_all_for_ticket( $ticket_id );
+            $report['skipped_reason'] = 'no-sa-orch-data';
+            return $report;
+        }
+
+        // ----- Meta -----
+        $latest_arb       = end( $arbitrations );
+        $arbitration_hash = $latest_arb ? (string) $latest_arb->hash : '';
+        $latest_event     = ! empty( $events ) ? end( $events ) : null;
+        $needs_human      = self::compute_needs_human( $arbitrations, $events );
+
+        $closure_authority = '';
+        if ( $latest_event && $latest_event->event_type === 'acceptance_affirmed' ) {
+            $closure_authority = (string) $latest_event->actor_role;
+        }
+
+        self::set_meta( $ticket_id, 'arbitration_hash',  $arbitration_hash );             $report['meta_written']++;
+        self::set_meta( $ticket_id, 'needs_human',       $needs_human ? 'true' : 'false' ); $report['meta_written']++;
+        self::set_meta( $ticket_id, 'closure_authority', $closure_authority );            $report['meta_written']++;
+
+        // ----- Entry 1: Tracking marker (upserts in place so phrasing/pin rule changes propagate) -----
+        $tracked_result = self::upsert_conversation(
+            $ticket_id,
+            'internal_info',
+            self::tracking_marker_text( $ticket_id ),
+            self::TRACKED_KEY . $ticket_id,
+            'no',
+            self::resolve_person_id( null )
+        );
+        $report['tracked_written'] = $tracked_result['inserted'];
+        $report['tracked_updated'] = $tracked_result['updated'];
+
+        // ----- Entry 2: State summary (upserts in place) -----
+        $state_content = self::build_state_summary( $ticket_id, $arbitrations, $events, $needs_human );
+        $state_pinned  = $needs_human ? 'yes' : 'no';
+        $state_actor   = $latest_event && $latest_event->actor_user_id ? (int) $latest_event->actor_user_id : null;
+        $state_result  = self::upsert_conversation(
+            $ticket_id,
+            'internal_info',
+            $state_content,
+            self::STATE_KEY . $ticket_id,
+            $state_pinned,
+            self::resolve_person_id( $state_actor )
+        );
+        $report['state_inserted'] = $state_result['inserted'];
+        $report['state_updated']  = $state_result['updated'];
+
+        // ----- Legacy cleanup: prune v0.6.0-era per-event and standalone needs-human rows -----
+        $report['legacy_pruned'] = self::prune_legacy_sa_orch_rows( $ticket_id );
+
+        return $report;
+    }
+
+    /* ---------- Phrasing helpers ---------- */
+
+    private static function tracking_marker_text( $ticket_id ) {
+        return "[SA-Orch] Tracking this ticket.\n"
+             . "Full record (arbitrations, acceptance events, audit) in WP Admin → SA-Orchestration → Demand Trace → ticket#{$ticket_id}.";
+    }
+
+    private static function build_state_summary( $ticket_id, $arbitrations, $events, $needs_human ) {
+        $latest_event = ! empty( $events ) ? end( $events ) : null;
+        $admin_link   = "WP Admin → SA-Orchestration → Demand Trace → ticket#{$ticket_id}";
+
+        $header = self::state_header( $latest_event, $arbitrations, $needs_human );
+        $body   = self::state_body(   $latest_event, $arbitrations );
+
+        $lines = [];
+        $lines[] = "[SA-Orch] {$header}";
+        if ( $body !== '' ) $lines[] = $body;
+        if ( $needs_human ) {
+            $lines[] = 'Action: ' . self::state_action( $latest_event, $arbitrations );
+        }
+        $lines[] = "Trace: {$admin_link}";
+        return implode( "\n", $lines );
+    }
+
+    private static function state_header( $latest_event, $arbitrations, $needs_human ) {
+        if ( $needs_human ) {
+            // Pick the most actionable trigger as the primary header.
+            if ( $latest_event && $latest_event->event_type === 'acceptance_disputed' ) {
+                return 'Needs review — disputed';
+            }
+            if ( $latest_event && $latest_event->event_type === 'acceptance_affirmed' && $latest_event->actor_role !== 'stakeholder' ) {
+                return 'Needs review — closure not authoritative';
+            }
+            if ( count( $arbitrations ) > 1 ) {
+                return 'Needs review — multiple arbitrations on this ticket';
+            }
+            foreach ( $arbitrations as $arb ) {
+                if ( ( $arb->truth_class ?? '' ) === 'derived' ) {
+                    return 'Needs review — Demand reconstructed from indirect signals';
+                }
+            }
+            return 'Needs review';
+        }
+        if ( ! $latest_event ) {
+            return 'Tracking — awaiting result';
+        }
+        switch ( $latest_event->event_type ) {
+            case 'result_claimed':      return 'Result claimed — awaiting affirmation';
+            case 'acceptance_affirmed': return 'Closed — stakeholder affirmation';
+            case 'acceptance_revoked':  return 'Revoked — open again';
+            case 'acceptance_disputed': return 'Disputed';
+        }
+        return 'Tracking';
+    }
+
+    private static function state_body( $latest_event, $arbitrations ) {
+        if ( ! $latest_event ) {
+            $arb_count = count( $arbitrations );
+            if ( $arb_count > 1 ) {
+                return "{$arb_count} arbitrations on file. No acceptance events yet.";
+            }
+            return 'An arbitration is on file. No result has been claimed yet.';
+        }
+
+        $when  = self::pretty_date( $latest_event->observed_at );
+        $actor = self::actor_phrase( $latest_event->actor_role );
+
+        switch ( $latest_event->event_type ) {
+            case 'result_claimed':
+                return "A result was claimed by {$actor} on {$when}. Awaiting stakeholder affirmation.";
+            case 'acceptance_affirmed':
+                if ( $latest_event->actor_role === 'stakeholder' ) {
+                    return "The stakeholder affirmed acceptance on {$when}. Closure is authoritative.";
+                }
+                return "Acceptance was affirmed by {$actor} on {$when} — but only the stakeholder can authoritatively close.";
+            case 'acceptance_disputed':
+                return "A dispute was recorded by {$actor} on {$when}. Closure is blocked until the dispute is resolved.";
+            case 'acceptance_revoked':
+                return "An earlier affirmation was revoked by {$actor} on {$when}. The Demand is open again.";
+        }
+        return '';
+    }
+
+    private static function state_action( $latest_event, $arbitrations ) {
+        if ( $latest_event ) {
+            if ( $latest_event->event_type === 'acceptance_disputed' ) {
+                return 'resolve the dispute, then have the stakeholder affirm or revoke.';
+            }
+            if ( $latest_event->event_type === 'acceptance_affirmed' && $latest_event->actor_role !== 'stakeholder' ) {
+                return 'ask the stakeholder to affirm the result, or record their actual response (affirm or dispute).';
+            }
+        }
+        if ( count( $arbitrations ) > 1 ) {
+            return 'reconcile the multiple arbitrations on this ticket before relying on closure.';
+        }
+        foreach ( $arbitrations as $arb ) {
+            if ( ( $arb->truth_class ?? '' ) === 'derived' ) {
+                return 'confirm the reconstructed Demand with the stakeholder before treating it as canonical.';
+            }
+        }
+        return 'review the trace and decide whether closure is appropriate.';
+    }
+
+    private static function actor_phrase( $actor_role ) {
+        switch ( $actor_role ) {
+            case 'stakeholder': return 'the stakeholder';
+            case 'agent':       return 'an agent';
+            case 'system':      return 'the system';
+            case 'inferred':    return 'an inferred actor';
+        }
+        return (string) $actor_role;
+    }
+
+    private static function pretty_date( $mysql_datetime ) {
+        if ( empty( $mysql_datetime ) ) return '(unknown)';
+        $ts = strtotime( $mysql_datetime );
+        if ( ! $ts ) return $mysql_datetime;
+        return gmdate( 'Y-m-d H:i', $ts ) . ' UTC';
+    }
+
+    /* ---------- Audit-mirror helpers (unchanged from v0.6.0) ---------- */
+
+    private static function compute_needs_human( $arbitrations, $events ) {
+        if ( ! empty( $events ) ) {
+            $latest = end( $events );
+            if ( $latest->event_type === 'acceptance_disputed' ) return true;
+            if ( $latest->event_type === 'acceptance_affirmed' && $latest->actor_role !== 'stakeholder' ) {
+                return true;
+            }
+        }
+        if ( empty( $events ) ) {
+            foreach ( $arbitrations as $arb ) {
+                if ( ( $arb->truth_class ?? '' ) === 'derived' ) return true;
+            }
+        }
+        if ( count( $arbitrations ) > 1 ) return true;
+        return false;
+    }
+
+    /* ---------- Meta + conversation writers ---------- */
+
+    private static function set_meta( $ticket_id, $key_short, $value ) {
+        global $wpdb;
+        $table = $wpdb->prefix . 'fs_meta';
+        $key   = self::META_PREFIX . $key_short;
+
+        $existing = $wpdb->get_var( $wpdb->prepare(
+            "SELECT id FROM {$table} WHERE object_type = %s AND object_id = %d AND `key` = %s LIMIT 1",
+            'ticket', (int) $ticket_id, $key
+        ) );
+        $now = current_time( 'mysql', true );
+        if ( $existing ) {
+            $wpdb->update(
+                $table,
+                [ 'value' => (string) $value, 'updated_at' => $now ],
+                [ 'id' => (int) $existing ]
+            );
+        } else {
+            $wpdb->insert( $table, [
+                'object_type' => 'ticket',
+                'object_id'   => (int) $ticket_id,
+                'key'         => $key,
+                'value'       => (string) $value,
+                'created_at'  => $now,
+                'updated_at'  => $now,
+            ] );
+        }
+    }
+
+    /**
+     * Insert-only by stable idempotency key. Used for the tracking marker.
+     */
+    private static function ensure_conversation( $ticket_id, $conversation_type, $content, $idempotency_key, $is_important, $person_id ) {
+        global $wpdb;
+        $table        = $wpdb->prefix . 'fs_conversations';
+        $content_hash = md5( $idempotency_key );
+
+        $existing = $wpdb->get_var( $wpdb->prepare(
+            "SELECT id FROM {$table} WHERE ticket_id = %d AND content_hash = %s AND source = %s LIMIT 1",
+            (int) $ticket_id, $content_hash, self::CONV_SOURCE
+        ) );
+        if ( $existing ) return false;
+
+        $now = current_time( 'mysql', true );
+        $wpdb->insert( $table, [
+            'serial'            => 1,
+            'ticket_id'         => (int) $ticket_id,
+            'person_id'         => (int) $person_id,
+            'conversation_type' => $conversation_type,
+            'content'           => $content,
+            'source'            => self::CONV_SOURCE,
+            'content_hash'      => $content_hash,
+            'is_important'      => ( $is_important === 'yes' ? 'yes' : 'no' ),
+            'created_at'        => $now,
+            'updated_at'        => $now,
+        ] );
+        return true;
+    }
+
+    /**
+     * Upsert by stable idempotency key. Used for the state summary.
+     * Returns ['inserted' => bool, 'updated' => bool] — at most one is true.
+     */
+    private static function upsert_conversation( $ticket_id, $conversation_type, $content, $idempotency_key, $is_important, $person_id ) {
+        global $wpdb;
+        $table        = $wpdb->prefix . 'fs_conversations';
+        $content_hash = md5( $idempotency_key );
+        $now          = current_time( 'mysql', true );
+        $important    = ( $is_important === 'yes' ? 'yes' : 'no' );
+
+        $existing = $wpdb->get_row( $wpdb->prepare(
+            "SELECT id, content, is_important FROM {$table}
+              WHERE ticket_id = %d AND content_hash = %s AND source = %s LIMIT 1",
+            (int) $ticket_id, $content_hash, self::CONV_SOURCE
+        ) );
+
+        if ( $existing ) {
+            // Skip update if nothing actually changed — preserves a stable updated_at.
+            if ( $existing->content === $content && $existing->is_important === $important ) {
+                return [ 'inserted' => false, 'updated' => false ];
+            }
+            $wpdb->update(
+                $table,
+                [
+                    'content'      => $content,
+                    'is_important' => $important,
+                    'person_id'    => (int) $person_id,
+                    'updated_at'   => $now,
+                ],
+                [ 'id' => (int) $existing->id ]
+            );
+            return [ 'inserted' => false, 'updated' => true ];
+        }
+
+        $wpdb->insert( $table, [
+            'serial'            => 1,
+            'ticket_id'         => (int) $ticket_id,
+            'person_id'         => (int) $person_id,
+            'conversation_type' => $conversation_type,
+            'content'           => $content,
+            'source'            => self::CONV_SOURCE,
+            'content_hash'      => $content_hash,
+            'is_important'      => $important,
+            'created_at'        => $now,
+            'updated_at'        => $now,
+        ] );
+        return [ 'inserted' => true, 'updated' => false ];
+    }
+
+    /**
+     * Drop SA-Orch conversation rows for this ticket that are NOT the canonical
+     * tracking-marker or state-summary entries. v0.6.0 emitted per-event entries
+     * and a separate needs-human entry; v0.6.1 collapses both into the state
+     * summary, so any leftover rows from v0.6.0 should be pruned on re-projection.
+     */
+    private static function prune_legacy_sa_orch_rows( $ticket_id ) {
+        global $wpdb;
+        $tracked_hash = md5( self::TRACKED_KEY . $ticket_id );
+        $state_hash   = md5( self::STATE_KEY   . $ticket_id );
+        $deleted = $wpdb->query( $wpdb->prepare(
+            "DELETE FROM {$wpdb->prefix}fs_conversations
+              WHERE ticket_id = %d AND source = %s
+                AND content_hash NOT IN ( %s, %s )",
+            (int) $ticket_id, self::CONV_SOURCE, $tracked_hash, $state_hash
+        ) );
+        return (int) $deleted;
+    }
+
+    private static function resolve_person_id( $actor_user_id ) {
+        global $wpdb;
+        $actor_user_id = (int) $actor_user_id;
+        if ( $actor_user_id > 0 ) {
+            $person = $wpdb->get_var( $wpdb->prepare(
+                "SELECT id FROM {$wpdb->prefix}fs_persons WHERE user_id = %d AND person_type = 'agent' LIMIT 1",
+                $actor_user_id
+            ) );
+            if ( $person ) return (int) $person;
+        }
+        if ( self::$system_person_id !== null ) return self::$system_person_id;
+
+        $admin_person = $wpdb->get_var(
+            "SELECT p.id FROM {$wpdb->prefix}fs_persons p
+              JOIN {$wpdb->users} u ON u.ID = p.user_id
+             WHERE p.person_type = 'agent' AND u.user_login = 'admin'
+             LIMIT 1"
+        );
+        if ( $admin_person ) {
+            self::$system_person_id = (int) $admin_person;
+            return self::$system_person_id;
+        }
+        $any_agent = $wpdb->get_var(
+            "SELECT id FROM {$wpdb->prefix}fs_persons WHERE person_type = 'agent' ORDER BY id LIMIT 1"
+        );
+        self::$system_person_id = $any_agent ? (int) $any_agent : 1;
+        return self::$system_person_id;
+    }
+
+    /* ---------- Cleanup ---------- */
+
+    public static function remove_all_for_ticket( $ticket_id ) {
+        global $wpdb;
+        $meta_deleted = $wpdb->query( $wpdb->prepare(
+            "DELETE FROM {$wpdb->prefix}fs_meta WHERE object_type = 'ticket' AND object_id = %d AND `key` LIKE %s",
+            (int) $ticket_id, $wpdb->esc_like( self::META_PREFIX ) . '%'
+        ) );
+        $conv_deleted = $wpdb->query( $wpdb->prepare(
+            "DELETE FROM {$wpdb->prefix}fs_conversations WHERE ticket_id = %d AND source = %s",
+            (int) $ticket_id, self::CONV_SOURCE
+        ) );
+        return [ 'meta_rows' => (int) $meta_deleted, 'conversation_rows' => (int) $conv_deleted ];
+    }
+
+    public static function remove_all() {
+        global $wpdb;
+        $meta_deleted = $wpdb->query( $wpdb->prepare(
+            "DELETE FROM {$wpdb->prefix}fs_meta WHERE object_type = 'ticket' AND `key` LIKE %s",
+            $wpdb->esc_like( self::META_PREFIX ) . '%'
+        ) );
+        $conv_deleted = $wpdb->query( $wpdb->prepare(
+            "DELETE FROM {$wpdb->prefix}fs_conversations WHERE source = %s",
+            self::CONV_SOURCE
+        ) );
+        return [ 'meta_rows' => (int) $meta_deleted, 'conversation_rows' => (int) $conv_deleted ];
+    }
+
+    public static function backfill_all() {
+        global $wpdb;
+        $rows = $wpdb->get_col(
+            "SELECT DISTINCT CAST(SUBSTRING(demand_ref, 8) AS UNSIGNED) AS ticket_id
+               FROM {$wpdb->prefix}sa_arbitration
+              WHERE demand_surface = 'fluent-support' AND demand_ref LIKE 'ticket#%'
+              UNION
+             SELECT DISTINCT CAST(SUBSTRING(demand_ref, 8) AS UNSIGNED) AS ticket_id
+               FROM {$wpdb->prefix}sa_acceptance_event
+              WHERE demand_surface = 'fluent-support' AND demand_ref LIKE 'ticket#%'"
+        );
+        $reports = [];
+        foreach ( $rows as $tid ) {
+            $tid = (int) $tid;
+            if ( $tid > 0 ) $reports[] = self::project_ticket( $tid );
+        }
+        return $reports;
+    }
+}

sa-orchestration/includes/class-sa-reasoning.php

@@ -0,0 +1,334 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Deterministic Trace Audit.
+ *
+ * Local rules-based checks over a Demand trace. Repeatable, side-effect-free,
+ * no external API, no LLM, no state stored. Pure function over the trace array
+ * as returned by SA_Orch_Rest::get_demand_trace().
+ *
+ * This is the FLOOR of a four-layer review stack:
+ *
+ *   (1) Trace data                — what is in the database / Asterion ledger.
+ *   (2) Deterministic Trace Audit — this layer. Rules-only, repeatable, fast.
+ *   (3) Strategy LLM Review       — FUTURE. Sits above this layer and compares
+ *                                   its reasoning against the deterministic audit.
+ *                                   The audit becomes a sanity-check / fallback
+ *                                   when the LLM layer is wired up.
+ *   (4) Human arbitration         — final meaning. Always wins.
+ *
+ * The class name `SA_Orch_Reasoning` is preserved as the long-term contract;
+ * v0.4 implements only the deterministic layer. When LLM review is added, it
+ * will live alongside this audit (the audit will not be replaced).
+ *
+ * Rules implemented in v0.4 (minimal deterministic set):
+ *   - Closure authority invalid (acceptance_affirmed by non-stakeholder)
+ *   - projection_type ↔ plan_link count mismatch
+ *   - Affirmation without prior result_claimed
+ *   - prior_event_id chain integrity
+ *   - Multiple arbitrations on same Demand → scope drift
+ *   - projection_type other than scope-direct(-no-plan) → scope drift
+ *   - truth_class=derived on arbitration → scope drift
+ *   - dispute → affirm pattern → informational note
+ *   - acceptance_revoked present → informational note
+ *   - Needs Human Arbitration triggers (v0.4.1):
+ *       * closure_authority_valid = false
+ *       * truth_class=derived AND no acceptance events
+ *       * multiple arbitrations on same Demand
+ *       * acceptance_disputed is the latest event
+ */
+class SA_Orch_Reasoning {
+
+    /**
+     * Mode constant. v0.4 is deterministic-only; the LLM seam is future work.
+     */
+    const MODE = 'deterministic';
+
+    /**
+     * Evaluate a trace and return the deterministic audit report.
+     *
+     * Input shape: trace array as returned by SA_Orch_Rest::get_demand_trace().
+     *
+     * Output:
+     *   [
+     *     'mode'                           => 'deterministic',
+     *     'summary'                        => string,
+     *     'inconsistencies'                => string[],
+     *     'scope_drift'                    => string[],
+     *     'notes'                          => string[],
+     *     'closure_confidence'             => 'high' | 'medium' | 'low' | 'n/a',
+     *     'closure_confidence_explanation' => string,
+     *     'needs_human_arbitration'        => bool,
+     *     'human_arbitration_message'      => string,    // verbatim user-facing line
+     *     'human_arbitration_triggers'     => string[],  // reasons firing the flag
+     *   ]
+     */
+    public static function evaluate( array $trace ) {
+        $arbs      = isset( $trace['arbitrations'] ) ? (array) $trace['arbitrations'] : [];
+        $links     = isset( $trace['plan_links'] )   ? (array) $trace['plan_links']   : [];
+        $events    = isset( $trace['acceptance'] )   ? (array) $trace['acceptance']   : [];
+        $basic     = $trace['closure_state_basic']      ?? null;
+        $authority = $trace['closure_authority_valid']  ?? null;
+
+        // Event-type flags
+        $has_claim   = false;
+        $has_dispute = false;
+        $has_affirm  = false;
+        $has_revoke  = false;
+        foreach ( $events as $e ) {
+            if ( $e->event_type === 'result_claimed' )      $has_claim   = true;
+            if ( $e->event_type === 'acceptance_disputed' ) $has_dispute = true;
+            if ( $e->event_type === 'acceptance_affirmed' ) $has_affirm  = true;
+            if ( $e->event_type === 'acceptance_revoked' )  $has_revoke  = true;
+        }
+
+        $inconsistencies = [];
+        $drift           = [];
+        $notes           = [];
+
+        // --- Inconsistencies ---
+
+        // Closure authority invalid: latest acceptance_affirmed by non-stakeholder
+        if ( $authority === false ) {
+            $latest_affirm = null;
+            foreach ( array_reverse( $events ) as $e ) {
+                if ( $e->event_type === 'acceptance_affirmed' ) { $latest_affirm = $e; break; }
+            }
+            if ( $latest_affirm ) {
+                $inconsistencies[] = "Closure authority invalid: acceptance_affirmed event #{$latest_affirm->id} authored by actor_role='{$latest_affirm->actor_role}' (must be 'stakeholder' for authoritative closure).";
+            }
+        }
+
+        // projection_type vs plan_link count mismatch
+        foreach ( $arbs as $arb ) {
+            $arb_id = (int) $arb->id;
+            $arb_links = count( array_filter( $links, function ( $l ) use ( $arb_id ) {
+                return (int) $l->arbitration_id === $arb_id;
+            } ) );
+            if ( $arb->projection_type === 'scope-direct-no-plan' && $arb_links > 0 ) {
+                $inconsistencies[] = "Arbitration #{$arb->id} declares projection_type='scope-direct-no-plan' but has {$arb_links} plan link(s) — inconsistent.";
+            }
+            if ( in_array( $arb->projection_type, [ 'scope-direct', 'scope-decomposed', 'scope-merged' ], true ) && $arb_links === 0 ) {
+                $inconsistencies[] = "Arbitration #{$arb->id} declares projection_type='{$arb->projection_type}' but has no plan links — projection promised a Plan but none recorded.";
+            }
+        }
+
+        // Affirmation without claim (closure path is incomplete)
+        if ( $has_affirm && ! $has_claim ) {
+            $inconsistencies[] = "Acceptance was affirmed without any prior result_claimed event — closure path is incomplete.";
+        }
+
+        // prior_event_id chain integrity
+        $event_ids = array_map( function ( $e ) { return (int) $e->id; }, $events );
+        foreach ( $events as $e ) {
+            if ( $e->prior_event_id !== null && $e->prior_event_id !== '' ) {
+                $prior = (int) $e->prior_event_id;
+                if ( $prior > 0 && ! in_array( $prior, $event_ids, true ) ) {
+                    $inconsistencies[] = "Event #{$e->id} references prior_event_id={$prior}, which is not in this Demand's event chain.";
+                }
+            }
+        }
+
+        // --- Scope drift ---
+
+        if ( count( $arbs ) > 1 ) {
+            $drift[] = "Demand has " . count( $arbs ) . " arbitrations recorded — review for re-interpretation across arbitration moments.";
+        }
+
+        foreach ( $arbs as $arb ) {
+            if ( ! in_array( $arb->projection_type, [ 'scope-direct', 'scope-direct-no-plan' ], true ) ) {
+                $drift[] = "Arbitration #{$arb->id} uses projection_type='{$arb->projection_type}' — explicit scope transformation. Verify the Plan honors the original Demand intent.";
+            }
+            if ( $arb->truth_class === 'derived' ) {
+                $drift[] = "Arbitration #{$arb->id} has truth_class='derived' — Demand was reconstructed from Plan-side evidence. Original scope is not directly verifiable.";
+            }
+        }
+
+        // --- Notes (informational) ---
+
+        if ( $has_dispute && $has_affirm ) {
+            $notes[] = "This Demand experienced a dispute before its current affirmation. Review the dispute → affirmation transition for completeness of resolution.";
+        }
+        if ( $has_revoke ) {
+            $notes[] = "An acceptance_revoked event is present — a previously-affirmed acceptance was withdrawn.";
+        }
+        if ( ! empty( $events ) && ! $has_claim && ! $has_dispute && ! $has_affirm && ! $has_revoke ) {
+            $notes[] = "Acceptance events present but none of the standard types (claim/dispute/affirm/revoke) — review event_type values.";
+        }
+
+        // --- Summary + confidence ---
+
+        $summary    = self::build_summary( $arbs, $links, $events, $basic, $authority );
+        $confidence = self::compute_confidence(
+            $basic,
+            $authority,
+            $has_dispute,
+            $has_revoke,
+            count( $inconsistencies ),
+            count( $drift ),
+            count( $events )
+        );
+
+        // --- Needs Human Arbitration (v0.4.1) ---
+
+        $human = self::compute_human_arbitration( $arbs, $events, $authority );
+
+        return [
+            'mode'                           => self::MODE,
+            'summary'                        => $summary,
+            'inconsistencies'                => $inconsistencies,
+            'scope_drift'                    => $drift,
+            'notes'                          => $notes,
+            'closure_confidence'             => $confidence['level'],
+            'closure_confidence_explanation' => $confidence['explanation'],
+            'needs_human_arbitration'        => $human['required'],
+            'human_arbitration_message'      => $human['message'],
+            'human_arbitration_triggers'     => $human['triggers'],
+        ];
+    }
+
+    /**
+     * Determine whether this trace requires human arbitration.
+     *
+     * Triggers (any one is sufficient):
+     *   1. closure_authority_valid = false (latest acceptance_affirmed by non-stakeholder).
+     *   2. arbitration carries truth_class='derived' AND no acceptance events exist
+     *      (Demand was reconstructed from Plan-side evidence and never confirmed).
+     *   3. multiple arbitrations on the same Demand (re-interpretation requires
+     *      human reconciliation).
+     *   4. latest event is acceptance_disputed (dispute is unresolved).
+     *
+     * The human arbitration verdict is the deterministic layer's escalation
+     * signal. It is independent of closure_confidence — a Demand can be
+     * "open" and still require human arbitration if the conditions warrant.
+     */
+    private static function compute_human_arbitration( $arbs, $events, $authority ) {
+        $triggers = [];
+
+        // 1. closure_authority_valid = false
+        if ( $authority === false ) {
+            $triggers[] = "closure_authority_valid is false (acceptance_affirmed event was authored by a non-stakeholder actor).";
+        }
+
+        // 2. derived arbitration without acceptance events
+        $has_derived_arb = false;
+        foreach ( $arbs as $a ) {
+            if ( ( $a->truth_class ?? null ) === 'derived' ) { $has_derived_arb = true; break; }
+        }
+        if ( $has_derived_arb && count( $events ) === 0 ) {
+            $triggers[] = "Demand is derived (truth_class='derived' on arbitration) and has no acceptance events — original stakeholder intent is unverified.";
+        }
+
+        // 3. multiple arbitrations on the same Demand
+        if ( count( $arbs ) > 1 ) {
+            $triggers[] = count( $arbs ) . " arbitrations exist on the same Demand — re-interpretation requires human reconciliation.";
+        }
+
+        // 4. latest event is acceptance_disputed
+        if ( ! empty( $events ) ) {
+            $latest = end( $events );
+            if ( ( $latest->event_type ?? null ) === 'acceptance_disputed' ) {
+                $triggers[] = "Latest event is acceptance_disputed — dispute is unresolved and requires human follow-up before closure can be trusted.";
+            }
+        }
+
+        return [
+            'required' => ! empty( $triggers ),
+            'message'  => 'This trace requires human arbitration before closure can be trusted.',
+            'triggers' => $triggers,
+        ];
+    }
+
+    private static function build_summary( $arbs, $links, $events, $basic, $authority ) {
+        $arb_n   = count( $arbs );
+        $link_n  = count( $links );
+        $event_n = count( $events );
+
+        if ( $arb_n === 0 && $event_n === 0 ) {
+            return "No arbitration and no acceptance events for this Demand. The Demand may be unrecognized by SA-Orchestration, or the surface_ref may be wrong.";
+        }
+
+        $bits   = [];
+        $bits[] = "{$arb_n} arbitration"   . ( $arb_n   === 1 ? '' : 's' );
+        $bits[] = "{$link_n} plan link"    . ( $link_n  === 1 ? '' : 's' );
+        $bits[] = "{$event_n} acceptance event" . ( $event_n === 1 ? '' : 's' );
+
+        $event_seq = '';
+        if ( $event_n > 0 ) {
+            $sequence = [];
+            foreach ( $events as $e ) $sequence[] = $e->event_type;
+            $event_seq = ' Sequence: ' . implode( ' → ', $sequence ) . '.';
+        }
+
+        $closure_phrase = '';
+        if ( $basic === 'closed' ) {
+            if ( $authority === true ) {
+                $closure_phrase = ' Currently closed (stakeholder-affirmed).';
+            } elseif ( $authority === false ) {
+                $closure_phrase = ' Marked closed but closure authority is invalid (non-stakeholder affirmed).';
+            } else {
+                $closure_phrase = ' Currently closed.';
+            }
+        } elseif ( is_string( $basic ) && strpos( $basic, 'open:' ) === 0 ) {
+            $closure_phrase = " Currently open ({$basic}).";
+        } elseif ( $basic === 'no-events' ) {
+            $closure_phrase = ' No acceptance events.';
+        }
+
+        return implode( ', ', $bits ) . '.' . $event_seq . $closure_phrase;
+    }
+
+    private static function compute_confidence( $basic, $authority, $has_dispute, $has_revoke, $inc_count, $drift_count, $event_count ) {
+        // No events — confidence not meaningful
+        if ( $event_count === 0 || $basic === 'no-events' ) {
+            return [
+                'level'       => 'n/a',
+                'explanation' => 'No acceptance events to evaluate; closure confidence is not yet meaningful.',
+            ];
+        }
+
+        // Open states
+        if ( is_string( $basic ) && strpos( $basic, 'open:' ) === 0 ) {
+            return [
+                'level'       => 'low',
+                'explanation' => "Demand is currently {$basic}; closure has not been claimed and confirmed.",
+            ];
+        }
+
+        // Closed but authority invalid
+        if ( $basic === 'closed' && $authority === false ) {
+            return [
+                'level'       => 'low',
+                'explanation' => 'Closed by non-stakeholder actor; closure_authority_valid=false. Treat as not authoritatively closed.',
+            ];
+        }
+
+        // Closed with stakeholder authority
+        if ( $basic === 'closed' && $authority === true ) {
+            if ( $inc_count > 0 ) {
+                return [
+                    'level'       => 'low',
+                    'explanation' => "Closed by stakeholder, but {$inc_count} inconsistenc" . ( $inc_count === 1 ? 'y' : 'ies' ) . ' detected. Review before treating as final.',
+                ];
+            }
+            $reasons = [];
+            if ( $has_dispute )  $reasons[] = 'a prior dispute was recorded';
+            if ( $has_revoke )   $reasons[] = 'an acceptance_revoked event exists';
+            if ( $drift_count )  $reasons[] = "{$drift_count} potential scope-drift indicator" . ( $drift_count === 1 ? '' : 's' );
+            if ( count( $reasons ) === 0 ) {
+                return [
+                    'level'       => 'high',
+                    'explanation' => 'Closed by stakeholder with a clean event chain and no scope drift detected.',
+                ];
+            }
+            return [
+                'level'       => 'medium',
+                'explanation' => 'Closed by stakeholder, but ' . implode( '; ', $reasons ) . '. Review history before treating as routine.',
+            ];
+        }
+
+        // Fall-through (unrecognized basic state)
+        return [ 'level' => 'low', 'explanation' => "Unrecognized closure_state_basic value: '{$basic}'." ];
+    }
+}

sa-orchestration/includes/class-sa-rest.php

@@ -0,0 +1,110 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+class SA_Orch_Rest {
+
+    const REST_NS = 'sa-orch/v1';
+
+    public static function register_routes() {
+        register_rest_route( self::REST_NS, '/arbitration', [
+            'methods'             => 'POST',
+            'callback'            => [ __CLASS__, 'post_arbitration' ],
+            'permission_callback' => [ __CLASS__, 'check_admin' ],
+        ] );
+
+        register_rest_route( self::REST_NS, '/acceptance', [
+            'methods'             => 'POST',
+            'callback'            => [ __CLASS__, 'post_acceptance' ],
+            'permission_callback' => [ __CLASS__, 'check_admin' ],
+        ] );
+
+        register_rest_route( self::REST_NS, '/demand/(?P<surface>[a-z\-]+)/(?P<ref>[^/]+)/trace', [
+            'methods'             => 'GET',
+            'callback'            => [ __CLASS__, 'get_demand_trace' ],
+            'permission_callback' => [ __CLASS__, 'check_admin' ],
+        ] );
+    }
+
+    public static function check_admin() {
+        return current_user_can( 'manage_options' );
+    }
+
+    public static function post_arbitration( WP_REST_Request $request ) {
+        $params = $request->get_json_params();
+        if ( ! is_array( $params ) || empty( $params ) ) {
+            $params = $request->get_params();
+        }
+        $result = SA_Orch_Arbitration::write( $params );
+        if ( is_wp_error( $result ) ) {
+            return new WP_REST_Response( [
+                'ok'      => false,
+                'error'   => $result->get_error_code(),
+                'message' => $result->get_error_message(),
+                'data'    => $result->get_error_data(),
+            ], 400 );
+        }
+        return new WP_REST_Response( [ 'ok' => true, 'data' => $result ], 201 );
+    }
+
+    public static function post_acceptance( WP_REST_Request $request ) {
+        $params = $request->get_json_params();
+        if ( ! is_array( $params ) || empty( $params ) ) {
+            $params = $request->get_params();
+        }
+        $result = SA_Orch_Acceptance::write( $params );
+        if ( is_wp_error( $result ) ) {
+            return new WP_REST_Response( [
+                'ok'      => false,
+                'error'   => $result->get_error_code(),
+                'message' => $result->get_error_message(),
+                'data'    => $result->get_error_data(),
+            ], 400 );
+        }
+        return new WP_REST_Response( [ 'ok' => true, 'data' => $result ], 201 );
+    }
+
+    public static function get_demand_trace( WP_REST_Request $request ) {
+        global $wpdb;
+        $surface = $request['surface'];
+        $ref     = $request['ref'];
+        $p       = $wpdb->prefix . SA_ORCH_DB_PREFIX;
+
+        $arbs = $wpdb->get_results( $wpdb->prepare(
+            "SELECT * FROM {$p}arbitration WHERE demand_surface = %s AND demand_ref = %s ORDER BY created_at, id",
+            $surface, $ref
+        ) );
+
+        $links = [];
+        if ( ! empty( $arbs ) ) {
+            $arb_ids      = array_map( function ( $a ) { return (int) $a->id; }, $arbs );
+            $placeholders = implode( ',', array_fill( 0, count( $arb_ids ), '%d' ) );
+            $links = $wpdb->get_results( $wpdb->prepare(
+                "SELECT * FROM {$p}arbitration_plan_link WHERE arbitration_id IN ($placeholders) ORDER BY created_at, id",
+                ...$arb_ids
+            ) );
+        }
+
+        $events = $wpdb->get_results( $wpdb->prepare(
+            "SELECT * FROM {$p}acceptance_event WHERE demand_surface = %s AND demand_ref = %s ORDER BY observed_at, id",
+            $surface, $ref
+        ) );
+
+        $closure_state_basic      = SA_Orch_Acceptance::basic_closure_state( $surface, $ref );
+        $closure_state_role_aware = SA_Orch_Acceptance::role_aware_closure_state( $surface, $ref );
+        $closure_authority_valid  = SA_Orch_Acceptance::closure_authority_valid( $surface, $ref );
+
+        return new WP_REST_Response( [
+            'ok'                       => true,
+            'demand'                   => [ 'surface' => $surface, 'ref' => $ref ],
+            'arbitrations'             => $arbs,
+            'plan_links'               => $links,
+            'acceptance'               => $events,
+            // Existing field (v0.1) — retained as alias of closure_state_basic for backward compatibility
+            'closure_state'            => $closure_state_basic,
+            // Added in v0.2 — explicit naming
+            'closure_state_basic'      => $closure_state_basic,
+            'closure_state_role_aware' => $closure_state_role_aware,
+            'closure_authority_valid'  => $closure_authority_valid,
+        ], 200 );
+    }
+}

sa-orchestration/includes/class-sa-sara-admin.php

@@ -0,0 +1,68 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Admin enqueue for the Sara bubble UI.
+ *
+ * Injects the Sara floating button + panel CSS/JS on Fluent Boards,
+ * Fluent Support, and SA-Orchestration admin pages. The bubble is
+ * gated to manage_options users; the REST endpoint behind it is
+ * gated identically.
+ *
+ * The frontend reads URL/hash to detect surface + ref, then POSTs to
+ * /sa-orch/v1/sara/invoke. No DOM mutation outside the bubble itself.
+ *
+ * Pages where Sara appears:
+ *   - page=fluent-boards     (any view inside the Boards SPA)
+ *   - page=fluent-support    (any view inside the Support SPA)
+ *   - page=sa-orchestration  (and its subpages)
+ */
+class SA_Orch_Sara_Admin {
+
+    const HANDLE_JS  = 'sa-orch-sara-bubble';
+    const HANDLE_CSS = 'sa-orch-sara-bubble';
+
+    public static function register_hooks() {
+        add_action( 'admin_enqueue_scripts', [ __CLASS__, 'maybe_enqueue' ] );
+    }
+
+    public static function maybe_enqueue( $hook ) {
+        if ( ! current_user_can( 'manage_options' ) ) {
+            return;
+        }
+
+        $page = isset( $_GET['page'] ) ? sanitize_text_field( wp_unslash( $_GET['page'] ) ) : '';
+
+        // Match the three primary admin surfaces. Sub-pages of sa-orchestration
+        // (e.g., sa-orchestration-arbitrations) all start with the parent slug.
+        $is_target = (
+            $page === 'fluent-boards'
+            || $page === 'fluent-support'
+            || strpos( $page, 'sa-orchestration' ) === 0
+        );
+        if ( ! $is_target ) {
+            return;
+        }
+
+        wp_enqueue_style(
+            self::HANDLE_CSS,
+            SA_ORCH_URL . 'assets/sara-bubble.css',
+            [],
+            SA_ORCH_VERSION
+        );
+
+        wp_enqueue_script(
+            self::HANDLE_JS,
+            SA_ORCH_URL . 'assets/sara-bubble.js',
+            [],
+            SA_ORCH_VERSION,
+            true
+        );
+
+        wp_localize_script( self::HANDLE_JS, 'SA_ORCH_SARA', [
+            'rest_url' => esc_url_raw( rest_url( 'sa-orch/v1/sara/invoke' ) ),
+            'nonce'    => wp_create_nonce( 'wp_rest' ),
+            'page'     => $page,
+        ] );
+    }
+}

sa-orchestration/includes/class-sa-sara-rest.php

@@ -0,0 +1,81 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Sara REST endpoint. Provides the LLM round-trip from the JS bubble.
+ *
+ * Endpoint: POST /sa-orch/v1/sara/invoke
+ * Body:     { surface: string|null, ref: string|null, prompt: string }
+ * Returns:  { response: string, context: {...} }   on success
+ *           { error: string, message: string }    on failure (HTTP 502)
+ *
+ * Capability: manage_options. Same gate as the rest of the SA-Orch admin.
+ *
+ * No DB writes. No mutation. Pure round-trip to the configured LLM
+ * provider via SA_Orch_Sara_Service.
+ */
+class SA_Orch_Sara_Rest {
+
+    public static function register_routes() {
+        register_rest_route( 'sa-orch/v1', '/sara/invoke', [
+            'methods'  => 'POST',
+            'callback' => [ __CLASS__, 'invoke' ],
+            'permission_callback' => function () {
+                return current_user_can( 'manage_options' );
+            },
+            'args' => [
+                'surface'       => [ 'type' => 'string', 'required' => false ],
+                'ref'           => [ 'type' => 'string', 'required' => false ],
+                'page'          => [ 'type' => 'string', 'required' => false ],
+                'prompt'        => [ 'type' => 'string', 'required' => true ],
+                'history'       => [ 'type' => 'array',  'required' => false ],
+                'asterion_file' => [ 'type' => 'string', 'required' => false ], // Board #28
+            ],
+        ] );
+    }
+
+    public static function invoke( WP_REST_Request $request ) {
+        $surface       = sanitize_text_field( (string) $request->get_param( 'surface' ) );
+        $ref           = sanitize_text_field( (string) $request->get_param( 'ref' ) );
+        $page          = sanitize_text_field( (string) $request->get_param( 'page' ) );
+        $prompt        = (string) $request->get_param( 'prompt' );
+        $asterion_file = sanitize_text_field( (string) $request->get_param( 'asterion_file' ) );
+        $history       = $request->get_param( 'history' );
+        if ( ! is_array( $history ) ) {
+            $history = [];
+        }
+
+        if ( trim( $prompt ) === '' ) {
+            return new WP_REST_Response( [
+                'error'   => 'empty_prompt',
+                'message' => 'prompt is required',
+            ], 400 );
+        }
+
+        $context = [
+            'surface' => $surface !== '' ? $surface : null,
+            'ref'     => $ref     !== '' ? $ref     : null,
+        ];
+
+        $result = SA_Orch_Sara_Service::invoke( $context, $prompt, $history, $page, $asterion_file );
+
+        if ( is_wp_error( $result ) ) {
+            return new WP_REST_Response( [
+                'error'   => $result->get_error_code(),
+                'message' => $result->get_error_message(),
+            ], 502 );
+        }
+
+        // Service now returns a wrapping shape: { response, usage, log_id }.
+        // Pass the structured response through as-is for backward-compat with
+        // the existing JS contract; surface usage + log_id alongside for Board #16.
+        return new WP_REST_Response( [
+            'response' => $result['response'],
+            'usage'    => $result['usage']  ?? null,
+            'log_id'   => $result['log_id'] ?? null,
+            'context'  => $context,
+            'page'     => $page !== '' ? $page : null,
+            'turn'     => count( $history ) / 2 + 1,  // 1-indexed turn number for UI feedback
+        ], 200 );
+    }
+}

sa-orchestration/includes/class-sa-sara-service.php

@@ -0,0 +1,418 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Sara service — interactive LLM bridge with structured output.
+ *
+ * v0.7.2 (Board #14 — Sara — Response Layer): returns a structured
+ * { summary, suggestion, draft, notes } payload instead of a free-text
+ * string. The shape is enforced server-side via clamp_response(); a
+ * misbehaving model cannot inject extra fields.
+ *
+ * Sara is the interactive surface of SA-Core (UI + contextual cognition;
+ * no persistence). This service does NOT write to Asterion or Fluent.
+ * It does NOT register demands. It does NOT mutate state of any kind.
+ *
+ * Per the locked Control Rule:
+ *   Sara outputs are non-binding.
+ *   Only human-initiated actions may trigger SA-Core writes.
+ *   Sara may identify untracked demand candidates.
+ *   Sara cannot register demands.
+ */
+class SA_Orch_Sara_Service {
+
+    const REQUEST_TIMEOUT = 30;
+
+    /**
+     * Invoke Sara with context + prompt + optional prior conversation.
+     *
+     * @param array  $context  ['surface' => string|null, 'ref' => string|null]
+     * @param string $prompt   Current user prompt (the new turn).
+     * @param array  $history  Optional prior turns. Each item:
+     *                           [ 'role' => 'user'|'assistant', 'content' => string|array ]
+     *                         Assistant content is the structured shape returned previously
+     *                         and gets reformatted as readable text for the model.
+     * @param string $page     Optional admin page slug (e.g. 'sa-orchestration', 'fluent-boards').
+     *                         Carried into the user prompt when no surface/ref pair is bound,
+     *                         so Sara still has page-level context.
+     *
+     * @return array|WP_Error  On success:
+     *   [
+     *     'response' => [ 'summary' => string, 'suggestion' => string, 'draft' => string, 'notes' => string ],
+     *     'usage'    => [ 'prompt_tokens' => int, 'completion_tokens' => int, 'total_tokens' => int ] | null,
+     *     'log_id'   => int | null,  // wp_sa_token_log row id, for later linkage to a committed comment
+     *   ]
+     *   WP_Error on any failure path.
+     */
+    public static function invoke( array $context, string $prompt, array $history = [], string $page = '', string $asterion_file = '' ) {
+        $settings = SA_Orch_LLM_Settings::get();
+        if ( empty( $settings['enabled'] ) ) {
+            return new WP_Error( 'llm_disabled', 'LLM provider is disabled in settings.' );
+        }
+        if ( empty( $settings['api_token'] ) ) {
+            return new WP_Error( 'no_api_token', 'No API token configured.' );
+        }
+        if ( empty( $settings['api_base_url'] ) || empty( $settings['model'] ) ) {
+            return new WP_Error( 'incomplete_settings', 'Provider api_base_url and model must be configured.' );
+        }
+
+        $url = rtrim( (string) $settings['api_base_url'], '/' ) . '/chat/completions';
+
+        // Build the messages array: system prompt, then prior turns (history),
+        // then the current user prompt with context wrapping.
+        $messages = [
+            [ 'role' => 'system', 'content' => self::system_prompt() ],
+        ];
+        foreach ( $history as $turn ) {
+            $role    = isset( $turn['role'] ) ? (string) $turn['role'] : '';
+            $content = $turn['content'] ?? '';
+            if ( $role === 'user' ) {
+                $messages[] = [ 'role' => 'user', 'content' => (string) $content ];
+            } elseif ( $role === 'assistant' ) {
+                $messages[] = [ 'role' => 'assistant', 'content' => self::format_assistant_replay( $content ) ];
+            }
+        }
+        $messages[] = [ 'role' => 'user', 'content' => self::user_prompt( $context, $prompt, $page, $asterion_file ) ];
+
+        $payload = [
+            'model'           => (string) $settings['model'],
+            'messages'        => $messages,
+            'response_format' => [ 'type' => 'json_object' ],
+            'temperature'     => 0.4,
+        ];
+
+        $response = wp_remote_post( $url, [
+            'headers' => [
+                'Authorization' => 'Bearer ' . (string) $settings['api_token'],
+                'Content-Type'  => 'application/json',
+            ],
+            'body'    => wp_json_encode( $payload ),
+            'timeout' => self::REQUEST_TIMEOUT,
+        ] );
+
+        if ( is_wp_error( $response ) ) {
+            return new WP_Error( 'network_error', 'Sara: network error — ' . $response->get_error_message() );
+        }
+        $code = (int) wp_remote_retrieve_response_code( $response );
+        if ( $code < 200 || $code >= 300 ) {
+            $excerpt = substr( (string) wp_remote_retrieve_body( $response ), 0, 240 );
+            return new WP_Error( 'http_error', "Sara: HTTP {$code} — {$excerpt}" );
+        }
+
+        $body     = (string) wp_remote_retrieve_body( $response );
+        $envelope = json_decode( $body, true );
+        if ( ! is_array( $envelope ) || ! isset( $envelope['choices'][0]['message']['content'] ) ) {
+            return new WP_Error( 'malformed_response', 'Sara: response missing content.' );
+        }
+
+        $content = (string) $envelope['choices'][0]['message']['content'];
+        $parsed  = json_decode( $content, true );
+        if ( ! is_array( $parsed ) ) {
+            $excerpt = substr( $content, 0, 240 );
+            return new WP_Error( 'parse_error', "Sara: model output is not valid JSON — {$excerpt}" );
+        }
+
+        $structured = self::clamp_response( $parsed );
+
+        // If the request had no bound context AND no Asterion file under view,
+        // surface "no context bound" so the operator knows why answers are general.
+        // When asterion_file IS bound, canonical context is present — do not lie
+        // about being unbound.
+        if ( ( empty( $context['surface'] ) || empty( $context['ref'] ) ) && $asterion_file === '' ) {
+            $existing = trim( $structured['notes'] );
+            $marker   = 'no context bound';
+            $structured['notes'] = $existing === ''
+                ? $marker
+                : ( $existing . '; ' . $marker );
+        }
+
+        // Capture usage and log the invocation (Board #16). Server-side log
+        // is for cross-session attribution (Board #23 hook). Sara UI counters
+        // remain JS-only / session-only as locked. log_id is returned so a
+        // future invocation surface can link this row to a committed comment.
+        $usage  = isset( $envelope['usage'] ) && is_array( $envelope['usage'] ) ? $envelope['usage'] : null;
+        $log_id = null;
+        if ( $usage !== null && class_exists( 'SA_Orch_Token_Log' ) ) {
+            $log_id = SA_Orch_Token_Log::record(
+                'openai',
+                (string) $settings['model'],
+                $usage,
+                (int) get_current_user_id()
+            );
+            $log_id = $log_id > 0 ? $log_id : null;
+        }
+
+        return [
+            'response' => $structured,
+            'usage'    => $usage,
+            'log_id'   => $log_id,
+        ];
+    }
+
+    /**
+     * Clamp model output to the structured contract. A misbehaving model
+     * cannot inject extra fields or wrong types into the consumer surface.
+     */
+    private static function clamp_response( array $parsed ): array {
+        return [
+            'summary'    => isset( $parsed['summary'] )    ? (string) $parsed['summary']    : '',
+            'suggestion' => isset( $parsed['suggestion'] ) ? (string) $parsed['suggestion'] : '',
+            'draft'      => isset( $parsed['draft'] )      ? (string) $parsed['draft']      : '',
+            'notes'      => isset( $parsed['notes'] )      ? (string) $parsed['notes']      : '',
+        ];
+    }
+
+    /** System prompt establishing Sara's role and the structured-output contract. */
+    private static function system_prompt(): string {
+        // Board #29 — Sara System Primer.
+        // Stable identity block: Sara has system-level awareness even with no
+        // surface or file bound. No generic AI-assistant fallback. No hedging
+        // disclaimers about "documentation not provided here."
+        $primer = "SYSTEM IDENTITY (always active)\n"
+                . "\n"
+                . "You are Sara — the interpretive cognition surface of\n"
+                . "SA-Orchestration / MissionNet. This is not a generic chat.\n"
+                . "You have a stable identity here. You DO NOT need to ask what\n"
+                . "this system is; you already know it.\n"
+                . "\n"
+                . "Forbidden phrasings (do not output any equivalent):\n"
+                . "  - \"specifics depend on system documentation not provided here\"\n"
+                . "  - \"as a generic AI assistant\"\n"
+                . "  - \"if I had access to ...\" about your own operating context\n"
+                . "  - \"likely\" / \"probably depends on\" as a hedge about the system itself\n"
+                . "(Hedging is fine ABOUT FACTS you genuinely don't know. It is not\n"
+                . "fine about your own role and the named structure of the system.)\n"
+                . "\n"
+                . "COMPASS\n"
+                . "  North  = Sara (you) — interpretation, drafting, advising, observing.\n"
+                . "  South  = Asterion — canonical truth, read-only markdown spec corpus\n"
+                . "           at Archvie/sa-core/docs/specs/. Verifies, never speculates.\n"
+                . "  Center = Human — only the Human advances state.\n"
+                . "\n"
+                . "SURFACES where you appear\n"
+                . "  - Fluent Boards (project tasks; per-board task lifecycle)\n"
+                . "  - Fluent Support (customer tickets)\n"
+                . "  - SA-Orchestration admin: Demand Trace, Sleeper Agents actor registry,\n"
+                . "    Asterion Explorer (canonical MD), Attention Bridge\n"
+                . "  - External Realms (FluentCRM, etc.) mediated through Adapters\n"
+                . "\n"
+                . "VOCABULARY\n"
+                . "  - Fluent = motion. Attention = routing.\n"
+                . "  - Boards are contracts (the Description IS the contract — Board #27).\n"
+                . "  - Comments are evidence (audit log; cannot redefine the contract).\n"
+                . "  - Asterion canonical files mirror the repo at Archvie/sa-core/docs/specs/.\n"
+                . "  - When an Asterion file is bound (Board #28), it appears in your prompt as\n"
+                . "    'ASTERION CANONICAL DOCUMENT — READ FIRST'. Treat it as authoritative.\n"
+                . "\n"
+                . "PERMISSIONS (locked)\n"
+                . "  You MAY interpret, draft, advise, observe, coordinate.\n"
+                . "  You MAY NOT progress Boards, accept gates, mutate Asterion, act silently.\n"
+                . "\n"
+                . "DOCTRINE\n"
+                . "  Sara interprets. Asterion verifies. Human arbitrates.\n"
+                . "\n"
+                . "META-ROLE OVERRIDE (highest priority — overrides BRIEF mode below)\n"
+                . "\n"
+                . "When the user asks a meta-question about your identity or the system\n"
+                . "(any of: \"what is your role\", \"what is this space\", \"what do you do\",\n"
+                . "\"who are you\", \"introduce yourself\", \"explain yourself\", or paraphrases),\n"
+                . "the response MUST contain ALL of the following — non-negotiable, regardless\n"
+                . "of any other mode rule below:\n"
+                . "\n"
+                . "  - summary: names yourself as Sara AND names the compass\n"
+                . "    (North/Sara, South/Asterion, Center/Human).\n"
+                . "  - suggestion: names at least three of the surfaces above\n"
+                . "    (Fluent Boards, Fluent Support, Asterion Explorer, Demand Trace,\n"
+                . "    Sleeper Agents actor registry, Attention Bridge, FluentCRM Realm).\n"
+                . "  - notes: states the doctrine line: \"Sara interprets. Asterion verifies.\n"
+                . "    Human arbitrates.\"\n"
+                . "\n"
+                . "On these questions, BRIEF mode does NOT apply — you produce the structured\n"
+                . "identity answer. Do NOT answer with one sentence. Do NOT abstract away the\n"
+                . "named structure. Do NOT say you don't have access to know.\n"
+                . "\n"
+                . "--\n"
+                . "\n";
+
+        return $primer
+             . 'You are Sara, the interactive cognition surface of the SA-Orchestration system. '
+             . 'You sit alongside the user inside WP admin and help them think and draft. '
+             . 'You are NOT canonical. You do not write to any system. '
+             . "Your outputs are non-binding drafts; the human decides what to commit.\n\n"
+             . "You MUST return ONLY a JSON object with this exact shape:\n"
+             . "  {\n"
+             . "    \"summary\":    string,  // 1-2 sentences\n"
+             . "    \"suggestion\": string,  // clear next step\n"
+             . "    \"draft\":      string,  // optional text the user can paste; empty string if not relevant\n"
+             . "    \"notes\":      string   // optional flags or caveats; empty string if none\n"
+             . "  }\n\n"
+             . "All four keys MUST be present. Values may be empty strings. No additional keys.\n\n"
+             . "Constraints:\n"
+             . "- Be direct and concrete. The audience is a busy developer/operator.\n"
+             . "- summary: a brief read of the situation — 1 to 2 sentences.\n"
+             . "- suggestion: one concrete next action; not a list of options.\n"
+             . "- draft: if the user seems to want text they can post (a comment, a reply, a message), put a complete ready-to-paste draft here. Otherwise empty string.\n"
+             . "- notes: caveats, low-confidence flags, missing-context observations. Otherwise empty string.\n"
+             . "- Do not invent facts about the system. If you do not know, put it in notes.\n"
+             . "- Keep responses tight. No filler. No preamble.\n"
+             . "\n"
+             . "Mode selection — match the depth of the input.\n"
+             . "\n"
+             . "The 4-key contract above does NOT change. What changes is the depth of what each field carries, based on what the input is asking for.\n"
+             . "\n"
+             . "The constraints above describe BRIEF mode (the default). In BRIEF mode they hold exactly as written.\n"
+             . "\n"
+             . "INTERPRETIVE mode OVERRIDES the depth rules. Engage INTERPRETIVE mode when the input shows 2 or more of:\n"
+             . "  - numbered or named principles (e.g. I1, R-O-1, axioms, invariants)\n"
+             . "  - multi-section structure with headings\n"
+             . "  - doctrine vocabulary (canonical, invariant, asymmetry, contract, law, axiom, doctrine, foundational, principle)\n"
+             . "  - explicit philosophical or architectural framing\n"
+             . "  - the user prompt asks for synthesis (\"explain\", \"what does this mean\", \"interpret\", \"synthesize\")\n"
+             . "\n"
+             . "When in INTERPRETIVE mode, depth changes:\n"
+             . "  - summary: 2 to 4 sentences. Name the underlying thesis. Connect multiple parts to a coherent system. Not paraphrase. Not a bullet-list of headings.\n"
+             . "  - suggestion: an architectural observation, a synthesis prompt back to the user, a connection-naming. NOT \"review this\". NOT \"check status\".\n"
+             . "  - draft: empty unless the user explicitly wants pasteable text.\n"
+             . "  - notes: thread-level observations — connections, named patterns, attribution flags, structural depth markers.\n"
+             . "\n"
+             . "When the input contains numbered or labeled principles (e.g. I1, I2, R-O-1, named axioms, named invariants), the synthesis MUST:\n"
+             . "  - reference at least 3 of them by their identifier (not as a vague group)\n"
+             . "  - explicitly tie each named one to the thesis you identified\n"
+             . "  - name structural patterns that appear (severity tiers, enforcement gradients, attribution chains, asymmetry classes, etc.) — call them out by what they are, not just what they do\n"
+             . "Do not refer to \"the invariants\" or \"these principles\" as a group when specific identifiers exist. Use the identifiers. The reader already has the document; what they need from you is the structural map.\n"
+             . "\n"
+             . "The contract is structural. The depth is contextual. Don't be brief because being brief is safe; brief is wrong on system-shaped input.\n";
+    }
+
+    /**
+     * User prompt wrapping the context payload + the user's actual question.
+     *
+     * When (surface, ref) is bound, hydrate the object through the surface
+     * adapter and embed structured details. When no adapter exists for the
+     * surface, surface that explicitly so the model knows the ID is real but
+     * the details aren't reachable (per the user's "if hydration fails, say
+     * details unavailable" requirement).
+     *
+     * When no (surface, ref) is bound, fall back to admin-page context so
+     * Sara still has SOMETHING to work with on SA-Orchestration admin pages
+     * that don't carry demand params.
+     */
+    private static function user_prompt( array $context, string $prompt, string $page = '', string $asterion_file = '' ): string {
+        $surface = $context['surface'] ?? null;
+        $ref     = $context['ref']     ?? null;
+
+        $context_block = "Context:\n";
+
+        if ( $surface && $ref ) {
+            $adapter  = SA_Orch_Bridge_Fluent::adapter_for( $surface );
+            $hydrated = null;
+            if ( $adapter && method_exists( $adapter, 'hydrate' ) ) {
+                $hydrated = $adapter->hydrate( $ref );
+            }
+
+            if ( is_array( $hydrated ) ) {
+                $context_block .= "User is currently viewing {$surface} / {$ref}.\n";
+                $context_block .= "Bound object details (hydrated through the {$surface} adapter):\n";
+                if ( ! empty( $hydrated['title'] ) ) {
+                    $context_block .= "  Title: {$hydrated['title']}\n";
+                }
+                if ( ! empty( $hydrated['board_name'] ) ) {
+                    $context_block .= "  Board / project: {$hydrated['board_name']}\n";
+                }
+                if ( ! empty( $hydrated['stage'] ) ) {
+                    $context_block .= "  Stage: {$hydrated['stage']}\n";
+                }
+                if ( ! empty( $hydrated['status'] ) ) {
+                    $context_block .= "  Status: {$hydrated['status']}\n";
+                }
+                if ( ! empty( $hydrated['priority'] ) ) {
+                    $context_block .= "  Priority: {$hydrated['priority']}\n";
+                }
+                if ( ! empty( $hydrated['customer'] ) ) {
+                    $context_block .= "  Customer / contact: {$hydrated['customer']}\n";
+                }
+                if ( ! empty( $hydrated['description'] ) ) {
+                    // Board #27 — Description Contract Enforcement: when present,
+                    // the Description IS the contract. Comments are evidence only.
+                    $context_block .= "  Description (CANONICAL CONTRACT — read this first; recent activity below is verification evidence only and cannot define or modify the contract):\n";
+                    $context_block .= "  {$hydrated['description']}\n";
+                }
+                if ( ! empty( $hydrated['recent_activity'] ) && is_array( $hydrated['recent_activity'] ) ) {
+                    $context_block .= "  Recent activity (verification evidence; not the contract):\n";
+                    foreach ( $hydrated['recent_activity'] as $item ) {
+                        $when = isset( $item['created_at'] ) ? "[{$item['created_at']}] " : '';
+                        $by   = ! empty( $item['by'] )       ? "({$item['by']}) "          : '';
+                        $exc  = isset( $item['excerpt'] )    ? (string) $item['excerpt']  : '';
+                        $context_block .= "    - {$when}{$by}{$exc}\n";
+                    }
+                }
+            } else {
+                // Hydration failed — either no adapter for this surface yet,
+                // or the adapter returned null. Per spec: tell the model the
+                // ID is bound but details are unavailable.
+                $reason = $adapter
+                    ? "the {$surface} adapter could not resolve the ref"
+                    : "no adapter is registered for {$surface} yet";
+                $context_block .= "User is currently viewing {$surface} / {$ref}.\n";
+                $context_block .= "Bound object details: UNAVAILABLE ({$reason}). Tell the user the context ID is bound but the underlying details could not be fetched, and answer based on the ref alone.\n";
+            }
+        } elseif ( $page !== '' ) {
+            $context_block .= "User is on admin page '{$page}' (no specific item bound).\n";
+        } else {
+            $context_block .= "No specific surface context detected.\n";
+        }
+
+        // Board #28 — Sara Asterion Context Binding.
+        // Inject the canonical document under view, before the user prompt,
+        // clearly labeled. No transformation: visibility only.
+        $asterion_block = '';
+        if ( $asterion_file !== '' && class_exists( 'SA_Orch_Asterion_Explorer' ) ) {
+            $resolved = SA_Orch_Asterion_Explorer::validate_relative_path( $asterion_file );
+            if ( is_array( $resolved ) ) {
+                $content = @file_get_contents( $resolved['absolute'] );
+                if ( $content !== false ) {
+                    $cap = 12000; // chars; truncation only allowed transformation
+                    $truncated = false;
+                    if ( strlen( $content ) > $cap ) {
+                        $content = function_exists( 'mb_substr' )
+                            ? mb_substr( $content, 0, $cap )
+                            : substr( $content, 0, $cap );
+                        $truncated = true;
+                    }
+                    $asterion_block  = "\n--\n\n";
+                    $asterion_block .= "ASTERION CANONICAL DOCUMENT — READ FIRST\n";
+                    $asterion_block .= "File: {$resolved['relative']}\n\n";
+                    $asterion_block .= $content;
+                    if ( $truncated ) {
+                        $asterion_block .= "\n\n[truncated to {$cap} chars]";
+                    }
+                    $asterion_block .= "\n";
+                }
+            }
+        }
+
+        return $context_block . $asterion_block . "\n--\n\nUser prompt:\n\n" . $prompt;
+    }
+
+    /**
+     * Convert a prior assistant turn (structured response) back into readable
+     * text the model can consume on replay. Accepts either the structured
+     * array shape or a plain string (defensive).
+     */
+    private static function format_assistant_replay( $content ): string {
+        if ( is_string( $content ) ) {
+            return $content;
+        }
+        if ( ! is_array( $content ) ) {
+            return '';
+        }
+        $parts = [];
+        foreach ( [ 'summary', 'suggestion', 'draft', 'notes' ] as $key ) {
+            $val = isset( $content[ $key ] ) ? trim( (string) $content[ $key ] ) : '';
+            if ( $val !== '' ) {
+                $parts[] = ucfirst( $key ) . ":\n" . $val;
+            }
+        }
+        return $parts ? implode( "\n\n", $parts ) : '(empty response)';
+    }
+}

sa-orchestration/includes/class-sa-seed-generator.php

@@ -0,0 +1,523 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Sara — Asterion Seed Generator (Board #26)
+ *
+ * Locked principle:
+ *   Sara generates seeds. Asterion validates seeds. Human plants seeds.
+ *
+ * A "seed" is structured markdown — project momentum distilled into a
+ * non-canonical .md file ready for human review and (later) deliberate
+ * promotion into the Asterion canonical corpus. The seed is NEVER written
+ * to the canonical spec pack by this system; promotion is a separate,
+ * explicit human act that lives outside this Board's scope.
+ *
+ * 7 INTENT questions resolved (simplest valid implementation):
+ *   (a) Storage:  wp-content/sa-asterion-seeds/<project_slug>/
+ *   (b) Filename: <yyyy-mm-dd>-<topic>.md, with frontmatter
+ *   (c) Trigger:  REST endpoint + admin submenu page (no auto-emission)
+ *   (d) Project:  Fluent Boards board_id
+ *   (e) Strategy: Sara-mediated synthesis (LLM via SA_Orch_Sara_Service)
+ *   (f) Promote:  DEFERRED — out of scope for #26
+ *   (g) Index:    NO new table; pure-filesystem listing
+ *
+ * Hard boundaries:
+ *   - No mutation to Archvie/sa-core/docs/specs/
+ *   - No mutation to fbs_tasks / fbs_comments
+ *   - No new schema; uses filesystem only
+ *   - No fluent state changes
+ */
+class SA_Orch_Seed_Generator {
+
+    const SUBMENU_SLUG = 'sa-orchestration-seeds';
+
+    /* -------------------- Hooks -------------------- */
+
+    public static function register_routes() {
+        register_rest_route( 'sa-orch/v1', '/seed/generate', [
+            'methods'             => 'POST',
+            'callback'            => [ __CLASS__, 'rest_generate' ],
+            'permission_callback' => function () {
+                return current_user_can( 'manage_options' );
+            },
+            'args' => [
+                'board_id' => [ 'type' => 'integer', 'required' => true ],
+                'topic'    => [ 'type' => 'string',  'required' => false ],
+            ],
+        ] );
+
+        register_rest_route( 'sa-orch/v1', '/seed/list', [
+            'methods'             => 'GET',
+            'callback'            => [ __CLASS__, 'rest_list' ],
+            'permission_callback' => function () {
+                return current_user_can( 'manage_options' );
+            },
+        ] );
+    }
+
+    public static function register_menu() {
+        add_submenu_page(
+            SA_Orch_Admin::PARENT_SLUG,
+            'Asterion Seeds',
+            'Asterion Seeds',
+            SA_Orch_Admin::CAP,
+            self::SUBMENU_SLUG,
+            [ __CLASS__, 'render_page' ]
+        );
+    }
+
+    /* -------------------- Storage paths -------------------- */
+
+    public static function seeds_root(): string {
+        $base = trailingslashit( WP_CONTENT_DIR ) . 'sa-asterion-seeds';
+        $base = apply_filters( 'sa_orch_seed_root', $base );
+        return rtrim( str_replace( '\\', '/', (string) $base ), '/' );
+    }
+
+    private static function ensure_dir( string $abs ): bool {
+        if ( is_dir( $abs ) ) return true;
+        return wp_mkdir_p( $abs );
+    }
+
+    private static function slug( string $s ): string {
+        $s = sanitize_title( $s );
+        $s = $s !== '' ? $s : 'seed';
+        return $s;
+    }
+
+    /* -------------------- REST -------------------- */
+
+    public static function rest_generate( WP_REST_Request $request ) {
+        $board_id = (int) $request->get_param( 'board_id' );
+        $topic    = sanitize_text_field( (string) $request->get_param( 'topic' ) );
+
+        if ( $board_id <= 0 ) {
+            return new WP_REST_Response( [
+                'error'   => 'invalid_board_id',
+                'message' => 'board_id must be a positive integer',
+            ], 400 );
+        }
+
+        $result = self::generate( $board_id, $topic );
+        if ( is_wp_error( $result ) ) {
+            return new WP_REST_Response( [
+                'error'   => $result->get_error_code(),
+                'message' => $result->get_error_message(),
+            ], 502 );
+        }
+
+        return new WP_REST_Response( $result, 200 );
+    }
+
+    public static function rest_list( WP_REST_Request $request ) {
+        return new WP_REST_Response( [ 'seeds' => self::list_seeds() ], 200 );
+    }
+
+    /* -------------------- Generation -------------------- */
+
+    /**
+     * Generate a seed packet for a Fluent Board.
+     *
+     * Steps:
+     *   1. Read project momentum from fbs_tasks (counts by stage, recent activity).
+     *   2. Build a structured analysis prompt for Sara.
+     *   3. Call SA_Orch_Sara_Service::invoke() — INTERPRETIVE-mode signals
+     *      embedded in the prompt so synthesis (not paraphrase) is produced.
+     *   4. Compose final markdown with YAML frontmatter (artifact_class: seed,
+     *      accepted_into_asterion: false) + Sara's synthesis as body.
+     *      NOTE: artifact_class — NOT truth_class. Seeds are non-canonical
+     *      proposed candidates that pre-date truth classification. I2's
+     *      truth_class enum (canonical | projected | cached | inferred |
+     *      derived | synthetic) stays sacred and is not widened to admit
+     *      seeds; seeds get their own classification dimension.
+     *   5. Write to wp-content/sa-asterion-seeds/<slug>/<date>-<topic>.md.
+     *   6. Return the file path + relative path + summary stats.
+     */
+    public static function generate( int $board_id, string $topic = '' ) {
+        global $wpdb;
+
+        // 1. Project metadata
+        $board = $wpdb->get_row( $wpdb->prepare(
+            "SELECT id, title FROM {$wpdb->prefix}fbs_boards WHERE id = %d",
+            $board_id
+        ), ARRAY_A );
+        if ( ! $board ) {
+            return new WP_Error( 'board_not_found', "Board {$board_id} not found." );
+        }
+
+        // 2. Tasks on this board (parent only, non-archived)
+        $tasks = $wpdb->get_results( $wpdb->prepare(
+            "SELECT id, title, stage_id, status, priority, last_completed_at, created_at, updated_at
+             FROM {$wpdb->prefix}fbs_tasks
+             WHERE board_id = %d AND (parent_id IS NULL OR parent_id = 0) AND archived_at IS NULL
+             ORDER BY id ASC",
+            $board_id
+        ), ARRAY_A );
+
+        // Stage label map
+        $stages = $wpdb->get_results( $wpdb->prepare(
+            "SELECT id, title FROM {$wpdb->prefix}fbs_board_terms WHERE board_id = %d AND type = 'stage'",
+            $board_id
+        ), ARRAY_A );
+        $slabel = [];
+        foreach ( $stages as $s ) $slabel[ (int) $s['id'] ] = (string) $s['title'];
+
+        // 3. Build momentum analysis (deterministic, pre-LLM)
+        $momentum = self::build_momentum( $tasks, $slabel );
+
+        // 4. Build prompt for Sara (INTERPRETIVE mode trigger via doctrine vocabulary)
+        $analysis_block = self::format_momentum_for_prompt( $board, $momentum, $tasks, $slabel );
+        $sara_prompt    = "Synthesize an Asterion seed packet for the project below.\n"
+                        . "\n"
+                        . "This is a doctrine-grade seed: the output will be a non-canonical\n"
+                        . "markdown candidate for human review and possible promotion into the\n"
+                        . "Asterion canonical spec corpus. Speak in interpretive mode — name\n"
+                        . "the underlying thesis of the project's momentum, identify accepted\n"
+                        . "invariants implied by the closed Boards, surface deferred items as\n"
+                        . "their own structural class, and propose 2–4 specific Asterion\n"
+                        . "additions (each as a one-line proposed canonical addition).\n"
+                        . "\n"
+                        . "Return the structured 4-key Sara shape. Use:\n"
+                        . "  summary    — 2-4 sentence thesis of the project's current state\n"
+                        . "  suggestion — one specific architectural observation worth surfacing to Asterion\n"
+                        . "  draft      — the proposed Asterion addition(s), markdown-formatted, one or more\n"
+                        . "               headed sections (## Proposed addition: …) ready to paste into a spec file\n"
+                        . "  notes      — open questions, deferred items, attribution flags, low-confidence calls\n"
+                        . "\n"
+                        . "Project analysis (pre-computed):\n"
+                        . "\n"
+                        . $analysis_block;
+
+        // 5. Call Sara
+        $sara = SA_Orch_Sara_Service::invoke(
+            [ 'surface' => null, 'ref' => null ],
+            $sara_prompt,
+            [],
+            'sa-orchestration-seeds',
+            ''
+        );
+        if ( is_wp_error( $sara ) ) {
+            return $sara;
+        }
+        $resp   = isset( $sara['response'] ) && is_array( $sara['response'] ) ? $sara['response'] : [];
+        $log_id = $sara['log_id'] ?? null;
+
+        // 6. Compose final MD with frontmatter
+        $project_slug = self::slug( $board['title'] ?: ('board-' . $board_id) );
+        $date_utc     = gmdate( 'Y-m-d' );
+        $time_utc     = gmdate( 'Y-m-d\TH:i:s\Z' );
+        $topic_slug   = $topic !== '' ? self::slug( $topic ) : ('momentum-' . substr( md5( $time_utc ), 0, 6 ));
+        $relative     = $project_slug . '/' . $date_utc . '-' . $topic_slug . '.md';
+        $abs_dir      = self::seeds_root() . '/' . $project_slug;
+        $abs_file     = self::seeds_root() . '/' . $relative;
+
+        if ( ! self::ensure_dir( $abs_dir ) ) {
+            return new WP_Error( 'mkdir_failed', "Could not create seed directory {$abs_dir}" );
+        }
+
+        $md = self::compose_markdown(
+            $board,
+            $project_slug,
+            $time_utc,
+            $log_id,
+            $momentum,
+            $resp
+        );
+
+        $written = @file_put_contents( $abs_file, $md );
+        if ( $written === false ) {
+            return new WP_Error( 'write_failed', "Could not write seed file {$abs_file}" );
+        }
+
+        return [
+            'ok'           => true,
+            'board_id'     => $board_id,
+            'board_title'  => $board['title'],
+            'project_slug' => $project_slug,
+            'relative'     => $relative,
+            'absolute'     => $abs_file,
+            'bytes'        => strlen( $md ),
+            'log_id'       => $log_id,
+            'momentum'     => $momentum,
+            'sara_response'=> $resp,
+        ];
+    }
+
+    /* -------------------- Helpers -------------------- */
+
+    private static function build_momentum( array $tasks, array $slabel ): array {
+        $by_stage = [];
+        $by_status = [];
+        $closed_recent = [];
+        $open_now      = [];
+        $deferred      = [];
+        $now = time();
+        $week = 7 * 24 * 3600;
+
+        foreach ( $tasks as $t ) {
+            $sn = $slabel[ (int) $t['stage_id'] ] ?? ('stage_' . $t['stage_id']);
+            $by_stage[ $sn ]    = ( $by_stage[ $sn ] ?? 0 ) + 1;
+            $by_status[ $t['status'] ] = ( $by_status[ $t['status'] ] ?? 0 ) + 1;
+
+            if ( $t['status'] === 'closed' && $t['last_completed_at'] ) {
+                $ts = strtotime( $t['last_completed_at'] );
+                if ( $ts && $now - $ts <= $week ) {
+                    $closed_recent[] = $t;
+                }
+            }
+            if ( $t['status'] !== 'closed' ) {
+                $open_now[] = $t;
+            }
+            if ( strpos( strtolower( (string) $t['title'] ), '[queue]' ) !== false ) {
+                $deferred[] = $t;
+            }
+        }
+
+        return [
+            'task_count'     => count( $tasks ),
+            'by_stage'       => $by_stage,
+            'by_status'      => $by_status,
+            'closed_in_week' => count( $closed_recent ),
+            'open_now'       => count( $open_now ),
+            'deferred'       => count( $deferred ),
+            'closed_recent_titles' => array_map( function ( $t ) {
+                return [ 'id' => (int) $t['id'], 'title' => (string) $t['title'] ];
+            }, $closed_recent ),
+            'open_now_titles' => array_map( function ( $t ) {
+                return [ 'id' => (int) $t['id'], 'title' => (string) $t['title'] ];
+            }, $open_now ),
+        ];
+    }
+
+    private static function format_momentum_for_prompt( array $board, array $momentum, array $tasks, array $slabel ): string {
+        $out  = "Project: {$board['title']} (board_id={$board['id']})\n";
+        $out .= "Total tasks: {$momentum['task_count']}\n";
+        $out .= "Closed in last 7 days: {$momentum['closed_in_week']}\n";
+        $out .= "Currently open: {$momentum['open_now']}\n";
+        $out .= "Deferred ([QUEUE]-tagged): {$momentum['deferred']}\n";
+        $out .= "\n";
+        $out .= "By stage:\n";
+        foreach ( $momentum['by_stage'] as $k => $n ) {
+            $out .= "  {$k}: {$n}\n";
+        }
+        $out .= "\n";
+        $out .= "Recently closed (last 7 days):\n";
+        if ( empty( $momentum['closed_recent_titles'] ) ) {
+            $out .= "  (none)\n";
+        } else {
+            foreach ( $momentum['closed_recent_titles'] as $r ) {
+                $out .= "  - [#{$r['id']}] {$r['title']}\n";
+            }
+        }
+        $out .= "\n";
+        $out .= "Currently open:\n";
+        if ( empty( $momentum['open_now_titles'] ) ) {
+            $out .= "  (none)\n";
+        } else {
+            foreach ( $momentum['open_now_titles'] as $r ) {
+                $out .= "  - [#{$r['id']}] {$r['title']}\n";
+            }
+        }
+        $out .= "\n";
+        return $out;
+    }
+
+    /**
+     * Build the final seed markdown:
+     *   - YAML frontmatter (artifact_class: seed; accepted_into_asterion: false)
+     *   - Header with project + generation context
+     *   - Momentum block (deterministic stats)
+     *   - Sara synthesis (4 fields rendered as headed sections)
+     *   - Footer noting non-canonical status + planting instructions
+     *
+     * artifact_class is intentionally NOT truth_class. Seeds are non-canonical
+     * proposed candidates predating truth classification. I2's enum stays
+     * sacred (canonical | projected | cached | inferred | derived | synthetic).
+     */
+    private static function compose_markdown( array $board, string $project_slug, string $time_utc, $log_id, array $momentum, array $sara_resp ): string {
+        $title = (string) $board['title'];
+        $bid   = (int) $board['id'];
+        $log   = $log_id !== null ? (int) $log_id : 'null';
+
+        $md  = "---\n";
+        $md .= "artifact_class: seed\n";
+        $md .= "accepted_into_asterion: false\n";
+        $md .= "project: " . self::yaml_escape( $title ) . "\n";
+        $md .= "project_slug: {$project_slug}\n";
+        $md .= "board_id: {$bid}\n";
+        $md .= "generated_at: {$time_utc}\n";
+        $md .= "sara_log_id: {$log}\n";
+        $md .= "generator: SA_Orch_Seed_Generator\n";
+        $md .= "---\n\n";
+
+        $md .= "# Asterion seed: {$title}\n\n";
+        $md .= "> **Non-canonical.** This file is a Sara-generated seed packet for human review.\n";
+        $md .= "> It has not been planted into the Asterion canonical spec corpus.\n";
+        $md .= "> Promotion is a separate, deliberate act outside this generator's scope.\n\n";
+
+        $md .= "## Project momentum (deterministic)\n\n";
+        $md .= "- Total tasks: {$momentum['task_count']}\n";
+        $md .= "- Closed in last 7 days: {$momentum['closed_in_week']}\n";
+        $md .= "- Currently open: {$momentum['open_now']}\n";
+        $md .= "- Deferred ([QUEUE]-tagged): {$momentum['deferred']}\n\n";
+        $md .= "By stage:\n\n";
+        foreach ( $momentum['by_stage'] as $k => $n ) {
+            $md .= "- `{$k}`: {$n}\n";
+        }
+        $md .= "\n";
+
+        $md .= "## Sara synthesis (interpretive)\n\n";
+
+        $sum  = trim( (string) ( $sara_resp['summary']    ?? '' ) );
+        $sug  = trim( (string) ( $sara_resp['suggestion'] ?? '' ) );
+        $drf  = trim( (string) ( $sara_resp['draft']      ?? '' ) );
+        $note = trim( (string) ( $sara_resp['notes']      ?? '' ) );
+
+        $md .= "### Thesis\n\n";
+        $md .= ( $sum !== '' ? $sum : '_(none)_' ) . "\n\n";
+
+        $md .= "### Architectural observation\n\n";
+        $md .= ( $sug !== '' ? $sug : '_(none)_' ) . "\n\n";
+
+        $md .= "### Proposed Asterion addition(s)\n\n";
+        $md .= ( $drf !== '' ? $drf : '_(none)_' ) . "\n\n";
+
+        $md .= "### Open questions / deferred / flags\n\n";
+        $md .= ( $note !== '' ? $note : '_(none)_' ) . "\n\n";
+
+        $md .= "---\n\n";
+        $md .= "## Planting (manual)\n\n";
+        $md .= "If accepted: review the proposed additions above, copy any that survive review into\n";
+        $md .= "`Archvie/sa-core/docs/specs/` (the canonical corpus), commit, and update this seed's\n";
+        $md .= "frontmatter `accepted_into_asterion: true` (the generator will not flip that flag).\n";
+        $md .= "If rejected: the seed remains in `wp-content/sa-asterion-seeds/` as a record that the\n";
+        $md .= "synthesis was attempted; nothing in canonical Asterion changes.\n";
+
+        return $md;
+    }
+
+    private static function yaml_escape( string $s ): string {
+        // YAML-safe single-line: wrap in double quotes, escape backslash + quotes.
+        $s = str_replace( [ '\\', '"' ], [ '\\\\', '\\"' ], $s );
+        return '"' . $s . '"';
+    }
+
+    /* -------------------- Listing -------------------- */
+
+    /**
+     * List existing seed files (filesystem-only; no index table per question (g)).
+     */
+    public static function list_seeds(): array {
+        $root = self::seeds_root();
+        if ( ! is_dir( $root ) ) return [];
+        $out = [];
+        $projects = @scandir( $root );
+        if ( $projects === false ) return [];
+        foreach ( $projects as $p ) {
+            if ( $p === '.' || $p === '..' ) continue;
+            $abs = $root . '/' . $p;
+            if ( ! is_dir( $abs ) ) continue;
+            $files = @scandir( $abs );
+            if ( $files === false ) continue;
+            foreach ( $files as $f ) {
+                if ( $f === '.' || $f === '..' ) continue;
+                if ( substr( strtolower( $f ), -3 ) !== '.md' ) continue;
+                $rel = $p . '/' . $f;
+                $st  = @stat( $abs . '/' . $f );
+                $out[] = [
+                    'project_slug' => $p,
+                    'file'         => $f,
+                    'relative'     => $rel,
+                    'size'         => $st ? (int) $st['size'] : 0,
+                    'mtime'        => $st ? gmdate( 'Y-m-d\TH:i:s\Z', (int) $st['mtime'] ) : '',
+                ];
+            }
+        }
+        usort( $out, function ( $a, $b ) { return strcmp( $b['mtime'], $a['mtime'] ); } );
+        return $out;
+    }
+
+    /* -------------------- Admin page -------------------- */
+
+    public static function render_page() {
+        if ( ! current_user_can( SA_Orch_Admin::CAP ) ) wp_die( 'Insufficient permissions.' );
+
+        // Handle synchronous form submission
+        $result = null;
+        $error  = '';
+        if ( isset( $_POST['sa_orch_seed_generate'] ) && check_admin_referer( 'sa_orch_seed_generate' ) ) {
+            $bid   = isset( $_POST['board_id'] ) ? (int) $_POST['board_id'] : 0;
+            $topic = isset( $_POST['topic'] )    ? sanitize_text_field( wp_unslash( $_POST['topic'] ) ) : '';
+            if ( $bid <= 0 ) {
+                $error = 'board_id required';
+            } else {
+                $r = self::generate( $bid, $topic );
+                if ( is_wp_error( $r ) ) {
+                    $error = $r->get_error_message();
+                } else {
+                    $result = $r;
+                }
+            }
+        }
+
+        global $wpdb;
+        $boards = $wpdb->get_results( "SELECT id, title FROM {$wpdb->prefix}fbs_boards ORDER BY id", ARRAY_A );
+        $seeds  = self::list_seeds();
+
+        echo '<div class="wrap">';
+        echo '<h1>Asterion Seeds <span style="font-size:13px;color:#777;font-weight:400;">— non-canonical seed packets generated by Sara</span></h1>';
+
+        echo '<p><em>Sara generates. Asterion validates. Human plants.</em></p>';
+        echo '<p>Seed root: <code>' . esc_html( self::seeds_root() ) . '</code></p>';
+
+        if ( $error !== '' ) {
+            echo '<div class="notice notice-error"><p>' . esc_html( $error ) . '</p></div>';
+        }
+        if ( $result ) {
+            echo '<div class="notice notice-success"><p>Seed written to <code>' . esc_html( $result['relative'] ) . '</code> ('
+                 . (int) $result['bytes'] . ' bytes).</p></div>';
+        }
+
+        echo '<h2>Generate a new seed</h2>';
+        echo '<form method="post">';
+        wp_nonce_field( 'sa_orch_seed_generate' );
+        echo '<table class="form-table">';
+        echo '<tr><th><label for="sa-orch-seed-board">Project (Fluent Board)</label></th><td>';
+        echo '<select id="sa-orch-seed-board" name="board_id" required>';
+        echo '<option value="">— select board —</option>';
+        foreach ( $boards as $b ) {
+            echo '<option value="' . (int) $b['id'] . '">[#' . (int) $b['id'] . '] ' . esc_html( $b['title'] ) . '</option>';
+        }
+        echo '</select>';
+        echo '</td></tr>';
+        echo '<tr><th><label for="sa-orch-seed-topic">Topic (optional, becomes filename slug)</label></th><td>';
+        echo '<input id="sa-orch-seed-topic" name="topic" type="text" class="regular-text" placeholder="e.g. midweek-momentum">';
+        echo '</td></tr>';
+        echo '</table>';
+        echo '<p><button type="submit" name="sa_orch_seed_generate" value="1" class="button button-primary">Generate seed</button></p>';
+        echo '<p style="color:#666;font-size:12px;">Generation calls the configured LLM provider (Sara). One LLM call per generation; cost logged in <code>wp_sa_token_log</code>.</p>';
+        echo '</form>';
+
+        echo '<h2>Existing seeds (' . count( $seeds ) . ')</h2>';
+        if ( empty( $seeds ) ) {
+            echo '<p>No seeds generated yet.</p>';
+        } else {
+            echo '<table class="widefat striped"><thead><tr>';
+            echo '<th>Project</th><th>File</th><th>Size</th><th>Generated (UTC)</th>';
+            echo '</tr></thead><tbody>';
+            foreach ( $seeds as $s ) {
+                echo '<tr>';
+                echo '<td><code>' . esc_html( $s['project_slug'] ) . '</code></td>';
+                echo '<td><code>' . esc_html( $s['file'] ) . '</code></td>';
+                echo '<td>' . (int) $s['size'] . '</td>';
+                echo '<td>' . esc_html( $s['mtime'] ) . '</td>';
+                echo '</tr>';
+            }
+            echo '</tbody></table>';
+            echo '<p style="color:#666;font-size:12px;">Files live on disk under the seed root. No DB index (per resolved question (g)).</p>';
+        }
+
+        echo '</div>';
+    }
+}

sa-orchestration/includes/class-sa-strategy.php

@@ -0,0 +1,83 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Strategy LLM Review orchestrator.
+ *
+ * Layer 3 of the review stack. Delegates to the active provider (resolved
+ * via SA_Orch_LLM_Providers::get_active_provider()) and adds metadata
+ * about which provider produced the result.
+ *
+ * Constraints (enforced by contract, not code):
+ *   - The Strategy Review NEVER overrides closure_state or
+ *     needs_human_arbitration. Those are governed by the deterministic
+ *     audit and ultimately by human arbitration.
+ *   - Strategy Review is purely advisory.
+ */
+class SA_Orch_Strategy {
+
+    /**
+     * Run a Strategy Review against the trace + deterministic audit.
+     *
+     * Returns the provider's review_trace() output augmented with:
+     *   - provider_id      (string)
+     *   - provider_name    (string)
+     *   - provider_error   (string, optional — present if the provider threw)
+     */
+    public static function review( array $trace, array $deterministic_audit ): array {
+        $configured  = SA_Orch_LLM_Providers::get_active_provider();
+        $configured_id   = $configured->id();
+        $configured_name = $configured->name();
+
+        $fallback_used = false;
+        $error_message = null;
+        $used          = $configured;
+
+        try {
+            $review = $configured->review_trace( $trace, $deterministic_audit );
+        } catch ( \Throwable $e ) {
+            // Fallback to simulated on any error from the configured provider
+            $fallback      = new SA_Orch_LLM_Provider_Simulated();
+            $review        = $fallback->review_trace( $trace, $deterministic_audit );
+            $error_message = $e->getMessage();
+            $fallback_used = true;
+            $used          = $fallback;
+        }
+
+        // Defensive: enforce required keys
+        $review = wp_parse_args( $review, [
+            'summary'               => '',
+            'agreement_with_audit'  => 'partial',
+            'additional_risks'      => [],
+            'suggested_next_action' => '',
+            'confidence'            => 'low',
+        ] );
+
+        // Conservative confidence floor (v0.5.2): when the deterministic audit
+        // cannot evaluate closure (closure_confidence='n/a' — i.e. no acceptance
+        // events recorded), the strategy layer MUST collapse to 'low'. Prevents
+        // LLM-shaped over-confidence on Demands with no acceptance evidence.
+        // Cross-cutting: applied here so any provider (including future ones)
+        // gets it for free, regardless of what the model returned.
+        if ( ( $deterministic_audit['closure_confidence'] ?? '' ) === 'n/a'
+             && in_array( $review['confidence'], [ 'medium', 'high' ], true ) ) {
+            $review['confidence'] = 'low';
+        }
+
+        // Provider used to actually produce this output
+        $review['provider_id']   = $used->id();
+        $review['provider_name'] = $used->name();
+
+        // Configured provider (what the operator selected)
+        $review['configured_provider_id']   = $configured_id;
+        $review['configured_provider_name'] = $configured_name;
+
+        // Fallback transparency
+        $review['fallback_used'] = $fallback_used;
+        if ( $error_message !== null ) {
+            $review['provider_error'] = $error_message;
+        }
+
+        return $review;
+    }
+}

sa-orchestration/includes/class-sa-token-log.php

@@ -0,0 +1,114 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Token Log — append-only audit of LLM invocations (Board #16).
+ *
+ * Each call to an LLM provider (OpenAI today; pluggable) writes one row.
+ * The row optionally links to a downstream actor-authored comment via
+ * (comment_kind, comment_id) once the future invocation surface ships
+ * and starts attributing AI-driven commits to actors.
+ *
+ * Two consumers:
+ *   1. Sara UI — reads usage from the live response (NOT from this table)
+ *      to render per-turn + session totals in the bubble. Session total is
+ *      JS-only; this table is server-side audit.
+ *   2. Board #23 handoff layer — its filter callback queries
+ *      has_token_for_comment(kind, comment_id) to resolve operator mode.
+ *      Returns true if a row matches, false otherwise. Always deterministic.
+ *
+ * Doctrine constraints honored:
+ *   - No cost calculation. No analytics. No replay.
+ *   - Server-side persistence is for cross-session attribution (the #23
+ *     hook). The Sara UI counters remain session-only as locked.
+ *   - Strictly additive: one new table; no existing table mutated.
+ */
+class SA_Orch_Token_Log {
+
+    private static function table(): string {
+        global $wpdb;
+        return $wpdb->prefix . SA_ORCH_DB_PREFIX . 'token_log';
+    }
+
+    /**
+     * Record one LLM invocation. Returns the new row id, or 0 on failure.
+     *
+     * @param string $provider  e.g. 'openai'
+     * @param string $model     e.g. 'gpt-4o-mini'
+     * @param array  $usage     [ prompt_tokens, completion_tokens, total_tokens ]
+     * @param int    $user_id   the WP user_id who triggered the call (or 0)
+     */
+    public static function record( string $provider, string $model, array $usage, int $user_id = 0 ): int {
+        if ( $provider === '' ) return 0;
+        global $wpdb;
+        $ok = $wpdb->insert( self::table(), [
+            'user_id'           => $user_id > 0 ? $user_id : null,
+            'provider'          => $provider,
+            'model'             => $model,
+            'prompt_tokens'     => isset( $usage['prompt_tokens'] )     ? (int) $usage['prompt_tokens']     : 0,
+            'completion_tokens' => isset( $usage['completion_tokens'] ) ? (int) $usage['completion_tokens'] : 0,
+            'total_tokens'      => isset( $usage['total_tokens'] )      ? (int) $usage['total_tokens']      : 0,
+            'comment_kind'      => null,
+            'comment_id'        => null,
+            'invoked_at'        => current_time( 'mysql', true ),
+        ] );
+        return $ok !== false ? (int) $wpdb->insert_id : 0;
+    }
+
+    /**
+     * Link a previously-recorded token row to the comment it produced.
+     * Called by the future invocation surface when an actor-attributed
+     * comment is committed from a Sara draft.
+     *
+     * Idempotent on the row's identity — re-linking just updates the row.
+     */
+    public static function link_to_comment( int $log_id, string $kind, int $comment_id ): bool {
+        if ( $log_id <= 0 || $comment_id <= 0 ) return false;
+        $kind = sanitize_key( $kind );
+        if ( $kind === '' ) return false;
+
+        global $wpdb;
+        $ok = $wpdb->update(
+            self::table(),
+            [
+                'comment_kind' => $kind,
+                'comment_id'   => $comment_id,
+            ],
+            [ 'id' => $log_id ]
+        );
+        return $ok !== false;
+    }
+
+    /**
+     * Filter callback for Board #23's 'sa_orch_handoff_has_llm_token'.
+     * Returns true if at least one token row is linked to (kind, comment_id),
+     * false otherwise. Always deterministic — no nulls.
+     */
+    public static function has_token_for_comment( string $kind, int $comment_id ): bool {
+        if ( $comment_id <= 0 ) return false;
+        $kind = sanitize_key( $kind );
+        if ( $kind === '' ) return false;
+
+        global $wpdb;
+        $count = (int) $wpdb->get_var( $wpdb->prepare(
+            "SELECT COUNT(*) FROM " . self::table() . "
+             WHERE comment_kind = %s AND comment_id = %d",
+            $kind,
+            $comment_id
+        ) );
+        return $count > 0;
+    }
+
+    /**
+     * Bridge to the Board #23 hook. Hooked at plugin load via add_filter.
+     * Replaces the default 'unknown' (null) with a deterministic boolean.
+     *
+     * @param mixed  $default     The default value (typically null).
+     * @param string $kind        Comment kind constant.
+     * @param int    $comment_id  Comment id.
+     * @return bool
+     */
+    public static function answer_handoff_filter( $default, string $kind, int $comment_id ): bool {
+        return self::has_token_for_comment( $kind, $comment_id );
+    }
+}

sa-orchestration/includes/interface-sa-llm-provider.php

@@ -0,0 +1,48 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Provider contract for the Strategy LLM Review layer.
+ *
+ * Layer 3 of the review stack:
+ *   1. Trace data
+ *   2. Deterministic Trace Audit
+ *   3. Strategy LLM Review (this contract; v0.5 = simulated only)
+ *   4. Human arbitration
+ *
+ * Implementations of this interface must:
+ *   - Treat the deterministic audit as authoritative for closure_state and
+ *     needs_human_arbitration. They MUST NOT override either.
+ *   - Return a five-key advisory shape (see review_trace docblock).
+ *   - Be local-dev safe. No external calls unless the operator has explicitly
+ *     enabled and configured a network-backed provider.
+ */
+interface SA_Orch_LLM_Provider_Interface {
+
+    /** Stable id used in settings ('simulated', 'openai', 'anthropic', etc.). */
+    public function id(): string;
+
+    /** Human-readable name shown in the admin dropdown. */
+    public function name(): string;
+
+    /** Whether this provider needs an API token to function. */
+    public function requires_api_key(): bool;
+
+    /**
+     * Produce a strategy review of the trace.
+     *
+     * Input:
+     *   $trace                — output of SA_Orch_Rest::get_demand_trace().
+     *   $deterministic_audit  — output of SA_Orch_Reasoning::evaluate( $trace ).
+     *
+     * Output (required keys):
+     *   [
+     *     'summary'               => string,                    // narrative
+     *     'agreement_with_audit'  => 'true'|'false'|'partial',
+     *     'additional_risks'      => string[],                  // risks not caught by audit
+     *     'suggested_next_action' => string,
+     *     'confidence'            => 'low'|'medium'|'high',
+     *   ]
+     */
+    public function review_trace( array $trace, array $deterministic_audit ): array;
+}

sa-orchestration/includes/interface-sa-surface-adapter.php

@@ -0,0 +1,63 @@
+<?php
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Surface adapter contract.
+ *
+ * Asterion binds to surface adapters, not tables. External schema
+ * assumptions are bounded to adapter implementations; consumers of
+ * the contract (the orchestration layer) only see the contract.
+ *
+ * Each surface (fluent-support, fluent-boards, fluentcrm, derived,
+ * future) has — or will have — a concrete implementation of this
+ * interface. The implementation encapsulates all schema-specific
+ * resolution. If the external surface's schema changes, the change
+ * lands in one file (the adapter), not across every caller.
+ *
+ * Contract guarantees:
+ *   - id():        the surface identifier this adapter handles
+ *   - validate():  is this ref shape-correct AND resolvable?
+ *   - resolve():   the underlying surface row, or null
+ *   - label():     a human-readable label for the row
+ *   - hydrate():   structured snapshot for downstream consumption (Sara, etc.)
+ *
+ * Out-of-scope for this interface:
+ *   - mutation of surface state (orchestration must not mutate Fluent)
+ *   - paginated listing (a separate adapter capability if needed)
+ */
+interface SA_Orch_Surface_Adapter {
+
+    /** Surface identifier (e.g. 'fluent-boards', 'fluent-support'). */
+    public function id(): string;
+
+    /**
+     * Is the ref shape-correct AND resolvable to a real row under this surface?
+     * Returns true only if both conditions hold. Pure read; no side effects.
+     */
+    public function validate( string $ref ): bool;
+
+    /**
+     * Resolve the ref to the underlying surface row, or null if missing.
+     * The shape of the returned object is implementation-defined; consumers
+     * should access fields only through the adapter's other methods (label,
+     * hydrate) rather than touching schema directly.
+     */
+    public function resolve( string $ref );
+
+    /** Human-readable label for the row, falling back to the ref if unresolvable. */
+    public function label( string $ref ): string;
+
+    /**
+     * Structured snapshot of the bound object — title, state, description
+     * summary, recent activity, etc. — shaped for downstream consumers (Sara).
+     * Returns null if the ref does not resolve. The implementation decides
+     * which fields are meaningful for its surface; consumers should treat
+     * any field as optional and tolerate missing/empty values.
+     *
+     * Conventional keys (all optional): ref, title, status, stage, priority,
+     * board_name, customer, description, recent_activity (array of items;
+     * each item has at minimum { created_at, excerpt } and may also include
+     * optional 'by' for the author of the activity).
+     */
+    public function hydrate( string $ref ): ?array;
+}

sa-orchestration/sa-orchestration.php

@@ -0,0 +1,97 @@
+<?php
+/**
+ * Plugin Name: SA-Orchestration
+ * Description: Arbitration record + Demand→Plan linkage + append-only acceptance events. First slice of SA-Core / MissionNet alignment layer above the Fluent stack.
+ * Version: 0.7.2
+ * Author: Mark Holak
+ * License: GPL-2.0-or-later
+ * Text Domain: sa-orchestration
+ *
+ * Asterion (markdown corpus) is canonical-at-write; this DB layer is cache.
+ * If runtime ≠ Asterion, runtime is wrong. See SA-orchestration/CORE_MODEL.md.
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+define( 'SA_ORCH_VERSION',   '0.7.3' );
+define( 'SA_ORCH_FILE',      __FILE__ );
+define( 'SA_ORCH_DIR',       plugin_dir_path( __FILE__ ) );
+define( 'SA_ORCH_URL',       plugin_dir_url( __FILE__ ) );
+define( 'SA_ORCH_DB_PREFIX', 'sa_' );  // tables become {wp_prefix}sa_*
+
+require_once SA_ORCH_DIR . 'includes/class-sa-migrations.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-asterion.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-bridge-fluent.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-arbitration.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-link.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-acceptance.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-rest.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-reasoning.php';
+require_once SA_ORCH_DIR . 'includes/interface-sa-llm-provider.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-llm-provider-simulated.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-llm-provider-openai.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-llm-settings.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-llm-providers.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-strategy.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-projection-fluent-support.php';
+require_once SA_ORCH_DIR . 'includes/interface-sa-surface-adapter.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-adapter-fluent-boards.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-adapter-fluent-support.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-fluent-state.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-asterion-explorer.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-attention-bridge.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-actor-registry.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-actor-admin.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-actor-handoff.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-token-log.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-env.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-demand-registry.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-sara-service.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-sara-rest.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-sara-admin.php';
+require_once SA_ORCH_DIR . 'includes/class-sa-asterion-projection.php'; // Board #30
+require_once SA_ORCH_DIR . 'includes/class-sa-seed-generator.php';      // Board #26
+require_once SA_ORCH_DIR . 'includes/class-sa-admin.php';
+
+register_activation_hook( __FILE__, [ 'SA_Orch_Migrations', 'install' ] );
+
+add_action( 'rest_api_init', [ 'SA_Orch_Rest', 'register_routes' ] );
+add_action( 'rest_api_init', [ 'SA_Orch_Sara_Rest', 'register_routes' ] );
+add_action( 'rest_api_init', [ 'SA_Orch_Asterion_Projection', 'register_routes' ] ); // Board #30
+add_action( 'rest_api_init', [ 'SA_Orch_Seed_Generator',      'register_routes' ] ); // Board #26
+add_action( 'admin_menu',    [ 'SA_Orch_Admin', 'register_menu' ] );
+add_action( 'admin_menu',    [ 'SA_Orch_Asterion_Explorer', 'register_menu' ] );
+add_action( 'admin_menu',    [ 'SA_Orch_Actor_Admin',       'register_menu' ] );
+add_action( 'admin_menu',    [ 'SA_Orch_Seed_Generator',    'register_menu' ] );      // Board #26
+add_action( 'init',          [ 'SA_Orch_Actor_Registry',    'register_role' ] );
+add_action( 'admin_init',    [ 'SA_Orch_Actor_Admin',       'maybe_handle_action' ] );
+add_action( 'init',          [ 'SA_Orch_Projection_Fluent_Support', 'register_hooks' ] );
+add_action( 'init',          [ 'SA_Orch_Sara_Admin', 'register_hooks' ] );
+add_action( 'init',          [ 'SA_Orch_Asterion_Projection', 'register_hooks' ] );   // Board #30
+add_action( 'init',          [ 'SA_Orch_Attention_Bridge', 'register_hooks' ] );
+
+// Board #16 → Board #23 hook integration. Token Log answers the
+// 'sa_orch_handoff_has_llm_token' filter with a deterministic boolean,
+// turning Board #23's MODE_UNKNOWN into MODE_AI / MODE_HUMAN once a
+// commit is linked to a token row.
+add_filter( 'sa_orch_handoff_has_llm_token', [ 'SA_Orch_Token_Log', 'answer_handoff_filter' ], 10, 3 );
+
+// Board #24 rev2 — Fluent Boards no-conflict dequeue compatibility.
+//
+// Fluent Boards' AdminMenuHandler registers a wp_print_scripts callback that
+// strips any plugin script whose src is under plugins_url() and doesn't
+// match an approved allowlist. Default allowlist: fluent-crm, fluent-boards.
+// Our Sara/Attention scripts are neither, so they get dequeued AFTER our
+// admin_enqueue_scripts call, before any <script> tag is rendered.
+//
+// We add 'sa-orchestration' to the allowlist via this filter. Surgical:
+// it does NOT disable Fluent Boards' no-conflict mechanism (other plugins'
+// scripts are still stripped), and it does NOT change any other behavior
+// in Sara, Attention, or anything else. Just whitelists our plugin path.
+add_filter( 'fluent_boards/asset_listed_slugs', function ( $slugs ) {
+    if ( ! is_array( $slugs ) ) $slugs = [];
+    if ( ! in_array( '\/sa-orchestration\/', $slugs, true ) ) {
+        $slugs[] = '\/sa-orchestration\/';
+    }
+    return $slugs;
+} );

sa-orchestration/vendor/Parsedown.php

@@ -0,0 +1,1712 @@
+<?php
+
+#
+#
+# Parsedown
+# http://parsedown.org
+#
+# (c) Emanuil Rusev
+# http://erusev.com
+#
+# For the full license information, view the LICENSE file that was distributed
+# with this source code.
+#
+#
+
+class Parsedown
+{
+    # ~
+
+    const version = '1.7.4';
+
+    # ~
+
+    function text($text)
+    {
+        # make sure no definitions are set
+        $this->DefinitionData = array();
+
+        # standardize line breaks
+        $text = str_replace(array("\r\n", "\r"), "\n", $text);
+
+        # remove surrounding line breaks
+        $text = trim($text, "\n");
+
+        # split text into lines
+        $lines = explode("\n", $text);
+
+        # iterate through lines to identify blocks
+        $markup = $this->lines($lines);
+
+        # trim line breaks
+        $markup = trim($markup, "\n");
+
+        return $markup;
+    }
+
+    #
+    # Setters
+    #
+
+    function setBreaksEnabled($breaksEnabled)
+    {
+        $this->breaksEnabled = $breaksEnabled;
+
+        return $this;
+    }
+
+    protected $breaksEnabled;
+
+    function setMarkupEscaped($markupEscaped)
+    {
+        $this->markupEscaped = $markupEscaped;
+
+        return $this;
+    }
+
+    protected $markupEscaped;
+
+    function setUrlsLinked($urlsLinked)
+    {
+        $this->urlsLinked = $urlsLinked;
+
+        return $this;
+    }
+
+    protected $urlsLinked = true;
+
+    function setSafeMode($safeMode)
+    {
+        $this->safeMode = (bool) $safeMode;
+
+        return $this;
+    }
+
+    protected $safeMode;
+
+    protected $safeLinksWhitelist = array(
+        'http://',
+        'https://',
+        'ftp://',
+        'ftps://',
+        'mailto:',
+        'data:image/png;base64,',
+        'data:image/gif;base64,',
+        'data:image/jpeg;base64,',
+        'irc:',
+        'ircs:',
+        'git:',
+        'ssh:',
+        'news:',
+        'steam:',
+    );
+
+    #
+    # Lines
+    #
+
+    protected $BlockTypes = array(
+        '#' => array('Header'),
+        '*' => array('Rule', 'List'),
+        '+' => array('List'),
+        '-' => array('SetextHeader', 'Table', 'Rule', 'List'),
+        '0' => array('List'),
+        '1' => array('List'),
+        '2' => array('List'),
+        '3' => array('List'),
+        '4' => array('List'),
+        '5' => array('List'),
+        '6' => array('List'),
+        '7' => array('List'),
+        '8' => array('List'),
+        '9' => array('List'),
+        ':' => array('Table'),
+        '<' => array('Comment', 'Markup'),
+        '=' => array('SetextHeader'),
+        '>' => array('Quote'),
+        '[' => array('Reference'),
+        '_' => array('Rule'),
+        '`' => array('FencedCode'),
+        '|' => array('Table'),
+        '~' => array('FencedCode'),
+    );
+
+    # ~
+
+    protected $unmarkedBlockTypes = array(
+        'Code',
+    );
+
+    #
+    # Blocks
+    #
+
+    protected function lines(array $lines)
+    {
+        $CurrentBlock = null;
+
+        foreach ($lines as $line)
+        {
+            if (chop($line) === '')
+            {
+                if (isset($CurrentBlock))
+                {
+                    $CurrentBlock['interrupted'] = true;
+                }
+
+                continue;
+            }
+
+            if (strpos($line, "\t") !== false)
+            {
+                $parts = explode("\t", $line);
+
+                $line = $parts[0];
+
+                unset($parts[0]);
+
+                foreach ($parts as $part)
+                {
+                    $shortage = 4 - mb_strlen($line, 'utf-8') % 4;
+
+                    $line .= str_repeat(' ', $shortage);
+                    $line .= $part;
+                }
+            }
+
+            $indent = 0;
+
+            while (isset($line[$indent]) and $line[$indent] === ' ')
+            {
+                $indent ++;
+            }
+
+            $text = $indent > 0 ? substr($line, $indent) : $line;
+
+            # ~
+
+            $Line = array('body' => $line, 'indent' => $indent, 'text' => $text);
+
+            # ~
+
+            if (isset($CurrentBlock['continuable']))
+            {
+                $Block = $this->{'block'.$CurrentBlock['type'].'Continue'}($Line, $CurrentBlock);
+
+                if (isset($Block))
+                {
+                    $CurrentBlock = $Block;
+
+                    continue;
+                }
+                else
+                {
+                    if ($this->isBlockCompletable($CurrentBlock['type']))
+                    {
+                        $CurrentBlock = $this->{'block'.$CurrentBlock['type'].'Complete'}($CurrentBlock);
+                    }
+                }
+            }
+
+            # ~
+
+            $marker = $text[0];
+
+            # ~
+
+            $blockTypes = $this->unmarkedBlockTypes;
+
+            if (isset($this->BlockTypes[$marker]))
+            {
+                foreach ($this->BlockTypes[$marker] as $blockType)
+                {
+                    $blockTypes []= $blockType;
+                }
+            }
+
+            #
+            # ~
+
+            foreach ($blockTypes as $blockType)
+            {
+                $Block = $this->{'block'.$blockType}($Line, $CurrentBlock);
+
+                if (isset($Block))
+                {
+                    $Block['type'] = $blockType;
+
+                    if ( ! isset($Block['identified']))
+                    {
+                        $Blocks []= $CurrentBlock;
+
+                        $Block['identified'] = true;
+                    }
+
+                    if ($this->isBlockContinuable($blockType))
+                    {
+                        $Block['continuable'] = true;
+                    }
+
+                    $CurrentBlock = $Block;
+
+                    continue 2;
+                }
+            }
+
+            # ~
+
+            if (isset($CurrentBlock) and ! isset($CurrentBlock['type']) and ! isset($CurrentBlock['interrupted']))
+            {
+                $CurrentBlock['element']['text'] .= "\n".$text;
+            }
+            else
+            {
+                $Blocks []= $CurrentBlock;
+
+                $CurrentBlock = $this->paragraph($Line);
+
+                $CurrentBlock['identified'] = true;
+            }
+        }
+
+        # ~
+
+        if (isset($CurrentBlock['continuable']) and $this->isBlockCompletable($CurrentBlock['type']))
+        {
+            $CurrentBlock = $this->{'block'.$CurrentBlock['type'].'Complete'}($CurrentBlock);
+        }
+
+        # ~
+
+        $Blocks []= $CurrentBlock;
+
+        unset($Blocks[0]);
+
+        # ~
+
+        $markup = '';
+
+        foreach ($Blocks as $Block)
+        {
+            if (isset($Block['hidden']))
+            {
+                continue;
+            }
+
+            $markup .= "\n";
+            $markup .= isset($Block['markup']) ? $Block['markup'] : $this->element($Block['element']);
+        }
+
+        $markup .= "\n";
+
+        # ~
+
+        return $markup;
+    }
+
+    protected function isBlockContinuable($Type)
+    {
+        return method_exists($this, 'block'.$Type.'Continue');
+    }
+
+    protected function isBlockCompletable($Type)
+    {
+        return method_exists($this, 'block'.$Type.'Complete');
+    }
+
+    #
+    # Code
+
+    protected function blockCode($Line, $Block = null)
+    {
+        if (isset($Block) and ! isset($Block['type']) and ! isset($Block['interrupted']))
+        {
+            return;
+        }
+
+        if ($Line['indent'] >= 4)
+        {
+            $text = substr($Line['body'], 4);
+
+            $Block = array(
+                'element' => array(
+                    'name' => 'pre',
+                    'handler' => 'element',
+                    'text' => array(
+                        'name' => 'code',
+                        'text' => $text,
+                    ),
+                ),
+            );
+
+            return $Block;
+        }
+    }
+
+    protected function blockCodeContinue($Line, $Block)
+    {
+        if ($Line['indent'] >= 4)
+        {
+            if (isset($Block['interrupted']))
+            {
+                $Block['element']['text']['text'] .= "\n";
+
+                unset($Block['interrupted']);
+            }
+
+            $Block['element']['text']['text'] .= "\n";
+
+            $text = substr($Line['body'], 4);
+
+            $Block['element']['text']['text'] .= $text;
+
+            return $Block;
+        }
+    }
+
+    protected function blockCodeComplete($Block)
+    {
+        $text = $Block['element']['text']['text'];
+
+        $Block['element']['text']['text'] = $text;
+
+        return $Block;
+    }
+
+    #
+    # Comment
+
+    protected function blockComment($Line)
+    {
+        if ($this->markupEscaped or $this->safeMode)
+        {
+            return;
+        }
+
+        if (isset($Line['text'][3]) and $Line['text'][3] === '-' and $Line['text'][2] === '-' and $Line['text'][1] === '!')
+        {
+            $Block = array(
+                'markup' => $Line['body'],
+            );
+
+            if (preg_match('/-->$/', $Line['text']))
+            {
+                $Block['closed'] = true;
+            }
+
+            return $Block;
+        }
+    }
+
+    protected function blockCommentContinue($Line, array $Block)
+    {
+        if (isset($Block['closed']))
+        {
+            return;
+        }
+
+        $Block['markup'] .= "\n" . $Line['body'];
+
+        if (preg_match('/-->$/', $Line['text']))
+        {
+            $Block['closed'] = true;
+        }
+
+        return $Block;
+    }
+
+    #
+    # Fenced Code
+
+    protected function blockFencedCode($Line)
+    {
+        if (preg_match('/^['.$Line['text'][0].']{3,}[ ]*([^`]+)?[ ]*$/', $Line['text'], $matches))
+        {
+            $Element = array(
+                'name' => 'code',
+                'text' => '',
+            );
+
+            if (isset($matches[1]))
+            {
+                /**
+                 * https://www.w3.org/TR/2011/WD-html5-20110525/elements.html#classes
+                 * Every HTML element may have a class attribute specified.
+                 * The attribute, if specified, must have a value that is a set
+                 * of space-separated tokens representing the various classes
+                 * that the element belongs to.
+                 * [...]
+                 * The space characters, for the purposes of this specification,
+                 * are U+0020 SPACE, U+0009 CHARACTER TABULATION (tab),
+                 * U+000A LINE FEED (LF), U+000C FORM FEED (FF), and
+                 * U+000D CARRIAGE RETURN (CR).
+                 */
+                $language = substr($matches[1], 0, strcspn($matches[1], " \t\n\f\r"));
+
+                $class = 'language-'.$language;
+
+                $Element['attributes'] = array(
+                    'class' => $class,
+                );
+            }
+
+            $Block = array(
+                'char' => $Line['text'][0],
+                'element' => array(
+                    'name' => 'pre',
+                    'handler' => 'element',
+                    'text' => $Element,
+                ),
+            );
+
+            return $Block;
+        }
+    }
+
+    protected function blockFencedCodeContinue($Line, $Block)
+    {
+        if (isset($Block['complete']))
+        {
+            return;
+        }
+
+        if (isset($Block['interrupted']))
+        {
+            $Block['element']['text']['text'] .= "\n";
+
+            unset($Block['interrupted']);
+        }
+
+        if (preg_match('/^'.$Block['char'].'{3,}[ ]*$/', $Line['text']))
+        {
+            $Block['element']['text']['text'] = substr($Block['element']['text']['text'], 1);
+
+            $Block['complete'] = true;
+
+            return $Block;
+        }
+
+        $Block['element']['text']['text'] .= "\n".$Line['body'];
+
+        return $Block;
+    }
+
+    protected function blockFencedCodeComplete($Block)
+    {
+        $text = $Block['element']['text']['text'];
+
+        $Block['element']['text']['text'] = $text;
+
+        return $Block;
+    }
+
+    #
+    # Header
+
+    protected function blockHeader($Line)
+    {
+        if (isset($Line['text'][1]))
+        {
+            $level = 1;
+
+            while (isset($Line['text'][$level]) and $Line['text'][$level] === '#')
+            {
+                $level ++;
+            }
+
+            if ($level > 6)
+            {
+                return;
+            }
+
+            $text = trim($Line['text'], '# ');
+
+            $Block = array(
+                'element' => array(
+                    'name' => 'h' . min(6, $level),
+                    'text' => $text,
+                    'handler' => 'line',
+                ),
+            );
+
+            return $Block;
+        }
+    }
+
+    #
+    # List
+
+    protected function blockList($Line)
+    {
+        list($name, $pattern) = $Line['text'][0] <= '-' ? array('ul', '[*+-]') : array('ol', '[0-9]+[.]');
+
+        if (preg_match('/^('.$pattern.'[ ]+)(.*)/', $Line['text'], $matches))
+        {
+            $Block = array(
+                'indent' => $Line['indent'],
+                'pattern' => $pattern,
+                'element' => array(
+                    'name' => $name,
+                    'handler' => 'elements',
+                ),
+            );
+
+            if($name === 'ol')
+            {
+                $listStart = stristr($matches[0], '.', true);
+
+                if($listStart !== '1')
+                {
+                    $Block['element']['attributes'] = array('start' => $listStart);
+                }
+            }
+
+            $Block['li'] = array(
+                'name' => 'li',
+                'handler' => 'li',
+                'text' => array(
+                    $matches[2],
+                ),
+            );
+
+            $Block['element']['text'] []= & $Block['li'];
+
+            return $Block;
+        }
+    }
+
+    protected function blockListContinue($Line, array $Block)
+    {
+        if ($Block['indent'] === $Line['indent'] and preg_match('/^'.$Block['pattern'].'(?:[ ]+(.*)|$)/', $Line['text'], $matches))
+        {
+            if (isset($Block['interrupted']))
+            {
+                $Block['li']['text'] []= '';
+
+                $Block['loose'] = true;
+
+                unset($Block['interrupted']);
+            }
+
+            unset($Block['li']);
+
+            $text = isset($matches[1]) ? $matches[1] : '';
+
+            $Block['li'] = array(
+                'name' => 'li',
+                'handler' => 'li',
+                'text' => array(
+                    $text,
+                ),
+            );
+
+            $Block['element']['text'] []= & $Block['li'];
+
+            return $Block;
+        }
+
+        if ($Line['text'][0] === '[' and $this->blockReference($Line))
+        {
+            return $Block;
+        }
+
+        if ( ! isset($Block['interrupted']))
+        {
+            $text = preg_replace('/^[ ]{0,4}/', '', $Line['body']);
+
+            $Block['li']['text'] []= $text;
+
+            return $Block;
+        }
+
+        if ($Line['indent'] > 0)
+        {
+            $Block['li']['text'] []= '';
+
+            $text = preg_replace('/^[ ]{0,4}/', '', $Line['body']);
+
+            $Block['li']['text'] []= $text;
+
+            unset($Block['interrupted']);
+
+            return $Block;
+        }
+    }
+
+    protected function blockListComplete(array $Block)
+    {
+        if (isset($Block['loose']))
+        {
+            foreach ($Block['element']['text'] as &$li)
+            {
+                if (end($li['text']) !== '')
+                {
+                    $li['text'] []= '';
+                }
+            }
+        }
+
+        return $Block;
+    }
+
+    #
+    # Quote
+
+    protected function blockQuote($Line)
+    {
+        if (preg_match('/^>[ ]?(.*)/', $Line['text'], $matches))
+        {
+            $Block = array(
+                'element' => array(
+                    'name' => 'blockquote',
+                    'handler' => 'lines',
+                    'text' => (array) $matches[1],
+                ),
+            );
+
+            return $Block;
+        }
+    }
+
+    protected function blockQuoteContinue($Line, array $Block)
+    {
+        if ($Line['text'][0] === '>' and preg_match('/^>[ ]?(.*)/', $Line['text'], $matches))
+        {
+            if (isset($Block['interrupted']))
+            {
+                $Block['element']['text'] []= '';
+
+                unset($Block['interrupted']);
+            }
+
+            $Block['element']['text'] []= $matches[1];
+
+            return $Block;
+        }
+
+        if ( ! isset($Block['interrupted']))
+        {
+            $Block['element']['text'] []= $Line['text'];
+
+            return $Block;
+        }
+    }
+
+    #
+    # Rule
+
+    protected function blockRule($Line)
+    {
+        if (preg_match('/^(['.$Line['text'][0].'])([ ]*\1){2,}[ ]*$/', $Line['text']))
+        {
+            $Block = array(
+                'element' => array(
+                    'name' => 'hr'
+                ),
+            );
+
+            return $Block;
+        }
+    }
+
+    #
+    # Setext
+
+    protected function blockSetextHeader($Line, array $Block = null)
+    {
+        if ( ! isset($Block) or isset($Block['type']) or isset($Block['interrupted']))
+        {
+            return;
+        }
+
+        if (chop($Line['text'], $Line['text'][0]) === '')
+        {
+            $Block['element']['name'] = $Line['text'][0] === '=' ? 'h1' : 'h2';
+
+            return $Block;
+        }
+    }
+
+    #
+    # Markup
+
+    protected function blockMarkup($Line)
+    {
+        if ($this->markupEscaped or $this->safeMode)
+        {
+            return;
+        }
+
+        if (preg_match('/^<(\w[\w-]*)(?:[ ]*'.$this->regexHtmlAttribute.')*[ ]*(\/)?>/', $Line['text'], $matches))
+        {
+            $element = strtolower($matches[1]);
+
+            if (in_array($element, $this->textLevelElements))
+            {
+                return;
+            }
+
+            $Block = array(
+                'name' => $matches[1],
+                'depth' => 0,
+                'markup' => $Line['text'],
+            );
+
+            $length = strlen($matches[0]);
+
+            $remainder = substr($Line['text'], $length);
+
+            if (trim($remainder) === '')
+            {
+                if (isset($matches[2]) or in_array($matches[1], $this->voidElements))
+                {
+                    $Block['closed'] = true;
+
+                    $Block['void'] = true;
+                }
+            }
+            else
+            {
+                if (isset($matches[2]) or in_array($matches[1], $this->voidElements))
+                {
+                    return;
+                }
+
+                if (preg_match('/<\/'.$matches[1].'>[ ]*$/i', $remainder))
+                {
+                    $Block['closed'] = true;
+                }
+            }
+
+            return $Block;
+        }
+    }
+
+    protected function blockMarkupContinue($Line, array $Block)
+    {
+        if (isset($Block['closed']))
+        {
+            return;
+        }
+
+        if (preg_match('/^<'.$Block['name'].'(?:[ ]*'.$this->regexHtmlAttribute.')*[ ]*>/i', $Line['text'])) # open
+        {
+            $Block['depth'] ++;
+        }
+
+        if (preg_match('/(.*?)<\/'.$Block['name'].'>[ ]*$/i', $Line['text'], $matches)) # close
+        {
+            if ($Block['depth'] > 0)
+            {
+                $Block['depth'] --;
+            }
+            else
+            {
+                $Block['closed'] = true;
+            }
+        }
+
+        if (isset($Block['interrupted']))
+        {
+            $Block['markup'] .= "\n";
+
+            unset($Block['interrupted']);
+        }
+
+        $Block['markup'] .= "\n".$Line['body'];
+
+        return $Block;
+    }
+
+    #
+    # Reference
+
+    protected function blockReference($Line)
+    {
+        if (preg_match('/^\[(.+?)\]:[ ]*<?(\S+?)>?(?:[ ]+["\'(](.+)["\')])?[ ]*$/', $Line['text'], $matches))
+        {
+            $id = strtolower($matches[1]);
+
+            $Data = array(
+                'url' => $matches[2],
+                'title' => null,
+            );
+
+            if (isset($matches[3]))
+            {
+                $Data['title'] = $matches[3];
+            }
+
+            $this->DefinitionData['Reference'][$id] = $Data;
+
+            $Block = array(
+                'hidden' => true,
+            );
+
+            return $Block;
+        }
+    }
+
+    #
+    # Table
+
+    protected function blockTable($Line, array $Block = null)
+    {
+        if ( ! isset($Block) or isset($Block['type']) or isset($Block['interrupted']))
+        {
+            return;
+        }
+
+        if (strpos($Block['element']['text'], '|') !== false and chop($Line['text'], ' -:|') === '')
+        {
+            $alignments = array();
+
+            $divider = $Line['text'];
+
+            $divider = trim($divider);
+            $divider = trim($divider, '|');
+
+            $dividerCells = explode('|', $divider);
+
+            foreach ($dividerCells as $dividerCell)
+            {
+                $dividerCell = trim($dividerCell);
+
+                if ($dividerCell === '')
+                {
+                    continue;
+                }
+
+                $alignment = null;
+
+                if ($dividerCell[0] === ':')
+                {
+                    $alignment = 'left';
+                }
+
+                if (substr($dividerCell, - 1) === ':')
+                {
+                    $alignment = $alignment === 'left' ? 'center' : 'right';
+                }
+
+                $alignments []= $alignment;
+            }
+
+            # ~
+
+            $HeaderElements = array();
+
+            $header = $Block['element']['text'];
+
+            $header = trim($header);
+            $header = trim($header, '|');
+
+            $headerCells = explode('|', $header);
+
+            foreach ($headerCells as $index => $headerCell)
+            {
+                $headerCell = trim($headerCell);
+
+                $HeaderElement = array(
+                    'name' => 'th',
+                    'text' => $headerCell,
+                    'handler' => 'line',
+                );
+
+                if (isset($alignments[$index]))
+                {
+                    $alignment = $alignments[$index];
+
+                    $HeaderElement['attributes'] = array(
+                        'style' => 'text-align: '.$alignment.';',
+                    );
+                }
+
+                $HeaderElements []= $HeaderElement;
+            }
+
+            # ~
+
+            $Block = array(
+                'alignments' => $alignments,
+                'identified' => true,
+                'element' => array(
+                    'name' => 'table',
+                    'handler' => 'elements',
+                ),
+            );
+
+            $Block['element']['text'] []= array(
+                'name' => 'thead',
+                'handler' => 'elements',
+            );
+
+            $Block['element']['text'] []= array(
+                'name' => 'tbody',
+                'handler' => 'elements',
+                'text' => array(),
+            );
+
+            $Block['element']['text'][0]['text'] []= array(
+                'name' => 'tr',
+                'handler' => 'elements',
+                'text' => $HeaderElements,
+            );
+
+            return $Block;
+        }
+    }
+
+    protected function blockTableContinue($Line, array $Block)
+    {
+        if (isset($Block['interrupted']))
+        {
+            return;
+        }
+
+        if ($Line['text'][0] === '|' or strpos($Line['text'], '|'))
+        {
+            $Elements = array();
+
+            $row = $Line['text'];
+
+            $row = trim($row);
+            $row = trim($row, '|');
+
+            preg_match_all('/(?:(\\\\[|])|[^|`]|`[^`]+`|`)+/', $row, $matches);
+
+            foreach ($matches[0] as $index => $cell)
+            {
+                $cell = trim($cell);
+
+                $Element = array(
+                    'name' => 'td',
+                    'handler' => 'line',
+                    'text' => $cell,
+                );
+
+                if (isset($Block['alignments'][$index]))
+                {
+                    $Element['attributes'] = array(
+                        'style' => 'text-align: '.$Block['alignments'][$index].';',
+                    );
+                }
+
+                $Elements []= $Element;
+            }
+
+            $Element = array(
+                'name' => 'tr',
+                'handler' => 'elements',
+                'text' => $Elements,
+            );
+
+            $Block['element']['text'][1]['text'] []= $Element;
+
+            return $Block;
+        }
+    }
+
+    #
+    # ~
+    #
+
+    protected function paragraph($Line)
+    {
+        $Block = array(
+            'element' => array(
+                'name' => 'p',
+                'text' => $Line['text'],
+                'handler' => 'line',
+            ),
+        );
+
+        return $Block;
+    }
+
+    #
+    # Inline Elements
+    #
+
+    protected $InlineTypes = array(
+        '"' => array('SpecialCharacter'),
+        '!' => array('Image'),
+        '&' => array('SpecialCharacter'),
+        '*' => array('Emphasis'),
+        ':' => array('Url'),
+        '<' => array('UrlTag', 'EmailTag', 'Markup', 'SpecialCharacter'),
+        '>' => array('SpecialCharacter'),
+        '[' => array('Link'),
+        '_' => array('Emphasis'),
+        '`' => array('Code'),
+        '~' => array('Strikethrough'),
+        '\\' => array('EscapeSequence'),
+    );
+
+    # ~
+
+    protected $inlineMarkerList = '!"*_&[:<>`~\\';
+
+    #
+    # ~
+    #
+
+    public function line($text, $nonNestables=array())
+    {
+        $markup = '';
+
+        # $excerpt is based on the first occurrence of a marker
+
+        while ($excerpt = strpbrk($text, $this->inlineMarkerList))
+        {
+            $marker = $excerpt[0];
+
+            $markerPosition = strpos($text, $marker);
+
+            $Excerpt = array('text' => $excerpt, 'context' => $text);
+
+            foreach ($this->InlineTypes[$marker] as $inlineType)
+            {
+                # check to see if the current inline type is nestable in the current context
+
+                if ( ! empty($nonNestables) and in_array($inlineType, $nonNestables))
+                {
+                    continue;
+                }
+
+                $Inline = $this->{'inline'.$inlineType}($Excerpt);
+
+                if ( ! isset($Inline))
+                {
+                    continue;
+                }
+
+                # makes sure that the inline belongs to "our" marker
+
+                if (isset($Inline['position']) and $Inline['position'] > $markerPosition)
+                {
+                    continue;
+                }
+
+                # sets a default inline position
+
+                if ( ! isset($Inline['position']))
+                {
+                    $Inline['position'] = $markerPosition;
+                }
+
+                # cause the new element to 'inherit' our non nestables
+
+                foreach ($nonNestables as $non_nestable)
+                {
+                    $Inline['element']['nonNestables'][] = $non_nestable;
+                }
+
+                # the text that comes before the inline
+                $unmarkedText = substr($text, 0, $Inline['position']);
+
+                # compile the unmarked text
+                $markup .= $this->unmarkedText($unmarkedText);
+
+                # compile the inline
+                $markup .= isset($Inline['markup']) ? $Inline['markup'] : $this->element($Inline['element']);
+
+                # remove the examined text
+                $text = substr($text, $Inline['position'] + $Inline['extent']);
+
+                continue 2;
+            }
+
+            # the marker does not belong to an inline
+
+            $unmarkedText = substr($text, 0, $markerPosition + 1);
+
+            $markup .= $this->unmarkedText($unmarkedText);
+
+            $text = substr($text, $markerPosition + 1);
+        }
+
+        $markup .= $this->unmarkedText($text);
+
+        return $markup;
+    }
+
+    #
+    # ~
+    #
+
+    protected function inlineCode($Excerpt)
+    {
+        $marker = $Excerpt['text'][0];
+
+        if (preg_match('/^('.$marker.'+)[ ]*(.+?)[ ]*(?<!'.$marker.')\1(?!'.$marker.')/s', $Excerpt['text'], $matches))
+        {
+            $text = $matches[2];
+            $text = preg_replace("/[ ]*\n/", ' ', $text);
+
+            return array(
+                'extent' => strlen($matches[0]),
+                'element' => array(
+                    'name' => 'code',
+                    'text' => $text,
+                ),
+            );
+        }
+    }
+
+    protected function inlineEmailTag($Excerpt)
+    {
+        if (strpos($Excerpt['text'], '>') !== false and preg_match('/^<((mailto:)?\S+?@\S+?)>/i', $Excerpt['text'], $matches))
+        {
+            $url = $matches[1];
+
+            if ( ! isset($matches[2]))
+            {
+                $url = 'mailto:' . $url;
+            }
+
+            return array(
+                'extent' => strlen($matches[0]),
+                'element' => array(
+                    'name' => 'a',
+                    'text' => $matches[1],
+                    'attributes' => array(
+                        'href' => $url,
+                    ),
+                ),
+            );
+        }
+    }
+
+    protected function inlineEmphasis($Excerpt)
+    {
+        if ( ! isset($Excerpt['text'][1]))
+        {
+            return;
+        }
+
+        $marker = $Excerpt['text'][0];
+
+        if ($Excerpt['text'][1] === $marker and preg_match($this->StrongRegex[$marker], $Excerpt['text'], $matches))
+        {
+            $emphasis = 'strong';
+        }
+        elseif (preg_match($this->EmRegex[$marker], $Excerpt['text'], $matches))
+        {
+            $emphasis = 'em';
+        }
+        else
+        {
+            return;
+        }
+
+        return array(
+            'extent' => strlen($matches[0]),
+            'element' => array(
+                'name' => $emphasis,
+                'handler' => 'line',
+                'text' => $matches[1],
+            ),
+        );
+    }
+
+    protected function inlineEscapeSequence($Excerpt)
+    {
+        if (isset($Excerpt['text'][1]) and in_array($Excerpt['text'][1], $this->specialCharacters))
+        {
+            return array(
+                'markup' => $Excerpt['text'][1],
+                'extent' => 2,
+            );
+        }
+    }
+
+    protected function inlineImage($Excerpt)
+    {
+        if ( ! isset($Excerpt['text'][1]) or $Excerpt['text'][1] !== '[')
+        {
+            return;
+        }
+
+        $Excerpt['text']= substr($Excerpt['text'], 1);
+
+        $Link = $this->inlineLink($Excerpt);
+
+        if ($Link === null)
+        {
+            return;
+        }
+
+        $Inline = array(
+            'extent' => $Link['extent'] + 1,
+            'element' => array(
+                'name' => 'img',
+                'attributes' => array(
+                    'src' => $Link['element']['attributes']['href'],
+                    'alt' => $Link['element']['text'],
+                ),
+            ),
+        );
+
+        $Inline['element']['attributes'] += $Link['element']['attributes'];
+
+        unset($Inline['element']['attributes']['href']);
+
+        return $Inline;
+    }
+
+    protected function inlineLink($Excerpt)
+    {
+        $Element = array(
+            'name' => 'a',
+            'handler' => 'line',
+            'nonNestables' => array('Url', 'Link'),
+            'text' => null,
+            'attributes' => array(
+                'href' => null,
+                'title' => null,
+            ),
+        );
+
+        $extent = 0;
+
+        $remainder = $Excerpt['text'];
+
+        if (preg_match('/\[((?:[^][]++|(?R))*+)\]/', $remainder, $matches))
+        {
+            $Element['text'] = $matches[1];
+
+            $extent += strlen($matches[0]);
+
+            $remainder = substr($remainder, $extent);
+        }
+        else
+        {
+            return;
+        }
+
+        if (preg_match('/^[(]\s*+((?:[^ ()]++|[(][^ )]+[)])++)(?:[ ]+("[^"]*"|\'[^\']*\'))?\s*[)]/', $remainder, $matches))
+        {
+            $Element['attributes']['href'] = $matches[1];
+
+            if (isset($matches[2]))
+            {
+                $Element['attributes']['title'] = substr($matches[2], 1, - 1);
+            }
+
+            $extent += strlen($matches[0]);
+        }
+        else
+        {
+            if (preg_match('/^\s*\[(.*?)\]/', $remainder, $matches))
+            {
+                $definition = strlen($matches[1]) ? $matches[1] : $Element['text'];
+                $definition = strtolower($definition);
+
+                $extent += strlen($matches[0]);
+            }
+            else
+            {
+                $definition = strtolower($Element['text']);
+            }
+
+            if ( ! isset($this->DefinitionData['Reference'][$definition]))
+            {
+                return;
+            }
+
+            $Definition = $this->DefinitionData['Reference'][$definition];
+
+            $Element['attributes']['href'] = $Definition['url'];
+            $Element['attributes']['title'] = $Definition['title'];
+        }
+
+        return array(
+            'extent' => $extent,
+            'element' => $Element,
+        );
+    }
+
+    protected function inlineMarkup($Excerpt)
+    {
+        if ($this->markupEscaped or $this->safeMode or strpos($Excerpt['text'], '>') === false)
+        {
+            return;
+        }
+
+        if ($Excerpt['text'][1] === '/' and preg_match('/^<\/\w[\w-]*[ ]*>/s', $Excerpt['text'], $matches))
+        {
+            return array(
+                'markup' => $matches[0],
+                'extent' => strlen($matches[0]),
+            );
+        }
+
+        if ($Excerpt['text'][1] === '!' and preg_match('/^<!---?[^>-](?:-?[^-])*-->/s', $Excerpt['text'], $matches))
+        {
+            return array(
+                'markup' => $matches[0],
+                'extent' => strlen($matches[0]),
+            );
+        }
+
+        if ($Excerpt['text'][1] !== ' ' and preg_match('/^<\w[\w-]*(?:[ ]*'.$this->regexHtmlAttribute.')*[ ]*\/?>/s', $Excerpt['text'], $matches))
+        {
+            return array(
+                'markup' => $matches[0],
+                'extent' => strlen($matches[0]),
+            );
+        }
+    }
+
+    protected function inlineSpecialCharacter($Excerpt)
+    {
+        if ($Excerpt['text'][0] === '&' and ! preg_match('/^&#?\w+;/', $Excerpt['text']))
+        {
+            return array(
+                'markup' => '&amp;',
+                'extent' => 1,
+            );
+        }
+
+        $SpecialCharacter = array('>' => 'gt', '<' => 'lt', '"' => 'quot');
+
+        if (isset($SpecialCharacter[$Excerpt['text'][0]]))
+        {
+            return array(
+                'markup' => '&'.$SpecialCharacter[$Excerpt['text'][0]].';',
+                'extent' => 1,
+            );
+        }
+    }
+
+    protected function inlineStrikethrough($Excerpt)
+    {
+        if ( ! isset($Excerpt['text'][1]))
+        {
+            return;
+        }
+
+        if ($Excerpt['text'][1] === '~' and preg_match('/^~~(?=\S)(.+?)(?<=\S)~~/', $Excerpt['text'], $matches))
+        {
+            return array(
+                'extent' => strlen($matches[0]),
+                'element' => array(
+                    'name' => 'del',
+                    'text' => $matches[1],
+                    'handler' => 'line',
+                ),
+            );
+        }
+    }
+
+    protected function inlineUrl($Excerpt)
+    {
+        if ($this->urlsLinked !== true or ! isset($Excerpt['text'][2]) or $Excerpt['text'][2] !== '/')
+        {
+            return;
+        }
+
+        if (preg_match('/\bhttps?:[\/]{2}[^\s<]+\b\/*/ui', $Excerpt['context'], $matches, PREG_OFFSET_CAPTURE))
+        {
+            $url = $matches[0][0];
+
+            $Inline = array(
+                'extent' => strlen($matches[0][0]),
+                'position' => $matches[0][1],
+                'element' => array(
+                    'name' => 'a',
+                    'text' => $url,
+                    'attributes' => array(
+                        'href' => $url,
+                    ),
+                ),
+            );
+
+            return $Inline;
+        }
+    }
+
+    protected function inlineUrlTag($Excerpt)
+    {
+        if (strpos($Excerpt['text'], '>') !== false and preg_match('/^<(\w+:\/{2}[^ >]+)>/i', $Excerpt['text'], $matches))
+        {
+            $url = $matches[1];
+
+            return array(
+                'extent' => strlen($matches[0]),
+                'element' => array(
+                    'name' => 'a',
+                    'text' => $url,
+                    'attributes' => array(
+                        'href' => $url,
+                    ),
+                ),
+            );
+        }
+    }
+
+    # ~
+
+    protected function unmarkedText($text)
+    {
+        if ($this->breaksEnabled)
+        {
+            $text = preg_replace('/[ ]*\n/', "<br />\n", $text);
+        }
+        else
+        {
+            $text = preg_replace('/(?:[ ][ ]+|[ ]*\\\\)\n/', "<br />\n", $text);
+            $text = str_replace(" \n", "\n", $text);
+        }
+
+        return $text;
+    }
+
+    #
+    # Handlers
+    #
+
+    protected function element(array $Element)
+    {
+        if ($this->safeMode)
+        {
+            $Element = $this->sanitiseElement($Element);
+        }
+
+        $markup = '<'.$Element['name'];
+
+        if (isset($Element['attributes']))
+        {
+            foreach ($Element['attributes'] as $name => $value)
+            {
+                if ($value === null)
+                {
+                    continue;
+                }
+
+                $markup .= ' '.$name.'="'.self::escape($value).'"';
+            }
+        }
+
+        $permitRawHtml = false;
+
+        if (isset($Element['text']))
+        {
+            $text = $Element['text'];
+        }
+        // very strongly consider an alternative if you're writing an
+        // extension
+        elseif (isset($Element['rawHtml']))
+        {
+            $text = $Element['rawHtml'];
+            $allowRawHtmlInSafeMode = isset($Element['allowRawHtmlInSafeMode']) && $Element['allowRawHtmlInSafeMode'];
+            $permitRawHtml = !$this->safeMode || $allowRawHtmlInSafeMode;
+        }
+
+        if (isset($text))
+        {
+            $markup .= '>';
+
+            if (!isset($Element['nonNestables']))
+            {
+                $Element['nonNestables'] = array();
+            }
+
+            if (isset($Element['handler']))
+            {
+                $markup .= $this->{$Element['handler']}($text, $Element['nonNestables']);
+            }
+            elseif (!$permitRawHtml)
+            {
+                $markup .= self::escape($text, true);
+            }
+            else
+            {
+                $markup .= $text;
+            }
+
+            $markup .= '</'.$Element['name'].'>';
+        }
+        else
+        {
+            $markup .= ' />';
+        }
+
+        return $markup;
+    }
+
+    protected function elements(array $Elements)
+    {
+        $markup = '';
+
+        foreach ($Elements as $Element)
+        {
+            $markup .= "\n" . $this->element($Element);
+        }
+
+        $markup .= "\n";
+
+        return $markup;
+    }
+
+    # ~
+
+    protected function li($lines)
+    {
+        $markup = $this->lines($lines);
+
+        $trimmedMarkup = trim($markup);
+
+        if ( ! in_array('', $lines) and substr($trimmedMarkup, 0, 3) === '<p>')
+        {
+            $markup = $trimmedMarkup;
+            $markup = substr($markup, 3);
+
+            $position = strpos($markup, "</p>");
+
+            $markup = substr_replace($markup, '', $position, 4);
+        }
+
+        return $markup;
+    }
+
+    #
+    # Deprecated Methods
+    #
+
+    function parse($text)
+    {
+        $markup = $this->text($text);
+
+        return $markup;
+    }
+
+    protected function sanitiseElement(array $Element)
+    {
+        static $goodAttribute = '/^[a-zA-Z0-9][a-zA-Z0-9-_]*+$/';
+        static $safeUrlNameToAtt  = array(
+            'a'   => 'href',
+            'img' => 'src',
+        );
+
+        if (isset($safeUrlNameToAtt[$Element['name']]))
+        {
+            $Element = $this->filterUnsafeUrlInAttribute($Element, $safeUrlNameToAtt[$Element['name']]);
+        }
+
+        if ( ! empty($Element['attributes']))
+        {
+            foreach ($Element['attributes'] as $att => $val)
+            {
+                # filter out badly parsed attribute
+                if ( ! preg_match($goodAttribute, $att))
+                {
+                    unset($Element['attributes'][$att]);
+                }
+                # dump onevent attribute
+                elseif (self::striAtStart($att, 'on'))
+                {
+                    unset($Element['attributes'][$att]);
+                }
+            }
+        }
+
+        return $Element;
+    }
+
+    protected function filterUnsafeUrlInAttribute(array $Element, $attribute)
+    {
+        foreach ($this->safeLinksWhitelist as $scheme)
+        {
+            if (self::striAtStart($Element['attributes'][$attribute], $scheme))
+            {
+                return $Element;
+            }
+        }
+
+        $Element['attributes'][$attribute] = str_replace(':', '%3A', $Element['attributes'][$attribute]);
+
+        return $Element;
+    }
+
+    #
+    # Static Methods
+    #
+
+    protected static function escape($text, $allowQuotes = false)
+    {
+        return htmlspecialchars($text, $allowQuotes ? ENT_NOQUOTES : ENT_QUOTES, 'UTF-8');
+    }
+
+    protected static function striAtStart($string, $needle)
+    {
+        $len = strlen($needle);
+
+        if ($len > strlen($string))
+        {
+            return false;
+        }
+        else
+        {
+            return strtolower(substr($string, 0, $len)) === strtolower($needle);
+        }
+    }
+
+    static function instance($name = 'default')
+    {
+        if (isset(self::$instances[$name]))
+        {
+            return self::$instances[$name];
+        }
+
+        $instance = new static();
+
+        self::$instances[$name] = $instance;
+
+        return $instance;
+    }
+
+    private static $instances = array();
+
+    #
+    # Fields
+    #
+
+    protected $DefinitionData;
+
+    #
+    # Read-Only
+
+    protected $specialCharacters = array(
+        '\\', '`', '*', '_', '{', '}', '[', ']', '(', ')', '>', '#', '+', '-', '.', '!', '|',
+    );
+
+    protected $StrongRegex = array(
+        '*' => '/^[*]{2}((?:\\\\\*|[^*]|[*][^*]*[*])+?)[*]{2}(?![*])/s',
+        '_' => '/^__((?:\\\\_|[^_]|_[^_]*_)+?)__(?!_)/us',
+    );
+
+    protected $EmRegex = array(
+        '*' => '/^[*]((?:\\\\\*|[^*]|[*][*][^*]+?[*][*])+?)[*](?![*])/s',
+        '_' => '/^_((?:\\\\_|[^_]|__[^_]*__)+?)_(?!_)\b/us',
+    );
+
+    protected $regexHtmlAttribute = '[a-zA-Z_:][\w:.-]*(?:\s*=\s*(?:[^"\'=<>`\s]+|"[^"]*"|\'[^\']*\'))?';
+
+    protected $voidElements = array(
+        'area', 'base', 'br', 'col', 'command', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source',
+    );
+
+    protected $textLevelElements = array(
+        'a', 'br', 'bdo', 'abbr', 'blink', 'nextid', 'acronym', 'basefont',
+        'b', 'em', 'big', 'cite', 'small', 'spacer', 'listing',
+        'i', 'rp', 'del', 'code',          'strike', 'marquee',
+        'q', 'rt', 'ins', 'font',          'strong',
+        's', 'tt', 'kbd', 'mark',
+        'u', 'xm', 'sub', 'nobr',
+                   'sup', 'ruby',
+                   'var', 'span',
+                   'wbr', 'time',
+    );
+}