pi-mega-compact 0.20.62 → 0.20.64

package/extensions/dashboard-client/src/App.tsx

@@ -176,13 +176,16 @@ function NewDashboard({
   snapshot,
   loading,
   error,
+  viewToggle,
 }: AppState & {
   activeTab: TabId;
   setActiveTab: (id: TabId) => void;
+  viewToggle?: React.ReactNode;
 }): React.ReactElement {
   return (
     <ErrorBoundary>
       <AppShell active={activeTab} onTabChange={setActiveTab} snapshot={snapshot}>
+        {viewToggle ? <div className="view-toggle-wrap">{viewToggle}</div> : null}
         <LegacyContent activeTab={activeTab} snapshot={snapshot} loading={loading} error={error} />
       </AppShell>
     </ErrorBoundary>
@@ -217,6 +220,11 @@ function ConsolidatedNav({
 
 export default function App(): React.ReactElement {
   const [activeTab, setActiveTab] = useState<ActiveTab>("overview");
+  // DASH-0d consolidated 7-surface view is OPT-IN. The default is the full
+  // NewDashboard layout (left Sidebar + mobile BottomBar, 13 tabs). A toggle
+  // button (rendered when the consolidated code is available) lets the operator
+  // switch to the minimal 7-surface view on demand.
+  const [consolidatedView, setConsolidatedView] = useState(false);
   const {
     data: snapshot,
     loading,
@@ -235,6 +243,7 @@ export default function App(): React.ReactElement {
     { pollInterval: 0, maxRetries: 0 },
   );
   const dash0dOn = dash0dEnabled(settingsData);
+  const canConsolidate = NEW_UI() && dash0dOn;
 
   // Additive hash→surface deep-link router: every legacy #hash maps to a live
   // consolidated surface; empty hash keeps current behavior (default overview).
@@ -242,12 +251,27 @@ export default function App(): React.ReactElement {
   // pre-rollup 13-tab behavior unchanged (hash ignored).
   const hashSurface = useHashTab();
   useEffect(() => {
-    if (dash0dOn && hashSurface != null) setActiveTab(hashSurface);
-  }, [dash0dOn, hashSurface]);
+    if (canConsolidate && consolidatedView && hashSurface != null)
+      setActiveTab(hashSurface);
+  }, [canConsolidate, consolidatedView, hashSurface]);
 
-  // Flag-ON consolidated New-UI surface: a 7-surface rail + the consolidated
-  // content. Flag-OFF (or legacy NEW_UI false) renders the 13-tab path as today.
-  if (NEW_UI() && dash0dOn) {
+  // The toggle button renders inside both view headers when the consolidated
+  // code is available. Default view = full (Sidebar+BottomBar); minimal = 7
+  // surfaces.
+  const ViewToggle = canConsolidate ? (
+    <button
+      type="button"
+      className="view-toggle-btn"
+      onClick={() => setConsolidatedView((v) => !v)}
+      aria-pressed={consolidatedView}
+      title={consolidatedView ? "Switch to full dashboard" : "Switch to minimal dashboard"}
+    >
+      {consolidatedView ? "Full view" : "Minimal view"}
+    </button>
+  ) : null;
+
+  // Consolidated 7-surface view — OPT-IN via the toggle button above.
+  if (canConsolidate && consolidatedView) {
     const current = DASH_SURFACE_IDS.includes(activeTab as DashTabId)
       ? (activeTab as DashTabId)
       : "overview";
@@ -256,6 +280,7 @@ export default function App(): React.ReactElement {
         <div className="dashboard-app">
           <header className="dashboard-header">
             <h1>mega-compact dashboard <span className="tier">{snapshot?.tier ?? "unknown"}</span></h1>
+            {ViewToggle}
           </header>
           <ConsolidatedNav active={current} onSelect={(id: DashTabId) => setActiveTab(id)} />
           <main className="dashboard-content">
@@ -271,8 +296,9 @@ export default function App(): React.ReactElement {
     );
   }
 
-  // Flag-off (or legacy NEW_UI): always a legacy TabId (hash routing is gated
-  // on dash0dOn above, so activeTab stays a 13-tab id here).
+  // Default view (full): always a legacy TabId (hash routing is gated on
+  // canConsolidate && consolidatedView above, so activeTab stays a 13-tab id
+  // here).
   const legacyTab = (activeTab as TabId) ?? "overview";
 
   if (NEW_UI()) {
@@ -283,6 +309,7 @@ export default function App(): React.ReactElement {
         snapshot={snapshot}
         loading={loading}
         error={error}
+        viewToggle={ViewToggle}
       />
     );
   }

package/extensions/dashboard-client/src/styles/base.css

@@ -43,10 +43,18 @@ body {
 	gap: clamp(8px, 1.5vw, 16px);
 }
 
+.dashboard-header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 8px;
+	flex-wrap: wrap;
+}
+
 .dashboard-header h1 {
 	font-size: clamp(16px, 1.4vw, 22px);
 	font-weight: 600;
-	margin: 0 0 clamp(8px, 1vw, 16px);
+	margin: 0;
 }
 
 .dashboard-header .tier,
@@ -65,6 +73,61 @@ body {
 	color: var(--accent);
 }
 
+/* View toggle button — switches between full (default) and minimal 7-surface */
+.view-toggle-btn {
+	background: var(--panel);
+	border: 1px solid var(--border);
+	color: var(--muted);
+	padding: 4px 12px;
+	font-size: clamp(11px, 0.8vw, 13px);
+	border-radius: 8px;
+	cursor: pointer;
+	white-space: nowrap;
+	transition: color 0.15s, border-color 0.15s;
+}
+.view-toggle-btn:hover {
+	color: var(--text);
+	border-color: var(--accent);
+}
+.view-toggle-btn[aria-pressed="true"] {
+	color: var(--accent);
+	border-color: var(--accent);
+}
+.view-toggle-wrap {
+	position: fixed;
+	top: 12px;
+	right: 16px;
+	z-index: 50;
+}
+
+/* Consolidated 7-surface nav — horizontal scrollable rail (mobile-friendly) */
+.consolidated-nav {
+	display: flex;
+	gap: 4px;
+	overflow-x: auto;
+	flex-wrap: nowrap;
+	border-bottom: 1px solid var(--border);
+	margin-bottom: clamp(8px, 1vw, 16px);
+	padding-bottom: 2px;
+}
+.consolidated-nav button {
+	background: none;
+	border: none;
+	color: var(--muted);
+	padding: 8px 14px;
+	cursor: pointer;
+	font-size: clamp(12px, 0.85vw, 14px);
+	white-space: nowrap;
+	border-bottom: 2px solid transparent;
+}
+.consolidated-nav button.active {
+	color: var(--text);
+	border-bottom-color: var(--accent);
+}
+.consolidated-nav button:hover {
+	color: var(--text);
+}
+
 .tab-bar {
 	display: flex;
 	gap: 4px;

package/extensions/dashboard-client/src/tabs/SetupTab/CortexRuntimeInstallCard.tsx

@@ -0,0 +1,103 @@
+/**
+ * SetupTab/CortexRuntimeInstallCard.tsx — operator-run install guide card
+ * (ENC-2a).
+ *
+ * Pure render. When `SetupStatusResponse.nativeOrtInstallGuide` is non-null
+ * (opt-in on, effective runtime still wasm, platform installable), this card
+ * surfaces the three copy-paste steps the operator runs OUTSIDE the dashboard:
+ * install onnxruntime-node, restart via pi, and the expected next status. When
+ * the guide is null the card hides entirely (the modifiers card already
+ * surfaces the honest ENC-0g state).
+ *
+ * NO client-side execution — the install script is never spawned from here.
+ * Data comes exclusively from the existing /api/setup-status poll.
+ */
+import type React from "react";
+import { useState, useCallback, useEffect } from "react";
+import type { SetupStatusResponse } from "@contracts";
+import { fetchSetupStatus } from "../../api/client";
+import { styles } from "./CortexSetupStyles";
+
+function useCopyState(): [boolean, (text: string) => Promise<void>] {
+	const [copied, setCopied] = useState(false);
+	const copy = useCallback(async (text: string) => {
+		try {
+			await navigator.clipboard.writeText(text);
+			setCopied(true);
+			window.setTimeout(() => setCopied(false), 1500);
+		} catch {
+			setCopied(false);
+		}
+	}, []);
+	return [copied, copy];
+}
+
+export default function CortexRuntimeInstallCard(): React.ReactElement {
+	const [status, setStatus] = useState<SetupStatusResponse | null>(null);
+	const [copied, copy] = useCopyState();
+
+	const loadStatus = useCallback(() => {
+		fetchSetupStatus()
+			.then(setStatus)
+			.catch(() => {
+				/* best-effort poll; hide card when unavailable */
+			});
+	}, []);
+
+	useEffect(() => {
+		loadStatus();
+		const id = setInterval(loadStatus, 5000);
+		return () => clearInterval(id);
+	}, [loadStatus]);
+
+	const guide = status?.nativeOrtInstallGuide ?? null;
+	const installedVersion = status?.nativeOrtInstalledVersion ?? null;
+	if (!guide) return <></>;
+
+	return (
+		<div style={styles.section}>
+			<h3 style={styles.sectionTitle}>Encoder Runtime Install</h3>
+			<p style={{ ...styles.label, fontSize: "0.85rem", marginBottom: "0.75rem" }}>
+				Platform: {guide.platform}
+			</p>
+			{installedVersion !== null && (
+				<div style={styles.row}>
+					<span style={styles.label}>Detected:</span>
+					<span style={styles.value}>{installedVersion}</span>
+				</div>
+			)}
+			{guide.commands.map((command, i) => (
+				<div key={`${i}-${command}`} style={styles.row}>
+					<span style={styles.label}>Step {i + 1}:</span>
+					<code
+						style={{
+							...styles.mono,
+							display: "inline-block",
+							marginTop: "0.15rem",
+						}}
+					>
+						{command}
+					</code>
+					<button
+						type="button"
+						onClick={() => {
+							void copy(command);
+						}}
+						style={{ marginLeft: "0.5rem", fontSize: "0.8rem" }}
+					>
+						Copy
+					</button>
+				</div>
+			))}
+			<p style={{ ...styles.row, fontSize: "0.85rem" }}>
+				<span style={styles.label}>Script:</span>{" "}
+				<code style={styles.mono}>{guide.scriptPath}</code>
+			</p>
+			{copied && (
+				<p style={{ color: "#4caf50", fontSize: "0.8rem", margin: "0.25rem 0 0" }}>
+					Copied to clipboard
+				</p>
+			)}
+		</div>
+	);
+}

package/extensions/dashboard-client/src/tabs/SetupTab/CortexSetup.tsx

@@ -15,6 +15,7 @@ import { CortexEncoderCard } from "./CortexEncoderCard";
 import { CortexBlockersCard } from "./CortexBlockersCard";
 import { CortexActionsCard } from "./CortexActionsCard";
 import CortexRuntimeCard from "./CortexRuntimeCard";
+import CortexRuntimeInstallCard from "./CortexRuntimeInstallCard";
 import { VectorCortexCosineFpCard } from "./VectorCortexCosineFpCard";
 import { VectorCortexRepoCorpusCard } from "./VectorCortexRepoCorpusCard";
 import { styles } from "./CortexSetupStyles";
@@ -43,6 +44,7 @@ export default function CortexSetup(): React.ReactElement {
 
 			<CortexEncoderCard data={state.data} error={state.error} />
 			<CortexRuntimeCard />
+			<CortexRuntimeInstallCard />
 			<VectorCortexCosineFpCard />
 			<VectorCortexRepoCorpusCard />
 			<CortexBlockersCard

package/extensions/dashboard-server/api-contracts/setup.ts

@@ -64,6 +64,25 @@ export interface SetupStatusResponse {
    *  operand — persists even when `nativeOrtBudgetMib` is absent because the
    *  runtime applies the default when unset. Additive, flag-gated. */
   readonly nativeOrtBudgetEffectiveMib?: string;
+  /** ENC-2a: the native onnxruntime install-guide, present (as an object) when
+   *  the operator opted into the native backend AND the effective runtime is
+   *  still wasm (onnxruntime-node absent) AND the host platform is installable.
+   *  `null` when opt-in is off or the platform is unsupported/demoted (the guide
+   *  never renders). Built ONLY from the artifacts module constants — no inline
+   *  URLs or hashes in the route. Additive, flag-gated; absent = no guide. */
+  readonly nativeOrtInstallGuide?: {
+    /** The host's EncoderPlatform this guide is matched to. */
+    readonly platform: string;
+    /** The [install, restart, verify] copy-paste commands. */
+    readonly commands: readonly string[];
+    /** The committed operator script path (repo-rel). */
+    readonly scriptPath: string;
+  } | null;
+  /** ENC-2a: the installed native onnxruntime version read from
+   *  `~/.pi/mega-compact/native-ort/` when the probe marker/package is present
+   *  and platform-matched. Absent (NOT null) when not installed, so the client
+   *  hides the detected-version row. Additive, flag-gated, reader-only. */
+  readonly nativeOrtInstalledVersion?: string | null;
 }
 
 /**
@@ -132,6 +151,11 @@ export interface SetupConfigureRequest {
    *  positive integer string within `ENC_2BUDGET_MAX_MIB` (validated; additive,
    *  flag-gated). */
   readonly nativeOrtBudgetMib?: string;
+  /** ENC-2a: an optional { boolean } guide-request key. `true` → 200 + the
+   *  guide echoed (this sprint conveys the GUIDE only — no server-side
+   *  execution); `false` → 400 `guide_rejected_false_nothing_to_do`.
+   *  Flag-gated, additive — ignored (no-op) when the flag is off. */
+  readonly nativeOrtInstallGuide?: boolean;
 }
 
 /** Response for POST /api/setup-configure. */

package/extensions/dashboard-server/routes-rag-settings-vector-cortex.ts

@@ -314,6 +314,12 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"ENC-2a exposes the runtime operator knob MEGACOMPACT_NATIVE_ORT_BUDGET_MIB (default 300 MiB, clamp 8192) as a dashboard Settings field. The knob gates budgetOk in the encoder runtime decision (decision.ts installBudgetMib + runtime-select.ts selectRuntimeBackend). Persisted to the per-repo .mega-compact.env via the setup-configure writer branch; the GET status route surfaces the persisted value AND the effective integer installBudgetMib() resolves to (so the dashboard shows the runtime's actual operand). OFF = no new GET fields, no writer branch, no new Settings rows (byte-identical ENC-1b predecessor).",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_ENC_2A",
+			"ENC-2a native onnxruntime install GUIDE (detect + copy-paste)",
+			"ENC-2a surfaces the platform-matched native onnxruntime install-guide (three copy-paste steps + script path) on the Setup Cortex sub-tab when the operator opted into the native backend but the effective runtime is still wasm (onnxruntime-node absent). Pure guidance — the extension NEVER executes or fetches (PREVENT-PI-004 unchanged); the committed operator script scripts/encoder/install-native-ort.mjs runs in the USER's shell. OFF = no guide GET fields, no guide-request POST branch, no install card (byte-identical ENC-1b predecessor).",
+			true,
+		),
 		boolDirect(
 			"MEGACOMPACT_COSINE_FP_BENCH",
 			"COS-FP-A Synthetic FP Bench",

package/extensions/dashboard-server/routes-setup-enc2a.ts

@@ -0,0 +1,140 @@
+/**
+ * dashboard-server/routes-setup-enc2a.ts — ENC-2a native onnxruntime install
+ * GUIDE (reader-only) + installed-version probe.
+ *
+ * Extracted out of routes-setup.ts (which hovers at the 300-line source soft
+ * cap, mirroring the ENC-1a/ENC-1b/ENC-2budget sibling extracts) so the
+ * ENC-2a additive GET fields — the platform-matched native install guide and
+ * the installed-version probe — live in a sibling impl file and routes-setup.ts
+ * stays a thin host.
+ *
+ * The guide's job is OPERATOR run-script assist: when the operator opted into
+ * the native backend (`MEGACOMPACT_ENCODER_NATIVE=1`) but the effective runtime
+ * is still `"wasm"` (onnxruntime-node not yet installed) AND the host platform
+ * is installable, the GET status response carries a `nativeOrtInstallGuide`
+ * object with the [install, restart, verify] copy-paste commands + the committed
+ * operator script path. The commands/URL/hash are built ONLY from the artifacts
+ * module constants (`src/vector-cortex/encoder/native-install-artifacts.ts`) —
+ * never an inline registry URL or literal hash (PREVENT-PI-004). The installed-
+ * version probe reads the local `~/.pi/mega-compact/native-ort/` package.json
+ * when present (reader-only filesystem read, zero network).
+ *
+ * The flag is off (or opt-in off / unsupported platform / non-wasm backend) ->
+ * guide `null` and installedVersion `null` -> the host omits both fields,
+ * byte-identical to the ENC-1b-era shape.
+ *
+ * Guardrails: PREVENT-PI-004 (local filesystem reads + in-memory backend
+ * selection only, zero network), PREVENT-001 (null-safe JSON), PREVENT-011
+ * (no `any`).
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { ENC_2A_ENABLED } from "../../src/config/vector-cortex.js";
+import { readEnc1bEnv } from "./routes-setup-enc1b.js";
+import { selectRuntimeBackend } from "../../src/vector-cortex/encoder/runtime-select.js";
+import { detectPlatform } from "../../src/vector-cortex/encoder/asset.js";
+import {
+  NATIVE_ORT_VERSION,
+  NATIVE_ORT_PACKAGE,
+  NATIVE_ORT_INSTALLABLE_PLATFORMS,
+} from "../../src/vector-cortex/encoder/native-install-artifacts.js";
+import type { SetupConfigureRequest } from "./api-contracts/setup.js";
+
+/** The committed operator script that performs the install (repo-relative). */
+const ENC_2A_SCRIPT_PATH = "scripts/encoder/install-native-ort.mjs";
+
+/** Where the operator script installs the native binding (absolute install
+ *  prefix used verbatim in the guide commands + the version probe). */
+function nativeOrtDir(): string {
+  return join(process.env.HOME ?? "", ".pi", "mega-compact", "native-ort");
+}
+
+/**
+ * True when the payload carries the ENC-2a guide-request key `false`/`true`
+ * (flag-gated, additive). `false` -> 400 (operator-driven no-op); `true` -> 200
+ * + the guide echoed (still no server execution — the execute path is ENC-2c).
+ * Flag-off -> null so the key falls through unrecognized (byte-identical
+ * ENC-1b-era predecessor).
+ */
+export function enc2aGuideRequest(
+  body: SetupConfigureRequest,
+): { status: 400 } | { status: 200 } | null {
+  if (!ENC_2A_ENABLED()) return null;
+  if (body.nativeOrtInstallGuide === true) return { status: 200 };
+  if (body.nativeOrtInstallGuide === false) return { status: 400 };
+  return null;
+}
+
+/**
+ * Read the ENC-2a native install GUIDE + installed-version, additive GET fields.
+ *
+ * The guide renders only when EVERY gate passes: flag on, operator opted into
+ * native, effective backend is still `"wasm"` (onnxruntime-node absent), and the
+ * host platform is installable (darwin-x64 is excluded — no native binding
+ * upstream, the ENC-0e demotion sentinel). The effective backend + demotion
+ * reason go through the EXISTING `selectRuntimeBackend` (reader-only — never a
+ * reimplemented literal). `installedVersion` probes
+ * `~/.pi/mega-compact/native-ort/node_modules/onnxruntime-node/package.json`
+ * when present; null otherwise. Returns `{ guide: null, installedVersion: null }`
+ * when the flag is off (byte-identical predecessor).
+ */
+export function readEnc2aGuide(stateDir: string): {
+  guide: { platform: string; commands: readonly string[]; scriptPath: string } | null;
+  installedVersion: string | null;
+} {
+  if (!ENC_2A_ENABLED()) return { guide: null, installedVersion: null };
+  const env = readEnc1bEnv(stateDir);
+  const platform = detectPlatform();
+  const chosen = selectRuntimeBackend({
+    platform: platform ?? "unsupported",
+    benchRecord: null,
+    nativeOptIn: env.nativeOptIn,
+  });
+  const backend = chosen.backend === "native" ? "native" : "wasm";
+
+  let guide: { platform: string; commands: readonly string[]; scriptPath: string } | null = null;
+  if (
+    env.nativeOptIn &&
+    backend === "wasm" &&
+    platform !== null &&
+    (NATIVE_ORT_INSTALLABLE_PLATFORMS as readonly string[]).includes(platform)
+  ) {
+    guide = {
+      platform,
+      commands: [
+        `npm install --prefix ${nativeOrtDir()} ${NATIVE_ORT_PACKAGE}@${NATIVE_ORT_VERSION}`,
+        "pi update --extensions && pi session-start",
+        "expect encoderBackend: native on next status poll",
+      ],
+      scriptPath: ENC_2A_SCRIPT_PATH,
+    };
+  }
+
+  return { guide, installedVersion: probeInstalledVersion() };
+}
+
+/** Probe the local native-ort package.json for the installed onnxruntime-node
+ *  version. Null when the package is absent/unreadable (reader-only, local). */
+function probeInstalledVersion(): string | null {
+  try {
+    const pkgPath = join(
+      nativeOrtDir(),
+      "node_modules",
+      NATIVE_ORT_PACKAGE,
+      "package.json",
+    );
+    if (!existsSync(pkgPath)) return null;
+    const raw = JSON.parse(readFileSync(pkgPath, "utf8")) as unknown;
+    if (
+      typeof raw === "object" &&
+      raw !== null &&
+      typeof (raw as { version?: unknown }).version === "string"
+    ) {
+      return (raw as { version: string }).version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/extensions/dashboard-server/routes-setup.ts

@@ -21,6 +21,7 @@ import {
 	tryEnc2BudgetInto,
 	enc2BudgetValidateCombined,
 } from "./routes-setup-enc2budget.js";
+import { readEnc2aGuide, enc2aGuideRequest } from "./routes-setup-enc2a.js";
 import { writeEmbedderEnv } from "./routes-setup-env-upsert.js";
 import {
 	detectOllama,
@@ -85,6 +86,11 @@ export function handleSetupStatus(
 	}
 	const configured = detectConfiguredEmbedder(ctx.stateDir);
 	const active = detectCurrentEmbedder();
+	// ENC-2a (flag-gated, additive): the native install-guide + installed-version
+	// fields. Optional fields are added only when present/installable; when the
+	// flag is off readEnc2aGuide returns nulls so the body stays byte-identical
+	// to the ENC-1b-era shape.
+	const enc2a = readEnc2aGuide(ctx.stateDir);
 	// ENC-1a (flag-gated, additive): echo the persisted endpoint URL and an
 	// embeddingApiKeySet boolean ONLY — the raw API key is never returned. When
 	// the flag is off (or neither is set) both fields are simply omitted.
@@ -100,6 +106,8 @@ export function handleSetupStatus(
 		),
 		...enc1aStatusFields(ctx.stateDir), ...enc1bStatusFields(ctx.stateDir),
 		...enc2BudgetStatusFields(ctx.stateDir),
+		...(enc2a.guide !== null ? { nativeOrtInstallGuide: enc2a.guide } : {}),
+		...(enc2a.installedVersion !== null ? { nativeOrtInstalledVersion: enc2a.installedVersion } : {}),
 	};
 	// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
 	res.writeHead(200, { "Content-Type": "application/json" });
@@ -218,10 +226,28 @@ export function handleSetupConfigure(
 			return;
 		}
 		const body = parsed.value as unknown as SetupConfigureRequest;
+		// ENC-2a guide-request key (flag-gated, additive): `false` → 400 (an
+		// operator-driven no-op — this sprint conveys the GUIDE only, no server
+		// execution), `true` → 200 + the guide echoed (still no execution; the
+		// execute path is ENC-2c). Flag-off: enc2aGuideRequest returns null so the
+		// key falls through unrecognized (byte-identical ENC-1b-era predecessor).
+		const guideReq = enc2aGuideRequest(body);
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		if (guideReq !== null && guideReq.status === 400) {
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "guide_rejected_false_nothing_to_do" }));
+			return;
+		}
 		// ENC-1a (flag-gated, additive): a pure external-embedder configure
 		// (new keys, no embedder selection) is handled by the sibling writer.
 		// Flag-off = the keys are simply not recognized, falling through to the
 		// pre-ENC-1a embedder path below (byte-identical predecessor).
+		if (guideReq !== null && guideReq.status === 200) {
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ nativeOrtInstallGuide: readEnc2aGuide(ctx.stateDir).guide }));
+			return;
+		}
 		if (tryEnc1aConfigure(body, res, ctx)) return;
 		if (tryEnc1bConfigure(body, res, ctx)) return; // pure ENC-1b configure (dim/headers/allow-remote/native)
 		// ENC-1b combined-payload validation: when a payload carries a valid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.62",
+  "version": "0.20.64",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/vector-cortex-enc2a.ts

@@ -0,0 +1,37 @@
+/**
+ * config/vector-cortex-enc2a.ts — ENC-2a native onnxruntime install-guide flag
+ * (operator run-script assist).
+ *
+ * Sibling of vector-cortex-enc1a.ts / vector-cortex-enc1b.ts /
+ * vector-cortex-enc2budget.ts so vector-cortex.ts stays under the 300-line soft
+ * limit (soft-as-hard gate). vector-cortex.ts re-exports the flag below and
+ * root src/config.ts re-exports it, so no consumer import path changes.
+ *
+ * ENC-2a, when the operator opted into the native backend
+ * (`MEGACOMPACT_ENCODER_NATIVE=1`) but `encoderBackend` is still `"wasm"`
+ * (onnxruntime-node absent / not yet installed), surfaces an "Encoder Runtime
+ * Install" card on the Cortex sub-tab with copy-paste operator commands: the
+ * install + restart + verify steps built ONLY from the artifacts-module
+ * constants (`src/vector-cortex/encoder/native-install-artifacts.ts`) — never
+ * an inline registry URL or hash in the route (PREVENT-PI-004). The guide
+ * renders only on an installable host platform; the ENC-0e darwin-x64 demotion
+ * sentinel keeps it absent on an Intel Mac (no native binding upstream).
+ *
+ * `MEGACOMPACT_ENC_2A=0` disables: no guide fields, no install card, no absent
+ * read — byte-identical to the ENC-1b predecessor. The flag MUST also be a
+ * dashboard SETTINGS toggle (visible in config UI, never in EXCLUDED_SETTINGS
+ * — see `feedback_dashboard-flags-toggleable` memory).
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import { sprintFlag } from "./vector-cortex-flag.js";
+
+/**
+ * ENC-2a — operator run-script assist (dashboard install guide for the
+ * onnxruntime-node native binding). Default ON. `MEGACOMPACT_ENC_2A=0` disables
+ * and is byte-identical to the ENC-1b predecessor: no guide/absent fields, no
+ * install card. This flag MUST also be a dashboard SETTINGS toggle (visible in
+ * config UI, never in EXCLUDED_SETTINGS).
+ */
+export const ENC_2A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_ENC_2A");

package/src/config/vector-cortex.ts

@@ -92,6 +92,8 @@ export {
   ENC_2BUDGET_MAX_MIB,
   ENC_2BUDGET_DEFAULT_MIB,
 } from "./vector-cortex-enc2budget.js";
+// ENC-2a native onnxruntime install-guide flag extracted to vector-cortex-enc2a.ts.
+export { ENC_2A_ENABLED } from "./vector-cortex-enc2a.js";
 // Breaker constants (TRIAD_RESILIENCE.md §breaker) extracted to vector-cortex-breakers.ts.
 export {
   BREAKER_WINDOW_MS,

package/src/config.ts

@@ -202,6 +202,7 @@ export {
   ENC_2BUDGET_NATIVE_ORT_BUDGET_ENV,
   ENC_2BUDGET_MAX_MIB,
   ENC_2BUDGET_DEFAULT_MIB,
+  ENC_2A_ENABLED,
   COSINE_FP_BENCH_ENABLED,
   COSINE_FP_REAL_ENABLED,
   REPO_CORPUS_ENABLED,

package/src/vector-cortex/encoder/native-install-artifacts.ts

@@ -0,0 +1,60 @@
+/**
+ * vector-cortex/encoder/native-install-artifacts.ts — ENC-2a native
+ * onnxruntime install-guide constants (PURE data module).
+ *
+ * Single source of truth for the operator's native-backend install guide
+ * (`onnxruntime-node`, the sole onnxruntime Node.js binding this extension's
+ * native path uses). The guide rendered by
+ * `extensions/dashboard-server/routes-setup-enc2a.ts` and the operator script
+ * `scripts/encoder/install-native-ort.mjs` build their commands/URLs ONLY from
+ * these scalars — never an inline registry URL or literal hash in the route or
+ * extension runtime (PREVENT-PI-004: the registry tarball URL is derived by
+ * callers from `NATIVE_ORT_PACKAGE` + "@" + `NATIVE_ORT_VERSION`, so no network
+ * path and no literal registry URL or scheme appears in src/).
+ *
+ * Package facts (verified, not invented):
+ *  - onnxruntime-node publishes ONE monolithic ~100MB npm tarball — not
+ *    per-platform `optionalDependencies` — so a single
+ *    `NATIVE_ORT_TARBALL_SHA256` pins the whole artifact for every host.
+ *  - darwin-x64 has NO native binding (arm64-only upstream since 1.17), so the
+ *    guide stays absent on an Intel Mac (the ENC-0e demotion sentinel).
+ *  - `NATIVE_ORT_TARBALL_SHA256` was computed from TWO independent downloads of
+ *    the 1.27.0 tarball (real, cross-checked, not guessed).
+ *
+ * Pi-agnostic, dependency-free, pure data — zero I/O, zero network
+ * (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/** onnxruntime-node version the guide installs (real published version). */
+export const NATIVE_ORT_VERSION: string = "1.27.0";
+
+/** onnxruntime-node npm package name (the native onnxruntime binding). */
+export const NATIVE_ORT_PACKAGE: string = "onnxruntime-node";
+
+/** SHA-256 of the onnxruntime-node@1.27.0 npm tarball (one sha for all hosts).
+ *  Computed from TWO independent tarball downloads; lowercase hex, 64 chars. */
+export const NATIVE_ORT_TARBALL_SHA256: string =
+  "c3779c01c59832f8c03e2c392ac3af10bf08579f1822e8b1c63cc451edb302a2";
+
+/**
+ * The host platform the guide can render for. darwin-x64 is deliberately NOT
+ * installable (no native onnxruntime binding upstream — arm64-only since 1.17);
+ * the guide stays absent on an Intel Mac (ENC-0e demotion sentinel).
+ */
+export type EncoderPlatform =
+  | "linux-x64"
+  | "linux-arm64"
+  | "darwin-arm64"
+  | "win32-x64"
+  | "darwin-x64";
+
+/**
+ * Platforms for which an operator install-guide can be rendered (native
+ * binding exists upstream). darwin-x64 is excluded — it has NO native binding.
+ */
+export const NATIVE_ORT_INSTALLABLE_PLATFORMS: readonly EncoderPlatform[] = [
+  "linux-x64",
+  "linux-arm64",
+  "darwin-arm64",
+  "win32-x64",
+];