pi-mega-compact 0.20.49 → 0.20.51

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

@@ -2,15 +2,46 @@
  * SetupTab/CustomEndpointSection.tsx — custom remote embedder endpoint section.
  *
  * Extracted from EmbedderSetup.tsx to respect the extensions/ 400-line soft limit.
+ *
+ * ENC-1a: an additive "API key (optional Bearer)" password input sits beside the
+ * existing custom-URL input. The key is NEVER prefilled (the setup-status GET does
+ * not echo it — only an "is set" boolean, embeddingApiKeySet) and it is only ever
+ * sent up via the POST /api/setup-configure body. When the ENC-1a surface is
+ * inactive (flag off, the server omits the new GET fields) the key input is hidden
+ * and only the pre-existing URL row remains — byte-identical to the predecessor.
  */
 import type React from "react";
+import { useState } from "react";
+import type { SetupConfigureResponse } from "@contracts";
 import { styles } from "./EmbedderSetupStyles";
 
+/** ENC-1a surfaced a successful custom-endpoint persistence on the card. */
+const SAVED_NOTICE = "Saved; takes effect on next session start";
+
 interface CustomEndpointSectionProps {
 	customUrl: string;
 	setCustomUrl: (v: string) => void;
-	applyEmbedder: (embedder: "ollama" | "llama" | "trigram" | "custom" | "onnx", url?: string) => void;
+	applyEmbedder: (
+		embedder: "ollama" | "llama" | "trigram" | "custom" | "onnx",
+		url?: string,
+		apiKey?: string,
+		dim?: string,
+		headers?: string,
+		allowRemote?: boolean,
+	) => void;
 	configuring: string | null;
+	/** ENC-1a surface active — true when the new setup-status fields are present. */
+	inputEnabled: boolean;
+	/** Server-reported "key is set" marker (the key itself is never returned). */
+	apiKeySet: boolean;
+	/** ENC-1b: the persisted `embeddingDim` value (numeric string), or undefined. One-shot seed. */
+	embeddingDim: string | undefined;
+	/** ENC-1b: server-reported "headers are set" marker (the raw JSON is never returned). */
+	embeddingHeadersSet: boolean;
+	/** ENC-1b: the persisted allow-remote flag, or undefined. One-shot seed. */
+	allowRemoteEmbedder: boolean | undefined;
+	configureResult: SetupConfigureResponse | null;
+	configureError: string | null;
 }
 
 export default function CustomEndpointSection({
@@ -18,7 +49,38 @@ export default function CustomEndpointSection({
 	setCustomUrl,
 	applyEmbedder,
 	configuring,
+	inputEnabled,
+	apiKeySet,
+	embeddingDim,
+	embeddingHeadersSet,
+	allowRemoteEmbedder,
+	configureResult,
+	configureError,
 }: CustomEndpointSectionProps): React.ReactElement {
+	// The API key is intentionally local-only state: it always renders blank and
+	// is never seeded from the persisted value (the server never returns it).
+	const [customApiKey, setCustomApiKey] = useState("");
+	// ENC-1b: the embedding dim, seeded once from the persisted value (never
+	// re-seeded after a poll so the user's in-flight edits survive the 5s poll).
+	const [dim, setDim] = useState("");
+	const [dimSeeded, setDimSeeded] = useState(false);
+	// ENC-1b: the headers JSON is local-only, write-only state: NEVER prefilled,
+	// never seeded, never shown back — the server persists it verbatim and only
+	// ever reports its presence via `embeddingHeadersSet`.
+	const [headers, setHeaders] = useState("");
+	// ENC-1b: allow-remote toggle, seeded once from the persisted flag.
+	const [allowRemote, setAllowRemote] = useState(false);
+	const [allowRemoteSeeded, setAllowRemoteSeeded] = useState(false);
+
+	if (inputEnabled && !dimSeeded && typeof embeddingDim === "string") {
+		setDim(embeddingDim);
+		setDimSeeded(true);
+	}
+	if (inputEnabled && !allowRemoteSeeded && typeof allowRemoteEmbedder === "boolean") {
+		setAllowRemote(allowRemoteEmbedder);
+		setAllowRemoteSeeded(true);
+	}
+
 	return (
 		<div style={styles.section}>
 			<h3 style={styles.sectionTitle}>Custom Endpoint (remote / third-party)</h3>
@@ -46,14 +108,128 @@ export default function CustomEndpointSection({
 						fontFamily: "monospace",
 					}}
 				/>
+				{inputEnabled && (
+					<input
+						type="password"
+						autoComplete="new-password"
+						aria-label="API key (optional Bearer)"
+						placeholder="API key (optional Bearer)"
+						value={customApiKey}
+						onChange={(e) => setCustomApiKey(e.target.value)}
+						style={{
+							flex: "1 1 300px",
+							background: "#12122a",
+							color: "#e0e0e0",
+							border: "1px solid #2a2a4e",
+							borderRadius: "6px",
+							padding: "0.4rem 0.6rem",
+							fontSize: "0.85rem",
+							fontFamily: "monospace",
+						}}
+					/>
+				)}
+				{inputEnabled && apiKeySet && (
+					<span
+						style={{
+							fontSize: "0.75rem",
+							color: "#81c784",
+							border: "1px solid #2a4e2a",
+							borderRadius: "4px",
+							padding: "0.15rem 0.45rem",
+						}}
+					>
+						API key saved
+					</span>
+				)}
+				{inputEnabled && embeddingHeadersSet && (
+					<span
+						style={{
+							fontSize: "0.75rem",
+							color: "#81c784",
+							border: "1px solid #2a4e2a",
+							borderRadius: "4px",
+							padding: "0.15rem 0.45rem",
+						}}
+					>
+						Headers saved
+					</span>
+				)}
 				<button
 					style={{ ...styles.button, opacity: customUrl ? 1 : 0.4 }}
-					onClick={() => applyEmbedder("custom", customUrl)}
+					onClick={() =>
+						applyEmbedder("custom", customUrl, customApiKey, dim, headers, allowRemote)
+					}
 					disabled={!customUrl || configuring !== null}
 				>
 					{configuring === "custom" ? "Writing..." : "Use Custom URL"}
 				</button>
 			</div>
+			{inputEnabled && (
+				<div style={{ marginTop: "0.75rem" }}>
+					<div style={{ marginBottom: "0.5rem" }}>
+						<label style={{ ...styles.label, display: "block", marginBottom: "0.25rem" }}>
+							Embedding dim (optional)
+						</label>
+						<input
+							type="number"
+							min={1}
+							placeholder="e.g. 384"
+							value={dim}
+							onChange={(e) => setDim(e.target.value)}
+							style={{
+								width: "200px",
+								background: "#12122a",
+								color: "#e0e0e0",
+								border: "1px solid #2a2a4e",
+								borderRadius: "6px",
+								padding: "0.4rem 0.6rem",
+								fontSize: "0.85rem",
+								fontFamily: "monospace",
+							}}
+						/>
+					</div>
+					<div style={{ marginBottom: "0.5rem" }}>
+						<label style={{ ...styles.label, display: "block", marginBottom: "0.25rem" }}>
+							Embedding headers (JSON, write-only — never re-displayed)
+						</label>
+						<textarea
+							placeholder={'{"Authorization": "Bearer ..."}'}
+							value={headers}
+							onChange={(e) => setHeaders(e.target.value)}
+							aria-label="Embedding headers JSON (write-only — never re-displayed)"
+							rows={2}
+							style={{
+								width: "100%",
+								background: "#12122a",
+								color: "#e0e0e0",
+								border: "1px solid #2a2a4e",
+								borderRadius: "6px",
+								padding: "0.4rem 0.6rem",
+								fontSize: "0.85rem",
+								fontFamily: "monospace",
+								resize: "vertical",
+							}}
+						/>
+					</div>
+					<label style={{ display: "flex", alignItems: "center", gap: "0.5rem", fontSize: "0.85rem" }}>
+						<input
+							type="checkbox"
+							checked={allowRemote}
+							onChange={(e) => setAllowRemote(e.target.checked)}
+							aria-label="Allow remote embedder (skips loopback-only check)"
+						/>
+						Allow remote embedder (skips loopback-only check)
+					</label>
+				</div>
+			)}
+			{configureError !== null && (
+				<p style={{ color: "#f44336", fontSize: "0.85rem", marginTop: "0.5rem" }}>
+					Configure error: {configureError}
+				</p>
+			)}
+			{configureResult !== null && configureResult.embedder === "custom" && (
+				<div style={styles.warning}>{SAVED_NOTICE}</div>
+			)}
 			<div style={styles.warning}>
 				<strong>Heads up:</strong> a remote endpoint receives the text you embed
 				(it does NOT receive your full conversation — only the strings passed to

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

@@ -16,6 +16,7 @@ import EmbedderHealthCard from "./EmbedderHealthCard";
 import SettingsPanel from "./SettingsPanel";
 import CustomEndpointSection from "./CustomEndpointSection";
 import { styles } from "./EmbedderSetupStyles";
+import { detectBadge, CurrentConfigSection } from "./EmbedderSetupHelpers";
 
 export default function EmbedderSetup(): React.ReactElement {
 	const [status, setStatus] = useState<SetupStatusResponse | null>(null);
@@ -27,6 +28,10 @@ export default function EmbedderSetup(): React.ReactElement {
 	const [configResult, setConfigResult] = useState<SetupConfigureResponse | null>(null);
 	const [configError, setConfigError] = useState<string | null>(null);
 	const [customUrl, setCustomUrl] = useState("");
+	// True once the URL field has been seeded from the persisted endpoint URL —
+	// seeding runs only on the first status load that carries the field so the
+	// user's in-flight edits are never clobbered by a poll refresh.
+	const [customUrlSeeded, setCustomUrlSeeded] = useState(false);
 
 	const loadStatus = useCallback(() => {
 		fetchSetupStatus()
@@ -36,21 +41,43 @@ export default function EmbedderSetup(): React.ReactElement {
 			);
 	}, []);
 
-	const applyEmbedder = useCallback((embedder: "ollama" | "llama" | "trigram" | "custom" | "onnx", url?: string) => {
-		setConfiguring(embedder);
-		setConfigError(null);
-		setConfigResult(null);
-		configureEmbedder({ embedder, url })
-			.then((r) => {
-				setConfigResult(r);
-				setConfiguring(null);
-				loadStatus();
+	const applyEmbedder = useCallback(
+		(
+			embedder: "ollama" | "llama" | "trigram" | "custom" | "onnx",
+			url?: string,
+			apiKey?: string,
+			dim?: string,
+			headers?: string,
+			allowRemote?: boolean,
+		) => {
+			setConfiguring(embedder);
+			setConfigError(null);
+			setConfigResult(null);
+			// ENC-1a: optional custom-endpoint URL + bearer key ride on the setup-configure POST (additive; flag-off ignores them).
+			// ENC-1b: the dim / headers / allow-remote fields are forwarded additively, gated on the same
+			// `embeddingHeadersSet` presence marker the aggregator/server uses (no separate client env read).
+			const enc1bOn = "embeddingHeadersSet" in (status ?? {});
+			configureEmbedder({
+				embedder,
+				url,
+				embeddingEndpointUrl: url,
+				embeddingApiKey: apiKey,
+				...(enc1bOn
+					? { embeddingDim: dim, embeddingHeaders: headers, allowRemoteEmbedder: allowRemote }
+					: {}),
 			})
-			.catch((e: unknown) => {
-				setConfigError(e instanceof Error ? e.message : String(e));
-				setConfiguring(null);
-			});
-	}, [loadStatus]);
+				.then((r) => {
+					setConfigResult(r);
+					setConfiguring(null);
+					loadStatus();
+				})
+				.catch((e: unknown) => {
+					setConfigError(e instanceof Error ? e.message : String(e));
+					setConfiguring(null);
+				});
+		},
+		[loadStatus, status],
+	);
 
 	const runDetect = useCallback(() => {
 		setRunningDetect(true);
@@ -70,6 +97,17 @@ export default function EmbedderSetup(): React.ReactElement {
 		loadStatus();
 	}, [loadStatus]);
 
+	// Seed the custom-endpoint URL field once from the persisted
+	// `embeddingEndpointUrl` (ENC-1a). Later poll refreshes do NOT re-seed —
+	// only the first load, so typed edits survive the 5s status poll.
+	useEffect(() => {
+		if (customUrlSeeded) return;
+		if (status && typeof status.embeddingEndpointUrl === "string" && status.embeddingEndpointUrl.length > 0) {
+			setCustomUrl(status.embeddingEndpointUrl);
+			setCustomUrlSeeded(true);
+		}
+	}, [status, customUrlSeeded]);
+
 	// Poll status every 5s — the same cadence the Setup Cortex sub-tab uses
 	// (see useSetupCortexPoll) so the embedder + cortex sub-tabs share one poll
 	// contract (VC9D consolidation). Detection is memoized server-side, so the
@@ -88,41 +126,6 @@ export default function EmbedderSetup(): React.ReactElement {
 		return () => clearInterval(id);
 	}, [runDetect]);
 
-	const embedderLabel = (e: string): string => {
-		switch (e) {
-			case "trigram":
-				return "TrigramEmbedder (heuristic, default)";
-			case "http":
-				return "HTTP Embedder (BYO localhost)";
-			case "minilm":
-				return "MiniLM (experimental)";
-			default:
-				return "Unknown";
-		}
-	};
-
-	const trigramWarning = status?.currentEmbedder === "trigram" && (
-		<div style={styles.warning}>
-			<strong>Note:</strong> TrigramEmbedder is a heuristic-strength default
-			embedder. It works without any setup but recall quality may be lower
-			than a dedicated embedding backend. If you notice poor recall results,
-			consider installing Ollama and running the{" "}
-			<code>/megasetup</code> command, or set{" "}
-			<code>MEGACOMPACT_EMBEDDING_URL</code> to point at your own localhost
-			embedding server.
-		</div>
-	);
-
-	const detectBadge = (installed: boolean): React.ReactElement => {
-		const bg = installed ? "#1a5a1a" : "#3a1a1a";
-		const color = installed ? "#4caf50" : "#f44336";
-		return (
-			<span style={{ ...styles.badge, background: bg, color }}>
-				{installed ? "Detected" : "Not found"}
-			</span>
-		);
-	};
-
 	return (
 		<div style={styles.container}>
 			<h2 style={{ fontSize: "1.3rem", marginTop: 0, marginBottom: "1rem" }}>
@@ -132,69 +135,7 @@ export default function EmbedderSetup(): React.ReactElement {
 			<EmbedderHealthCard />
 
 			{/* Current Config Section */}
-			<div style={styles.section}>
-				<h3 style={styles.sectionTitle}>Current Embedder Configuration</h3>
-				{statusError && (
-					<p style={{ color: "#f44336", fontSize: "0.85rem" }}>
-						Error: {statusError}
-					</p>
-				)}
-				{status && (
-					<>
-						<div style={styles.row}>
-							<span style={styles.label}>Active Embedder:</span>
-							<span style={styles.value}>
-								{embedderLabel(status.currentEmbedder)}
-							</span>
-						</div>
-						{"configuredEmbedder" in status && status.configuredEmbedder !== status.currentEmbedder && (
-							<div style={styles.warning}>
-								<strong>Configured but not active:</strong>{" "}
-								{embedderLabel(status.configuredEmbedder)} is configured in
-								.mega-compact.env but not yet loaded.{" "}
-								<strong>Restart pi</strong> to activate it.
-								{status.configuredUrl && (
-									<> ({status.configuredUrl})</>
-								)}
-							</div>
-						)}
-						{"restartRequired" in status && status.restartRequired && (
-							<div style={{ ...styles.row, color: "#ff9800" }}>
-								<span style={styles.label}>Status:</span>
-								<span style={styles.value}>
-									Restart required to activate the configured embedder
-								</span>
-							</div>
-						)}
-						<div style={styles.row}>
-							<span style={styles.label}>Embedding URL:</span>
-							<span style={styles.value}>
-								{status.embeddingUrl ?? (
-									<span style={{ color: "#888" }}>not set</span>
-								)}
-							</span>
-						</div>
-						<div style={styles.row}>
-							<span style={styles.label}>Embed Cache:</span>
-							<span style={styles.value}>
-								{status.embedCache ?? (
-									<span style={{ color: "#888" }}>not set</span>
-								)}
-							</span>
-						</div>
-						<div style={styles.row}>
-							<span style={styles.label}>MiniLM:</span>
-							<span style={styles.value}>{status.minilm ? "enabled" : "disabled"}</span>
-						</div>
-						{trigramWarning}
-					</>
-				)}
-				{!status && !statusError && (
-					<p style={{ color: "#888", fontSize: "0.85rem" }}>
-						Loading configuration...
-					</p>
-				)}
-			</div>
+			<CurrentConfigSection status={status} statusError={statusError} />
 
 			{/* Detection Section */}
 			<div style={styles.section}>
@@ -334,7 +275,7 @@ export default function EmbedderSetup(): React.ReactElement {
 								{configuring === "trigram" ? "Writing..." : "Use Trigram (default)"}
 							</button>
 						</div>
-						{configResult && (
+						{configResult && configResult.embedder !== "custom" && (
 							<div style={styles.warning}>
 								{configResult.alreadyActive
 									? "Already active — no restart needed."
@@ -356,6 +297,13 @@ export default function EmbedderSetup(): React.ReactElement {
 				setCustomUrl={setCustomUrl}
 				applyEmbedder={applyEmbedder}
 				configuring={configuring}
+				inputEnabled={status !== null && "embeddingApiKeySet" in status}
+				apiKeySet={status?.embeddingApiKeySet === true}
+				embeddingDim={status?.embeddingDim}
+				embeddingHeadersSet={status?.embeddingHeadersSet === true}
+				allowRemoteEmbedder={status?.allowRemoteEmbedder}
+				configureResult={configResult}
+				configureError={configError}
 			/>
 
 			{/* Help Section */}

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

@@ -0,0 +1,125 @@
+/**
+ * SetupTab/EmbedderSetupHelpers.tsx — extracted render helpers for EmbedderSetup.
+ *
+ * Split from EmbedderSetup.tsx to respect the extensions/ 400-line soft limit
+ * (ENC-1a pushed the embedder card over its cap, so the helpers were extracted).
+ */
+import type React from "react";
+import type { SetupStatusResponse } from "@contracts";
+import { styles } from "./EmbedderSetupStyles";
+
+/** Human label for an embedder identifier. */
+export function embedderLabel(e: string): string {
+	switch (e) {
+		case "trigram":
+			return "TrigramEmbedder (heuristic, default)";
+		case "http":
+			return "HTTP Embedder (BYO localhost)";
+		case "minilm":
+			return "MiniLM (experimental)";
+		default:
+			return "Unknown";
+	}
+}
+
+/** Warn when the active embedder is the heuristic trigram default. */
+export function trigramWarning(status: SetupStatusResponse | null): React.ReactElement | null {
+	if (status?.currentEmbedder !== "trigram") return null;
+	return (
+		<div style={styles.warning}>
+			<strong>Note:</strong> TrigramEmbedder is a heuristic-strength default
+			embedder. It works without any setup but recall quality may be lower
+			than a dedicated embedding backend. If you notice poor recall results,
+			consider installing Ollama and running the{" "}
+			<code>/megasetup</code> command, or set{" "}
+			<code>MEGACOMPACT_EMBEDDING_URL</code> to point at your own localhost
+			embedding server.
+		</div>
+	);
+}
+
+/** Installed / not-found badge dot for a detection row. */
+export function detectBadge(installed: boolean): React.ReactElement {
+	const bg = installed ? "#1a5a1a" : "#3a1a1a";
+	const color = installed ? "#4caf50" : "#f44336";
+	return (
+		<span style={{ ...styles.badge, background: bg, color }}>
+			{installed ? "Detected" : "Not found"}
+		</span>
+	);
+}
+
+/** The "Current Embedder Configuration" readout block. */
+export function CurrentConfigSection({
+	status,
+	statusError,
+}: {
+	status: SetupStatusResponse | null;
+	statusError: string | null;
+}): React.ReactElement {
+	return (
+		<div style={styles.section}>
+			<h3 style={styles.sectionTitle}>Current Embedder Configuration</h3>
+			{statusError && (
+				<p style={{ color: "#f44336", fontSize: "0.85rem" }}>
+					Error: {statusError}
+				</p>
+			)}
+			{status && (
+				<>
+					<div style={styles.row}>
+						<span style={styles.label}>Active Embedder:</span>
+						<span style={styles.value}>
+							{embedderLabel(status.currentEmbedder)}
+						</span>
+					</div>
+					{"configuredEmbedder" in status && status.configuredEmbedder !== status.currentEmbedder && (
+						<div style={styles.warning}>
+							<strong>Configured but not active:</strong>{" "}
+							{embedderLabel(status.configuredEmbedder)} is configured in
+							.mega-compact.env but not yet loaded.{" "}
+							<strong>Restart pi</strong> to activate it.
+							{status.configuredUrl && (
+								<> ({status.configuredUrl})</>
+							)}
+						</div>
+					)}
+					{"restartRequired" in status && status.restartRequired && (
+						<div style={{ ...styles.row, color: "#ff9800" }}>
+							<span style={styles.label}>Status:</span>
+							<span style={styles.value}>
+								Restart required to activate the configured embedder
+							</span>
+						</div>
+					)}
+					<div style={styles.row}>
+						<span style={styles.label}>Embedding URL:</span>
+						<span style={styles.value}>
+							{status.embeddingUrl ?? (
+								<span style={{ color: "#888" }}>not set</span>
+							)}
+						</span>
+					</div>
+					<div style={styles.row}>
+						<span style={styles.label}>Embed Cache:</span>
+						<span style={styles.value}>
+							{status.embedCache ?? (
+								<span style={{ color: "#888" }}>not set</span>
+							)}
+						</span>
+					</div>
+					<div style={styles.row}>
+						<span style={styles.label}>MiniLM:</span>
+						<span style={styles.value}>{status.minilm ? "enabled" : "disabled"}</span>
+					</div>
+					{trigramWarning(status)}
+				</>
+			)}
+			{!status && !statusError && (
+				<p style={{ color: "#888", fontSize: "0.85rem" }}>
+					Loading configuration...
+				</p>
+			)}
+		</div>
+	);
+}

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

@@ -27,6 +27,34 @@ export interface SetupStatusResponse {
   readonly embedCache: string | null;
   /** Whether MEGACOMPACT_MINILM is set to a truthy value. */
   readonly minilm: boolean;
+  /** ENC-1a: the external embedder endpoint URL persisted in the per-repo
+   *  `.mega-compact.env`, when one is configured (additive, flag-gated). */
+  readonly embeddingEndpointUrl?: string;
+  /** ENC-1a: whether an external embedder API key is configured. The raw key is
+   *  NEVER returned — only this boolean presence marker (additive, flag-gated). */
+  readonly embeddingApiKeySet?: boolean;
+  /** ENC-1b: the persisted `MEGACOMPACT_EMBEDDING_DIM` value as its numeric
+   *  string, when one is configured (additive, flag-gated). */
+  readonly embeddingDim?: string;
+  /** ENC-1b: whether `MEGACOMPACT_EMBEDDING_HEADERS` is configured. The raw
+   *  headers JSON is NEVER returned — only this boolean presence marker
+   *  (additive, flag-gated, redaction mirrors embeddingApiKeySet). */
+  readonly embeddingHeadersSet?: boolean;
+  /** ENC-1b: whether `MEGACOMPACT_ALLOW_REMOTE_EMBEDDER` is set (default off —
+   *  a deliberate escape hatch that skips the loopback-only check; additive,
+   *  flag-gated). */
+  readonly allowRemoteEmbedder?: boolean;
+  /** ENC-1b: whether `MEGACOMPACT_ENCODER_NATIVE=1` is set, i.e. the operator
+   *  opted into the onnxruntime-node native backend (additive, flag-gated). */
+  readonly encoderNativeOptIn?: boolean;
+  /** ENC-1b: the current effective ONNX runtime backend, computed live through
+   *  the existing `selectRuntimeBackend`. `modeB` (flag-off / no runtime) is
+   *  projected to `wasm` for display (additive, flag-gated). */
+  readonly encoderBackend?: "wasm" | "native";
+  /** ENC-1b: the runtime's own demotion reason when the effective backend
+   *  falls back (e.g. native selected but onnxruntime-node absent / darwin-x64
+   *  demoted), surfaced verbatim; null when no demotion (additive, flag-gated). */
+  readonly encoderDemotionReason?: string | null;
 }
 
 /**
@@ -72,6 +100,25 @@ export interface SetupConfigureRequest {
   readonly embedder: "ollama" | "llama" | "trigram" | "custom" | "onnx";
   /** Override URL (required for "custom"; optional defaults for ollama/llama/onnx). */
   readonly url?: string;
+  /** ENC-1a: external embedder endpoint URL, persisted to the per-repo
+   *  `.mega-compact.env` (additive, flag-gated). */
+  readonly embeddingEndpointUrl?: string;
+  /** ENC-1a: external embedder API key, persisted to the per-repo
+   *  `.mega-compact.env` only — never returned by any GET (additive, flag-gated). */
+  readonly embeddingApiKey?: string;
+  /** ENC-1b: persisted `MEGACOMPACT_EMBEDDING_DIM` as a positive integer string
+   *  within `ENC_1B_MAX_EMBEDDING_DIM` (validated; additive, flag-gated). */
+  readonly embeddingDim?: string;
+  /** ENC-1b: persisted `MEGACOMPACT_EMBEDDING_HEADERS` JSON object string
+   *  (secret-bearing — written verbatim, NEVER echoed back; validated to parse
+   *  as a JSON object; additive, flag-gated). */
+  readonly embeddingHeaders?: string;
+  /** ENC-1b: opt in to `MEGACOMPACT_ALLOW_REMOTE_EMBEDDER` (default off — a
+   *  deliberate escape hatch; additive, flag-gated). */
+  readonly allowRemoteEmbedder?: boolean;
+  /** ENC-1b: opt in to `MEGACOMPACT_ENCODER_NATIVE` (onnxruntime-node native
+   *  backend; additive, flag-gated). */
+  readonly encoderNativeOptIn?: boolean;
 }
 
 /** Response for POST /api/setup-configure. */

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

@@ -294,5 +294,17 @@ export const VECTOR_CORTEX_SETTINGS: SettingGroup = {
 			"ENC-0g makes the Setup Cortex status route honest: reads the ENC-0f QualificationV1 record (when ENC_0F is ON and a record exists) and lets its verdict override the structural verify for the qualification field; computes the blocker list from (platform, record, manifest head-count) with corrected HG statuses/wording; re-derives VC9B action gating from live blockers. OFF = verdict from verifyEncoderAsset alone, static SETUP_CORTEX_BLOCKERS, static action gating (byte-identical ENC-0f predecessor).",
 			true,
 		),
+		boolDirect(
+			"MEGACOMPACT_ENC_1A",
+			"ENC-1a external embedder API key + endpoint Settings fields",
+			"ENC-1a adds a Settings-visible field pair for the external embedder endpoint URL + optional Bearer API key, persisted by the setup-configure writer branch to the per-repo .mega-compact.env (MEGACOMPACT_EMBEDDING_URL / MEGACOMPACT_EMBEDDING_KEY). The GET status route echoes the endpoint URL and reports embeddingApiKeySet as a boolean ONLY — the raw key is never returned. OFF = no new GET fields, no writer branch, no new Settings text rows (byte-identical ENC-0g predecessor).",
+			true,
+		),
+		boolDirect(
+			"MEGACOMPACT_ENC_1B",
+			"ENC-1b ONNX runtime backend + embedder API settings",
+			"ENC-1b completes the embedder API Settings surface (dim / headers / allow-remote persisted to the per-repo .mega-compact.env) and surfaces the ONNX runtime selection knob (MEGACOMPACT_ENCODER_NATIVE) as a toggle plus the current effective backend + demotion reason. OFF = no new GET fields, no writer branch, no new Settings rows or toggle (byte-identical ENC-1a predecessor).",
+			true,
+		),
 	],
 };