Pre-stage mu-plugin for spec_root override; ONBOARDING references file not snippet

Adds:
mu-plugins/sa-orch-spec-root.php (1.7 KB) — auto-loaded WP filter that
redirects SA-Orchestration's
spec_root() to wp-content/sa-asterion/.

ONBOARDING.md updated to copy the pre-staged file rather than author it from
an embedded snippet. Same v2 pattern as asterion/ + sa-orchestration/ +
SA-orchestration MD/.

Why: the SA-Orch plugin hardcodes a default spec_root path that only exists
on the source-author's machine (F:/SleeperAgents/SA-orchestration/Archvie/...).
Every other WP install — WPE dev root, leaf installs — needs this mu-plugin
to redirect spec_root, otherwise Asterion queries return 'no canonical
reference found in the spec corpus (corpus root unreachable)'. Discovered
during WPE deploy verification on 2026-05-06.

Source-of-truth file: F:\SleeperAgents\SA-orchestration\mu-plugins\sa-orch-spec-root.php
(committed at aa78b71). Copies in seeded repos are byte-identical.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ONBOARDING.md

@@ -167,30 +167,21 @@ The SA-Orchestration plugin reads its canonical content from a filterable path.
 
 Two valid placements:
 
-**A. Mirror corpus into WP content** (recommended):
+**Locked approach: mirror corpus + install pre-staged mu-plugin.**
 
 ```
+# (a) Mirror the canonical corpus into the WP install
 mkdir -p <wp-install>/wp-content/sa-asterion
 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`. 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 () {
-    // 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 );
+# (b) Install the pre-staged mu-plugin (already in this repo at <repo-root>/mu-plugins/sa-orch-spec-root.php)
+mkdir -p <wp-install>/wp-content/mu-plugins
+cp <this-repo>/mu-plugins/sa-orch-spec-root.php <wp-install>/wp-content/mu-plugins/sa-orch-spec-root.php
 ```
 
-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.
+The pre-staged mu-plugin points the `sa_orch_asterion_spec_root` filter at `WP_CONTENT_DIR . '/sa-asterion'`. **Do not author it from a snippet** — the file exists at `<repo-root>/mu-plugins/sa-orch-spec-root.php`. If missing, the seed is corrupt — surface to the human.
 
-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.**
+Earlier seed versions described a "Path B" pointing the filter at the repo's `asterion/` directly without mirroring. That fails on container-based stacks (DDEV) where the container only mounts `public_html/`. The mirror approach above works on every stack.
 
 **Verify**: filesystem readable by the web user; `01-ontology.md` and `02-invariants.md` exist at the chosen location.
 

mu-plugins/sa-orch-spec-root.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * SA-Orchestration — Asterion spec_root override
+ *
+ * Type:        mu-plugin (must-use plugin) — auto-loaded by WordPress;
+ *              no activation needed; survives plugin deactivation.
+ *
+ * Purpose:     Point the SA-Orchestration Asterion canonical corpus root at
+ *              the deployed `wp-content/sa-asterion/` directory.
+ *
+ * Why it exists: The SA-Orchestration plugin's `SA_Orch_Asterion_Explorer::DEFAULT_SPEC_ROOT`
+ *              is hardcoded to a path that exists on the source-author's machine
+ *              (`F:/SleeperAgents/SA-orchestration/Archvie/sa-core/docs/specs`).
+ *              On every other WordPress install — WPE, client deployments, leaf
+ *              installs — that path doesn't exist. Without this filter, every
+ *              Asterion query returns
+ *              "no canonical reference found in the spec corpus (corpus root unreachable)".
+ *
+ * Deploy path: Copy this file to `<wp-install>/wp-content/mu-plugins/sa-orch-spec-root.php`.
+ *              No `mu-plugins/` directory? Create it. WordPress auto-discovers it.
+ *
+ * Companion:   The Asterion corpus directory itself must exist at
+ *              `<wp-install>/wp-content/sa-asterion/` and contain the canonical
+ *              spec files (`01-ontology.md`, `02-invariants.md`, `concepts/`, etc.).
+ *              Source of those files: `F:\SleeperAgents\SA-orchestration\asterion\`
+ *              (committed at v1.1, commit 848ee70).
+ *
+ * One file per WP install. Idempotent. No DB writes. No state.
+ */
+
+defined( 'ABSPATH' ) || exit;
+
+add_filter( 'sa_orch_asterion_spec_root', function () {
+    return WP_CONTENT_DIR . '/sa-asterion';
+}, 5 );