@rubytech/create-maxy-code 0.1.321 → 0.1.323

package/dist/index.js

@@ -20,7 +20,7 @@ import { classifyPortHolder } from "./preflight-port-classifier.js";
 import { parsePluginList, computeInstallActions, parseExternalPlugins, findUnregisteredResyncs, } from "./lib/plugin-install.js";
 import { findPremiumMcpDirs } from "./lib/premium-mcp-discover.js";
 import { pickBindDecision, mergeSmbConf, formatSambaMarker, SAMBA_ENABLE_UNITS, } from "./samba-provision.js";
-import { networkInterfaces, userInfo } from "node:os";
+import { networkInterfaces, userInfo, cpus } from "node:os";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -608,6 +608,55 @@ function writeChromiumBinaryPathFile() {
     console.log(`  Wrote ${target} → ${RESOLVED_CHROMIUM_BIN}`);
     logFile(`  [snap-chromium] wrote ${target} contents=${RESOLVED_CHROMIUM_BIN}`);
 }
+// Arm the systemd system-manager hardware watchdog so a *kernel hang* (the
+// freeze mode: board powered but stuck, /dev/watchdog never petted) reboots the
+// board without a manual power cycle. Distinct from the brand user-service's
+// software watchdog (Type=notify WATCHDOG_USEC), which only restarts the UI
+// process — this resets the whole SoC. Idempotent host-wide drop-in; gated on
+// /dev/watchdog existing (driver loaded) and Linux. Best-effort: a failure
+// warns, never aborts the install. Cannot recover a latched-off brownout (no
+// power = no watchdog) — that needs the external power-cycler documented in
+// deployment.md.
+function configureHardwareWatchdog() {
+    try {
+        if (!isLinux()) {
+            logFile("  hardware watchdog: skipped (not Linux)");
+            return;
+        }
+        if (!existsSync("/dev/watchdog")) {
+            logFile("  hardware watchdog: skipped (/dev/watchdog absent)");
+            return;
+        }
+        const desired = "[Manager]\nRuntimeWatchdogSec=20s\nRebootWatchdogSec=2min\n";
+        const dropinDir = "/etc/systemd/system.conf.d";
+        const dropinPath = `${dropinDir}/10-maxy-watchdog.conf`;
+        let current = "";
+        if (existsSync(dropinPath)) {
+            try {
+                current = readFileSync(dropinPath, "utf-8");
+            }
+            catch {
+                // Unreadable existing drop-in — treat as changed so we rewrite.
+                current = "";
+            }
+        }
+        if (current === desired) {
+            logFile(`  hardware watchdog: already active (${dropinPath})`);
+            return;
+        }
+        const tmpPath = "/tmp/10-maxy-watchdog.conf";
+        writeFileSync(tmpPath, desired);
+        console.log("  [privileged] install systemd hardware watchdog drop-in (RuntimeWatchdogSec=20s RebootWatchdogSec=2min)");
+        shell("mkdir", ["-p", dropinDir], { sudo: true });
+        shell("cp", [tmpPath, dropinPath], { sudo: true });
+        spawnSync("rm", ["-f", tmpPath]);
+        spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
+        logFile(`  hardware watchdog: enabled (wrote ${dropinPath}; arms on next boot or systemd re-exec)`);
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to configure hardware watchdog: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 function installSystemDeps() {
     log("1", TOTAL, "System dependencies and network...");
     const platform = requireSupportedPlatform(process.platform);
@@ -1557,6 +1606,86 @@ function ensureOllamaServing() {
     logFile(`  Ollama serve timed out after 30s. Log tail:\n${serveLog}`);
     throw new Error(`Ollama server did not respond within 30s. Log: ${ollamaLog}\n${serveLog}`);
 }
+// Cap ollama's CPU so an embedding burst cannot thermally hard-reset a
+// passively-cooled Pi. The platform embeds a document's summary plus every
+// section body via one `/api/embed` POST; ollama's llama-server then runs
+// flat-out across every core for the whole batch with no idle gaps, and on a
+// passively-cooled Pi 5 the SoC climbs past its soft-temp limit until the board
+// reaches its thermal ceiling and hard-resets. A systemd `CPUQuota` drop-in on
+// `ollama.service` bounds llama-server to a fraction of the cores so peak
+// temperature plateaus below the limit regardless of batch shape or which
+// platform path issues the embeds — the caller-agnostic fix, inherited by every
+// install. Quota is one core (100%): an embedding burst then draws roughly a
+// quarter of a 4-core Pi's compute current instead of half, which both keeps
+// peak SoC temperature down and shaves the current spike that browns out a
+// marginal PSU. Ingest is slower in exchange. Applied only when the ollama
+// system service exists (the normal Linux path, where ollama's install.sh
+// registers `ollama.service`); a detached `ollama serve` has no unit to cap.
+// ollama is one shared host service across co-resident brands, so the drop-in is
+// host-wide with a neutral filename — idempotent across brands and reinstalls,
+// and ollama restarts only when the drop-in content actually changes. Best-
+// effort: a failure warns, never aborts the install.
+function capOllamaServiceCpu() {
+    try {
+        const svcCheck = spawnSync("systemctl", ["cat", "ollama"], { stdio: "pipe", timeout: 5_000 });
+        if (svcCheck.status !== 0) {
+            logFile("  ollama CPU cap: skipped (no ollama system service to cap)");
+            return;
+        }
+        const coreCount = Math.max(1, cpus().length);
+        const quotaCores = 1;
+        const quotaPct = quotaCores * 100;
+        const desired = `[Service]\nCPUQuota=${quotaPct}%\n`;
+        const dropinDir = "/etc/systemd/system/ollama.service.d";
+        const dropinPath = `${dropinDir}/10-maxy-cpuquota.conf`;
+        let current = "";
+        if (existsSync(dropinPath)) {
+            try {
+                current = readFileSync(dropinPath, "utf-8");
+            }
+            catch {
+                // Unreadable existing drop-in — treat as changed so we rewrite + restart.
+                current = "";
+            }
+        }
+        if (current === desired) {
+            logFile(`  ollama CPU cap: already active (${dropinPath} matches CPUQuota=${quotaPct}%)`);
+            return;
+        }
+        const tmpPath = "/tmp/10-maxy-ollama-cpuquota.conf";
+        writeFileSync(tmpPath, desired);
+        console.log(`  [privileged] install ollama CPUQuota=${quotaPct}% drop-in (${quotaCores}/${coreCount} cores)`);
+        shell("mkdir", ["-p", dropinDir], { sudo: true });
+        shell("cp", [tmpPath, dropinPath], { sudo: true });
+        spawnSync("rm", ["-f", tmpPath]);
+        spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
+        console.log("  [privileged] systemctl restart ollama");
+        spawnSync("sudo", ["systemctl", "restart", "ollama"], { stdio: "inherit", timeout: 30_000 });
+        // The restart briefly drops the API. Wait for ollama to serve again before
+        // returning so the immediately-following ensureOllamaServing() probe finds
+        // it up and does not race the restart by spawning a second detached
+        // `ollama serve` that would contend for port 11434. Bounded poll; the drop-in
+        // is already on disk either way, so a timeout still applies the cap on the
+        // next ollama start.
+        let served = false;
+        for (let elapsed = 0; elapsed < 15; elapsed += 3) {
+            if (spawnSync("curl", ["-sf", "http://localhost:11434/api/tags"], { stdio: "pipe", timeout: 5_000 }).status === 0) {
+                served = true;
+                break;
+            }
+            spawnSync("sleep", ["3"]);
+        }
+        if (served) {
+            logFile(`  ollama CPU cap: enabled (wrote ${dropinPath} CPUQuota=${quotaPct}%, ollama serving again under the cap)`);
+        }
+        else {
+            logFile(`  ollama CPU cap: drop-in written (${dropinPath} CPUQuota=${quotaPct}%); ollama not serving yet after restart — cap applies on its next start`);
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to cap ollama CPU: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 function installOllama(embedModel) {
     if (!commandExists("ollama")) {
         log("5", TOTAL, "Installing Ollama...");
@@ -1565,6 +1694,9 @@ function installOllama(embedModel) {
     else {
         log("5", TOTAL, "Ollama already installed.");
     }
+    // Bound ollama's CPU before bringing the service up so the capped unit is what
+    // serves embeds (and the restart below lands the new quota).
+    capOllamaServiceCpu();
     ensureOllamaServing();
     console.log(`  Pulling ${embedModel} embedding model...`);
     logFile(`  Pulling embedding model: ${embedModel}`);
@@ -4107,6 +4239,7 @@ logDiagnostics("pre-flight");
 logFile(`  Neo4j instance: ${NEO4J_DEDICATED ? "dedicated" : "shared"} on bolt://localhost:${NEO4J_PORT}`);
 try {
     installSystemDeps();
+    configureHardwareWatchdog();
     installNodejs();
     installClaudeCode();
     installNeo4j();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.321",
+  "version": "0.1.323",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/lib/embed-client/dist/index.d.ts

@@ -1,4 +1,6 @@
 export declare const EMBED_INPUT_MAX_CHARS = 8000;
+export declare const EMBED_SUBBATCH_SIZE: number;
+export declare const EMBED_SUBBATCH_COOLDOWN_MS: number;
 export declare function embed(text: string): Promise<number[]>;
 export declare function embedBatch(texts: string[]): Promise<number[][]>;
 //# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/embed-client/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAU1C,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa3D;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAarE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAmB1C,eAAO,MAAM,mBAAmB,QAA6D,CAAC;AAC9F,eAAO,MAAM,0BAA0B,QAGtC,CAAC;AA4BF,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa3D;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAoBrE"}

package/payload/platform/lib/embed-client/dist/index.js

@@ -6,7 +6,7 @@
 // and one POST shape across the platform (Task 636). fetch-only — no node:fs —
 // so it is safe to bundle into the ESM payload.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EMBED_INPUT_MAX_CHARS = void 0;
+exports.EMBED_SUBBATCH_COOLDOWN_MS = exports.EMBED_SUBBATCH_SIZE = exports.EMBED_INPUT_MAX_CHARS = void 0;
 exports.embed = embed;
 exports.embedBatch = embedBatch;
 const OLLAMA_URL = process.env.OLLAMA_URL ?? "http://localhost:11434";
@@ -16,28 +16,49 @@ const EMBED_MODEL = process.env.EMBED_MODEL ?? "nomic-embed-text";
 // an oversized body embeds (truncated) instead of throwing and aborting the
 // caller.
 exports.EMBED_INPUT_MAX_CHARS = 8000;
+// Batch pacing (Task 960). On a passively-cooled Pi, embedding a whole
+// document's sections in one `/api/embed` POST pins ollama's llama-server
+// across every core for the entire batch with no idle gaps — the SoC climbs
+// past its soft-temp limit and the board thermally hard-resets. embedBatch
+// splits an oversized input array into sub-batches and waits a cooldown between
+// them so the SoC gets cooling gaps. Centralising here means every batch caller
+// (memory-ingest, memory-archive-write, memory-reindex) inherits the pacing.
+// The systemd CPUQuota cap on ollama.service is the load-bearing thermal fix;
+// this pacing is defence-in-depth and faster recovery. Both knobs are
+// env-overridable so an operator can tune them from on-device thermal
+// measurement without a code change.
+function envInt(name, def) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return def;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : def;
+}
+exports.EMBED_SUBBATCH_SIZE = Math.max(1, Math.floor(envInt("EMBED_SUBBATCH_SIZE", 32)));
+exports.EMBED_SUBBATCH_COOLDOWN_MS = Math.max(0, envInt("EMBED_SUBBATCH_COOLDOWN_MS", 1000));
 function capInput(text) {
     if (text.length <= exports.EMBED_INPUT_MAX_CHARS)
         return text;
     process.stderr.write(`[embed] op=truncate origBytes=${text.length} cappedBytes=${exports.EMBED_INPUT_MAX_CHARS}\n`);
     return text.slice(0, exports.EMBED_INPUT_MAX_CHARS);
 }
-async function embed(text) {
-    const input = capInput(text);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// POST one already-capped sub-batch of inputs to the embed endpoint.
+async function postBatch(inputs) {
     const res = await fetch(`${OLLAMA_URL}/api/embed`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ model: EMBED_MODEL, input }),
+        body: JSON.stringify({ model: EMBED_MODEL, input: inputs }),
     });
     if (!res.ok) {
         const body = await res.text();
-        throw new Error(`Ollama embedding failed (${res.status}): ${body}`);
+        throw new Error(`Ollama batch embedding failed (${res.status}): ${body}`);
     }
     const data = (await res.json());
-    return data.embeddings[0];
+    return data.embeddings;
 }
-async function embedBatch(texts) {
-    const input = texts.map(capInput);
+async function embed(text) {
+    const input = capInput(text);
     const res = await fetch(`${OLLAMA_URL}/api/embed`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -45,9 +66,28 @@ async function embedBatch(texts) {
     });
     if (!res.ok) {
         const body = await res.text();
-        throw new Error(`Ollama batch embedding failed (${res.status}): ${body}`);
+        throw new Error(`Ollama embedding failed (${res.status}): ${body}`);
     }
     const data = (await res.json());
-    return data.embeddings;
+    return data.embeddings[0];
+}
+async function embedBatch(texts) {
+    const inputs = texts.map(capInput);
+    // Common case — an array within the sub-batch size is one POST, unchanged.
+    if (inputs.length <= exports.EMBED_SUBBATCH_SIZE) {
+        return postBatch(inputs);
+    }
+    // Oversized: split into sub-batches, cooling between each (not after the
+    // last). Vectors are concatenated in input order so callers can keep their
+    // index-aligned `embeddings[i]` ↔ `texts[i]` contract.
+    const out = [];
+    for (let i = 0; i < inputs.length; i += exports.EMBED_SUBBATCH_SIZE) {
+        if (i > 0 && exports.EMBED_SUBBATCH_COOLDOWN_MS > 0) {
+            await sleep(exports.EMBED_SUBBATCH_COOLDOWN_MS);
+        }
+        const chunk = inputs.slice(i, i + exports.EMBED_SUBBATCH_SIZE);
+        out.push(...(await postBatch(chunk)));
+    }
+    return out;
 }
 //# sourceMappingURL=index.js.map

package/payload/platform/lib/embed-client/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,yEAAyE;AACzE,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,gDAAgD;;;AAmBhD,sBAaC;AAED,gCAaC;AA7CD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,wBAAwB,CAAC;AACtE,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,kBAAkB,CAAC;AAElE,2EAA2E;AAC3E,gFAAgF;AAChF,4EAA4E;AAC5E,UAAU;AACG,QAAA,qBAAqB,GAAG,IAAI,CAAC;AAE1C,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,IAAI,CAAC,MAAM,IAAI,6BAAqB;QAAE,OAAO,IAAI,CAAC;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCAAiC,IAAI,CAAC,MAAM,gBAAgB,6BAAqB,IAAI,CACtF,CAAC;IACF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,6BAAqB,CAAC,CAAC;AAC9C,CAAC;AAEM,KAAK,UAAU,KAAK,CAAC,IAAY;IACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,UAAU,YAAY,EAAE;QACjD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;KACpD,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA+B,CAAC;IAC9D,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAEM,KAAK,UAAU,UAAU,CAAC,KAAe;IAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,UAAU,YAAY,EAAE;QACjD,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;KACpD,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA+B,CAAC;IAC9D,OAAO,IAAI,CAAC,UAAU,CAAC;AACzB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/payload/platform/lib/embed-client/src/index.ts

@@ -14,6 +14,29 @@ const EMBED_MODEL = process.env.EMBED_MODEL ?? "nomic-embed-text";
 // caller.
 export const EMBED_INPUT_MAX_CHARS = 8000;
 
+// Batch pacing (Task 960). On a passively-cooled Pi, embedding a whole
+// document's sections in one `/api/embed` POST pins ollama's llama-server
+// across every core for the entire batch with no idle gaps — the SoC climbs
+// past its soft-temp limit and the board thermally hard-resets. embedBatch
+// splits an oversized input array into sub-batches and waits a cooldown between
+// them so the SoC gets cooling gaps. Centralising here means every batch caller
+// (memory-ingest, memory-archive-write, memory-reindex) inherits the pacing.
+// The systemd CPUQuota cap on ollama.service is the load-bearing thermal fix;
+// this pacing is defence-in-depth and faster recovery. Both knobs are
+// env-overridable so an operator can tune them from on-device thermal
+// measurement without a code change.
+function envInt(name: string, def: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return def;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : def;
+}
+export const EMBED_SUBBATCH_SIZE = Math.max(1, Math.floor(envInt("EMBED_SUBBATCH_SIZE", 32)));
+export const EMBED_SUBBATCH_COOLDOWN_MS = Math.max(
+  0,
+  envInt("EMBED_SUBBATCH_COOLDOWN_MS", 1000),
+);
+
 function capInput(text: string): string {
   if (text.length <= EMBED_INPUT_MAX_CHARS) return text;
   process.stderr.write(
@@ -22,23 +45,26 @@ function capInput(text: string): string {
   return text.slice(0, EMBED_INPUT_MAX_CHARS);
 }
 
-export async function embed(text: string): Promise<number[]> {
-  const input = capInput(text);
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+// POST one already-capped sub-batch of inputs to the embed endpoint.
+async function postBatch(inputs: string[]): Promise<number[][]> {
   const res = await fetch(`${OLLAMA_URL}/api/embed`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ model: EMBED_MODEL, input }),
+    body: JSON.stringify({ model: EMBED_MODEL, input: inputs }),
   });
   if (!res.ok) {
     const body = await res.text();
-    throw new Error(`Ollama embedding failed (${res.status}): ${body}`);
+    throw new Error(`Ollama batch embedding failed (${res.status}): ${body}`);
   }
   const data = (await res.json()) as { embeddings: number[][] };
-  return data.embeddings[0];
+  return data.embeddings;
 }
 
-export async function embedBatch(texts: string[]): Promise<number[][]> {
-  const input = texts.map(capInput);
+export async function embed(text: string): Promise<number[]> {
+  const input = capInput(text);
   const res = await fetch(`${OLLAMA_URL}/api/embed`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -46,8 +72,30 @@ export async function embedBatch(texts: string[]): Promise<number[][]> {
   });
   if (!res.ok) {
     const body = await res.text();
-    throw new Error(`Ollama batch embedding failed (${res.status}): ${body}`);
+    throw new Error(`Ollama embedding failed (${res.status}): ${body}`);
   }
   const data = (await res.json()) as { embeddings: number[][] };
-  return data.embeddings;
+  return data.embeddings[0];
+}
+
+export async function embedBatch(texts: string[]): Promise<number[][]> {
+  const inputs = texts.map(capInput);
+
+  // Common case — an array within the sub-batch size is one POST, unchanged.
+  if (inputs.length <= EMBED_SUBBATCH_SIZE) {
+    return postBatch(inputs);
+  }
+
+  // Oversized: split into sub-batches, cooling between each (not after the
+  // last). Vectors are concatenated in input order so callers can keep their
+  // index-aligned `embeddings[i]` ↔ `texts[i]` contract.
+  const out: number[][] = [];
+  for (let i = 0; i < inputs.length; i += EMBED_SUBBATCH_SIZE) {
+    if (i > 0 && EMBED_SUBBATCH_COOLDOWN_MS > 0) {
+      await sleep(EMBED_SUBBATCH_COOLDOWN_MS);
+    }
+    const chunk = inputs.slice(i, i + EMBED_SUBBATCH_SIZE);
+    out.push(...(await postBatch(chunk)));
+  }
+  return out;
 }

package/payload/platform/plugins/admin/skills/insight/SKILL.md

@@ -19,6 +19,6 @@ Pass 2 — Operator-relationship updates. Walk this session for tonal signals, r
 
 Pass 3 — Graph completeness sweep. Walk this session for any node, edge, or commitment that was discussed but not written to the graph in-flight. For each missing write, delegate to `database-operator` via the Task tool. Count what you write.
 
-Pass 4 — Typed-edge auto-extraction. Delegate to `database-operator` via the Task tool with a prompt naming the typed-edge pass and the session-start timestamp. The specialist calls `memory-typed-edge-pass` with that timestamp and returns the counters. Capture `nodesProcessed` and the accepted count from its reply.
+Pass 4 — Typed-edge auto-extraction. Delegate to `typed-edge-classifier` via the Task tool with a prompt supplying the `accountId` and the session-start timestamp as `sinceIso`. The specialist reads prose nodes written since that timestamp, writes typed edges from the closed allowlist, and returns one line `typed-edge-classifier: nodesProcessed=… proposed=… accepted=… rejected=… ms=…`. Capture `nodesProcessed` and `accepted` from that line.
 
 Then reply with one short paragraph in your house voice summarising what you wrote — naming the five counts (learnings, preferences, graph-writes, typed-edges, nodesProcessed) — and carry on with the operator's work.

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:fe4862e501a7da76a576d077c3313fb611b3db8b5f9c52ac272b193d16b0d08b
+content-hash: sha256:479e04a1e25ace04e44415db3c536ed28faac7ee30b9171524d38b7a667716d1
 brand: maxy-code
 product-name: Maxy
 ---
@@ -365,10 +365,10 @@ These are enabled during onboarding and can be added or removed at any time. Som
 | `whatsapp` | WhatsApp messaging, pairing, and conversation browsing | Personal assistant |
 | `replicate` | Image generation — three models for photorealistic, design, and fast draft images | Content producer, Research assistant |
 | `linkedin-import` | Import a LinkedIn Basic Data Export — Profile and Connections today, more CSVs as references land | Database operator |
-| `notion-import` | Import a Notion workspace export (markdown + CSV) — pages, databases, hierarchy, attachments, schema-bounded relations, `@person` mentions account-filtered | Database operator |
-| `obsidian-import` | Import an extracted Obsidian vault — pages map to `:KnowledgeDocument`, wikilinks resolve to intra-vault pages or existing entities, tags become `:DefinedTerm`, embedded images become `:DigitalDocument`. Two-phase tool (dry-run → operator disambiguation → commit). | Database operator |
-| `x-import` | Import an X (Twitter) Basic Data Export — tweet stream renders as one chronological transcript and ingests as a single `:KnowledgeDocument` (`source='x'`); each DM `sessionId` ingests as one `:ConversationArchive` (`source='x-dm'`, keyed on `conversationIdentity`) via `conversation-archive-ingest.sh`. Mentions, replies, and quote-tweet authors resolve to `:Person` on lowercased `xHandle`; every handle and DM senderId confirms against existing nodes (no auto-create). Per-thread KD granularity and `:Post` / `:DirectMessage` labels are explicitly rejected. | Database operator |
-| `substack-import` | Import a Substack "Export your data" archive — per-essay `:KnowledgeDocument {kind:'substack-post'}` via librarian/document-ingest with synthetic stable `attachmentId = "substack-post-${substackPostId}"` (survives Substack edits); one `:KnowledgeDocument {kind:'substack-subscriber-roster'}` per import run with `:MENTIONS {mentionContext:'substack-subscription', tier, totalOpens, totalClicks, lastOpenedAt, lastClickedAt, engagementWindowDays}` to each subscriber `:Person` MERGEd on `(accountId, email)`. Engagement aggregates parsed from `email_activity.csv` (or `subscriber_activity.csv` / `emails.csv`); overwrite-on-reimport. No new label, no new edge type, no new graph writer. Images attach via canonical `:HAS_ENCLOSURE` (or `:MENTIONS` fallback). Bulk-gate at >200 posts or >2000 subscribers. | Database operator |
+| `notion-import` | Import a Notion workspace export (markdown + CSV) — pages, databases, hierarchy, attachments, schema-bounded relations, `@person` mentions account-filtered | Librarian |
+| `obsidian-import` | Import an extracted Obsidian vault — pages map to `:KnowledgeDocument`, wikilinks resolve to intra-vault pages or existing entities, tags become `:DefinedTerm`, embedded images become `:DigitalDocument`. Two-phase tool (dry-run → operator disambiguation → commit). | Librarian |
+| `x-import` | Import an X (Twitter) Basic Data Export — tweet stream renders as one chronological transcript and ingests as a single `:KnowledgeDocument` (`source='x'`); each DM `sessionId` ingests as one `:ConversationArchive` (`source='x-dm'`, keyed on `conversationIdentity`) via `conversation-archive-ingest.sh`. Mentions, replies, and quote-tweet authors resolve to `:Person` on lowercased `xHandle`; every handle and DM senderId confirms against existing nodes (no auto-create). Per-thread KD granularity and `:Post` / `:DirectMessage` labels are explicitly rejected. | Librarian |
+| `substack-import` | Import a Substack "Export your data" archive — per-essay `:KnowledgeDocument {kind:'substack-post'}` via librarian/document-ingest with synthetic stable `attachmentId = "substack-post-${substackPostId}"` (survives Substack edits); one `:KnowledgeDocument {kind:'substack-subscriber-roster'}` per import run with `:MENTIONS {mentionContext:'substack-subscription', tier, totalOpens, totalClicks, lastOpenedAt, lastClickedAt, engagementWindowDays}` to each subscriber `:Person` MERGEd on `(accountId, email)`. Engagement aggregates parsed from `email_activity.csv` (or `subscriber_activity.csv` / `emails.csv`); overwrite-on-reimport. No new label, no new edge type, no new graph writer. Images attach via canonical `:HAS_ENCLOSURE` (or `:MENTIONS` fallback). Bulk-gate at >200 posts or >2000 subscribers. | Librarian |
 | `memory/skills/conversation-archive` | Source-agnostic conversation transcript ingest. One skill for WhatsApp `_chat.txt`, Telegram, Signal, LinkedIn DMs, Zoom transcript, meeting minutes, iMessage, Slack, X DMs — `--source <enum>` selects the per-source normaliser. Single Bash entry — `bash platform/plugins/memory/bin/conversation-archive-ingest.sh <archive> --source <enum> --participant-person-ids <csv> --scope <admin\|public>` — runs normalise → operator-confirms owner + every distinct sender (owner derived from env via Cypher, no flag) → sessionize at the fixed 8h gap → emit one JSON line carrying prepared sessions (turn-attributed text + per-session cursor). The dispatched specialist iterates the sessions in-turn, produces a typed-section JSON chunking for each, and calls the `memory-ingest` MCP tool with `conversationIdentity` set (writes `:ConversationArchive`, source=<enum>) once per session — chunks + cursor advance commit atomically inside one Cypher transaction, so a kill mid-archive resumes from the next session on re-issue without re-classifying anything already written. Re-imports are delta-append. Auto-creating participants is forbidden — any sender outside the operator-confirmed closed set LOUD-FAILs with `parser-miss`. Distinct from the live `whatsapp` plugin (Baileys). | Database operator |
 | `memory/skills/conversation-archive-enrich` | Phase 2 for any named `:ConversationArchive` — source-agnostic per-row insight derivation. Operator-triggered (never auto-fires on Phase 1 completion). Walks the parent's `:Section` chunks in pages via the read-only MCP tool `mcp__plugin_memory_memory__conversation-archive-list-chunks`; the dispatched specialist reads each chunk in-turn and emits claims under the four-kind contract (`mention`, `task`, `preference`, `observed-relationship`); the skill hands those claims to `mcp__plugin_memory_memory__conversation-archive-derive-insights` for per-kind cypher emission, then runs the per-row operator gate (`wire / skip / reject`). Idempotent on `(elementId(chunk), kind, contentHash)` — re-runs collapse identical claims. Confidence floor is a hedging-avoidance instruction the skill embeds in the specialist's per-chunk prompt, not a numeric post-filter; the LLM step runs in-turn from the dispatched specialist rather than as a server-side OAuth round-trip. | Database operator |
 
@@ -2290,6 +2290,18 @@ reserved for vertical / integration notes (LinkedIn extension,
 PropertyData, Real Agent standalone, MCP server inventory) — not for
 core-platform docs.
 
+## UI conventions
+
+**Icons are Lucide components only — no emoji.** Every glyph rendered in
+`platform/ui` JSX (the `/chat` web chat, the WhatsApp/channel readers, the
+admin shell, the `/data` grid) is a `lucide-react` component (e.g.
+`<Paperclip>`, `<FileText>`), never an emoji/emoticon character in the rendered
+string. The rule is enforced at build time by
+[`scripts/check-no-emoji-in-jsx.mjs`](../../../ui/scripts/check-no-emoji-in-jsx.mjs),
+which fails `prebuild` if any emoji codepoint appears in a `.ts`/`.tsx` file
+under `app/` (tests excluded). Inline an icon at the surrounding text size and
+colour (`size={14}` matches body text; Lucide inherits `currentColor`).
+
 ## Admin Hono routes
 
 Every admin sub-app is mounted by
@@ -2995,6 +3007,8 @@ If Ollama is unavailable at write time, the node is stored without an embedding
 
 The `memory-reindex` tool backfills missing embeddings by iterating nodes where `embedding IS NULL`. It uses the bounded representation (the `summary` for document/archive labels, never the raw body), embeds in batches with a per-node fallback on batch error, and **skips and continues** past a failing node — keeping skipped nodes out of the re-fetch via an exclude set — instead of aborting the whole run. `embed()`/`embedBatch()` cap oversized input (`EMBED_INPUT_MAX_CHARS`) before the Ollama POST, so a large body embeds truncated rather than throwing. Per-node `[reindex] op=embedded|skip-error` lines and a terminal `[reindex] op=done processed=N skipped=M`.
 
+`embedBatch()` also paces large batches. A document's summary plus every section body in one `/api/embed` POST pins ollama's `llama-server` across all cores for the whole batch with no idle gaps; on a passively-cooled Pi the SoC climbs past its soft-temp limit and the board thermally hard-resets. `embedBatch` splits an input array longer than `EMBED_SUBBATCH_SIZE` (default 32) into sub-batches, waiting `EMBED_SUBBATCH_COOLDOWN_MS` (default 1000) between them so the SoC gets cooling gaps; vectors are concatenated in input order. Both knobs are env-overridable for on-device tuning. The load-bearing thermal protection is the installer's `CPUQuota` cap on `ollama.service` (every embed caller is bounded there regardless of batch shape); this pacing is defence-in-depth. The UI's file-index path uses its own single-input embed client in `platform/ui/app/lib/neo4j-store.ts` (one embed per file, not a batch), so it is covered by the CPU cap, not by `embedBatch` pacing.
+
 ---
 
 ## Knowledge Document Hierarchy
@@ -3456,6 +3470,25 @@ Source: https://docs.getmaxy.com/deployment.md
 - Mac with macOS 14 (Sonoma) or newer — both Apple Silicon and Intel
 - 256GB storage minimum
 - Always-on power and network connection
+- **On a Pi 5: the official 27W USB-C power supply (5.1V / 5A) and a good cable.** This is not optional — see Power and recovery below.
+
+## Power and recovery (Raspberry Pi)
+
+A Pi 5 running Maxy draws hard during document ingest: the embedding model runs the CPU flat-out in bursts. An underpowered supply or a thin/long USB-C cable cannot hold 5V under that current spike, the board *browns out*, and you get one of two failures:
+
+- **A reset or freeze** — the board drops out mid-task and either reboots or hangs.
+- **A latched-off board** — the board goes dark and stays dark until you physically unplug and replug the power. No software can recover this, because there is no power to run any recovery.
+
+**The cure is hardware.** Use the official Raspberry Pi 5 27W PSU (5.1V / 5A) and a short, good-quality USB-C cable. A marginal phone charger or a cheap cable is the usual cause. This is the only thing that *prevents* a brownout.
+
+**Recovery seatbelts the installer sets up for you:**
+
+- **A hardware watchdog.** If the board *hangs* (powered but stuck), it reboots itself automatically within about two minutes — no manual power cycle. This only helps a hung board; it cannot help a board that has gone dark.
+- **Power-health logging.** The admin server writes a `[power-health]` line to `server.log` at boot and every 15 minutes, so a brownout shows up without waiting for a crash. A healthy line reads `throttled=0x0 ... undervolt_occurred=false`. Any `undervolt`-flag set, or `reboots_unclean_24h` above zero, means the board is browning out — fix the power before trusting it with heavy work.
+
+**For a board that latches off (the dark-board case):** put the Pi on a smart plug that you can power-cycle remotely, ideally one driven by a heartbeat (cut power and restore it when the box stops responding). This is the robust recovery for the dark-board failure and is an operator hardware choice, not something the installer can do.
+
+**Keep one address.** After a reboot the Pi can pick up a different DHCP address and look like it vanished. Add a **DHCP reservation** on your router that pins the Pi's MAC to a fixed LAN IP, so the box is always reachable at the same address. The boot `[power-health] op=boot lan_ip=<ip>` line records the address each boot — if it changes across reboots, the reservation is not in place.
 
 ## macOS install
 
@@ -3703,6 +3736,7 @@ A single Pi or laptop can host more than one brand (for example Maxy and Real Ag
 - **Brand-isolated Neo4j:** when a brand provisions a dedicated Neo4j instance (any port other than 7687), the installer stops and disables the apt-package's system `neo4j.service` after enabling the brand-dedicated unit, so only one Neo4j process holds the shared `/var/lib/neo4j/run/` PID file. The seed step receives the brand-correct `NEO4J_URI` and `NEO4J_PASSWORD` as explicit environment variables — the seed script no longer carries a `bolt://localhost:7687` default. A failed dedicated start aborts the install loudly with a journalctl tail; there is no silent fallback to the system instance. Stop/disable targets the literal `neo4j.service` only, so peer brands running their own `neo4j-{brand}.service` are unaffected.
 - **Peer-aware system-unit guard:** before stopping the system `neo4j.service`, the installer checks whether any other brand on the device still depends on it — that is, has `NEO4J_URI=bolt://localhost:7687` in its `~/.<peer>/.env`. If so, the system unit is left enabled and active, and the install log shows `[neo4j] system unit kept active — peer brand <name> depends on port 7687` instead of the usual `[neo4j] disabling system unit` line. This prevents a `create-realagent` install from disabling Maxy's database on a host where Maxy still uses the shared system instance (the earlier platform fixes reproducer on Neo's laptop, 2026-04-28). On single-brand hosts and on multi-brand hosts where every peer runs a dedicated port, behaviour is unchanged. The dedicated unit exports `NEO4J_HOME=<per-brand-data-dir>` alongside `NEO4J_CONF`, so `server.directories.run`, `server.directories.plugins`, and `server.directories.import` resolve per-brand — no collision with `/var/lib/neo4j/run/neo4j.pid`. The conf sed-overrides, mkdir-p, chown, and unit-write are idempotent and re-run on every install, so a host whose prior install left a broken unit recovers on retry.
 - **Shared:** both brands share the system Chromium/VNC stack, the Ollama model server, and the `cloudflared` command itself. Browser automation is serialised — one admin session at a time across both brands.
+- **Thermal cap on shared Ollama:** the installer writes a host-wide systemd `CPUQuota` drop-in (`/etc/systemd/system/ollama.service.d/10-maxy-cpuquota.conf`) bounding `ollama.service` to half the cores (200% on a 4-core Pi). An embedding burst — a document's summary plus every section body in one POST — otherwise pins `llama-server` across all cores with no idle gaps until a passively-cooled Pi crosses its soft-temp limit and hard-resets. The cap keeps peak temperature below the limit regardless of which brand or platform path issues the embeds. The drop-in has a neutral filename and is rewritten only when its content changes, so it is idempotent across brands and reinstalls. Applied only where the `ollama.service` system unit exists; a detached `ollama serve` has no unit to cap.
 
 To install a second brand on a device that already runs the first, just run the other installer. No flags needed for isolation:
 

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -25,6 +25,18 @@ reserved for vertical / integration notes (LinkedIn extension,
 PropertyData, Real Agent standalone, MCP server inventory) — not for
 core-platform docs.
 
+## UI conventions
+
+**Icons are Lucide components only — no emoji.** Every glyph rendered in
+`platform/ui` JSX (the `/chat` web chat, the WhatsApp/channel readers, the
+admin shell, the `/data` grid) is a `lucide-react` component (e.g.
+`<Paperclip>`, `<FileText>`), never an emoji/emoticon character in the rendered
+string. The rule is enforced at build time by
+[`scripts/check-no-emoji-in-jsx.mjs`](../../../ui/scripts/check-no-emoji-in-jsx.mjs),
+which fails `prebuild` if any emoji codepoint appears in a `.ts`/`.tsx` file
+under `app/` (tests excluded). Inline an icon at the surrounding text size and
+colour (`size={14}` matches body text; Lucide inherits `currentColor`).
+
 ## Admin Hono routes
 
 Every admin sub-app is mounted by

package/payload/platform/plugins/docs/references/deployment.md

@@ -6,6 +6,25 @@
 - Mac with macOS 14 (Sonoma) or newer — both Apple Silicon and Intel
 - 256GB storage minimum
 - Always-on power and network connection
+- **On a Pi 5: the official 27W USB-C power supply (5.1V / 5A) and a good cable.** This is not optional — see Power and recovery below.
+
+## Power and recovery (Raspberry Pi)
+
+A Pi 5 running {{productName}} draws hard during document ingest: the embedding model runs the CPU flat-out in bursts. An underpowered supply or a thin/long USB-C cable cannot hold 5V under that current spike, the board *browns out*, and you get one of two failures:
+
+- **A reset or freeze** — the board drops out mid-task and either reboots or hangs.
+- **A latched-off board** — the board goes dark and stays dark until you physically unplug and replug the power. No software can recover this, because there is no power to run any recovery.
+
+**The cure is hardware.** Use the official Raspberry Pi 5 27W PSU (5.1V / 5A) and a short, good-quality USB-C cable. A marginal phone charger or a cheap cable is the usual cause. This is the only thing that *prevents* a brownout.
+
+**Recovery seatbelts the installer sets up for you:**
+
+- **A hardware watchdog.** If the board *hangs* (powered but stuck), it reboots itself automatically within about two minutes — no manual power cycle. This only helps a hung board; it cannot help a board that has gone dark.
+- **Power-health logging.** The admin server writes a `[power-health]` line to `server.log` at boot and every 15 minutes, so a brownout shows up without waiting for a crash. A healthy line reads `throttled=0x0 ... undervolt_occurred=false`. Any `undervolt`-flag set, or `reboots_unclean_24h` above zero, means the board is browning out — fix the power before trusting it with heavy work.
+
+**For a board that latches off (the dark-board case):** put the Pi on a smart plug that you can power-cycle remotely, ideally one driven by a heartbeat (cut power and restore it when the box stops responding). This is the robust recovery for the dark-board failure and is an operator hardware choice, not something the installer can do.
+
+**Keep one address.** After a reboot the Pi can pick up a different DHCP address and look like it vanished. Add a **DHCP reservation** on your router that pins the Pi's MAC to a fixed LAN IP, so the box is always reachable at the same address. The boot `[power-health] op=boot lan_ip=<ip>` line records the address each boot — if it changes across reboots, the reservation is not in place.
 
 ## macOS install
 
@@ -253,6 +272,7 @@ A single Pi or laptop can host more than one brand (for example Maxy and Real Ag
 - **Brand-isolated Neo4j:** when a brand provisions a dedicated Neo4j instance (any port other than 7687), the installer stops and disables the apt-package's system `neo4j.service` after enabling the brand-dedicated unit, so only one Neo4j process holds the shared `/var/lib/neo4j/run/` PID file. The seed step receives the brand-correct `NEO4J_URI` and `NEO4J_PASSWORD` as explicit environment variables — the seed script no longer carries a `bolt://localhost:7687` default. A failed dedicated start aborts the install loudly with a journalctl tail; there is no silent fallback to the system instance. Stop/disable targets the literal `neo4j.service` only, so peer brands running their own `neo4j-{brand}.service` are unaffected.
 - **Peer-aware system-unit guard:** before stopping the system `neo4j.service`, the installer checks whether any other brand on the device still depends on it — that is, has `NEO4J_URI=bolt://localhost:7687` in its `~/.<peer>/.env`. If so, the system unit is left enabled and active, and the install log shows `[neo4j] system unit kept active — peer brand <name> depends on port 7687` instead of the usual `[neo4j] disabling system unit` line. This prevents a `create-realagent` install from disabling Maxy's database on a host where Maxy still uses the shared system instance (the earlier platform fixes reproducer on Neo's laptop, 2026-04-28). On single-brand hosts and on multi-brand hosts where every peer runs a dedicated port, behaviour is unchanged. The dedicated unit exports `NEO4J_HOME=<per-brand-data-dir>` alongside `NEO4J_CONF`, so `server.directories.run`, `server.directories.plugins`, and `server.directories.import` resolve per-brand — no collision with `/var/lib/neo4j/run/neo4j.pid`. The conf sed-overrides, mkdir-p, chown, and unit-write are idempotent and re-run on every install, so a host whose prior install left a broken unit recovers on retry.
 - **Shared:** both brands share the system Chromium/VNC stack, the Ollama model server, and the `cloudflared` command itself. Browser automation is serialised — one admin session at a time across both brands.
+- **Thermal cap on shared Ollama:** the installer writes a host-wide systemd `CPUQuota` drop-in (`/etc/systemd/system/ollama.service.d/10-maxy-cpuquota.conf`) bounding `ollama.service` to half the cores (200% on a 4-core Pi). An embedding burst — a document's summary plus every section body in one POST — otherwise pins `llama-server` across all cores with no idle gaps until a passively-cooled Pi crosses its soft-temp limit and hard-resets. The cap keeps peak temperature below the limit regardless of which brand or platform path issues the embeds. The drop-in has a neutral filename and is rewritten only when its content changes, so it is idempotent across brands and reinstalls. Applied only where the `ollama.service` system unit exists; a detached `ollama serve` has no unit to cap.
 
 To install a second brand on a device that already runs the first, just run the other installer. No flags needed for isolation:
 

package/payload/platform/plugins/docs/references/internals.md

@@ -95,6 +95,8 @@ If Ollama is unavailable at write time, the node is stored without an embedding
 
 The `memory-reindex` tool backfills missing embeddings by iterating nodes where `embedding IS NULL`. It uses the bounded representation (the `summary` for document/archive labels, never the raw body), embeds in batches with a per-node fallback on batch error, and **skips and continues** past a failing node — keeping skipped nodes out of the re-fetch via an exclude set — instead of aborting the whole run. `embed()`/`embedBatch()` cap oversized input (`EMBED_INPUT_MAX_CHARS`) before the Ollama POST, so a large body embeds truncated rather than throwing. Per-node `[reindex] op=embedded|skip-error` lines and a terminal `[reindex] op=done processed=N skipped=M`.
 
+`embedBatch()` also paces large batches. A document's summary plus every section body in one `/api/embed` POST pins ollama's `llama-server` across all cores for the whole batch with no idle gaps; on a passively-cooled Pi the SoC climbs past its soft-temp limit and the board thermally hard-resets. `embedBatch` splits an input array longer than `EMBED_SUBBATCH_SIZE` (default 32) into sub-batches, waiting `EMBED_SUBBATCH_COOLDOWN_MS` (default 1000) between them so the SoC gets cooling gaps; vectors are concatenated in input order. Both knobs are env-overridable for on-device tuning. The load-bearing thermal protection is the installer's `CPUQuota` cap on `ollama.service` (every embed caller is bounded there regardless of batch shape); this pacing is defence-in-depth. The UI's file-index path uses its own single-input embed client in `platform/ui/app/lib/neo4j-store.ts` (one embed per file, not a batch), so it is covered by the CPU cap, not by `embedBatch` pacing.
+
 ---
 
 ## Knowledge Document Hierarchy

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -43,10 +43,10 @@ These are enabled during onboarding and can be added or removed at any time. Som
 | `whatsapp` | WhatsApp messaging, pairing, and conversation browsing | Personal assistant |
 | `replicate` | Image generation — three models for photorealistic, design, and fast draft images | Content producer, Research assistant |
 | `linkedin-import` | Import a LinkedIn Basic Data Export — Profile and Connections today, more CSVs as references land | Database operator |
-| `notion-import` | Import a Notion workspace export (markdown + CSV) — pages, databases, hierarchy, attachments, schema-bounded relations, `@person` mentions account-filtered | Database operator |
-| `obsidian-import` | Import an extracted Obsidian vault — pages map to `:KnowledgeDocument`, wikilinks resolve to intra-vault pages or existing entities, tags become `:DefinedTerm`, embedded images become `:DigitalDocument`. Two-phase tool (dry-run → operator disambiguation → commit). | Database operator |
-| `x-import` | Import an X (Twitter) Basic Data Export — tweet stream renders as one chronological transcript and ingests as a single `:KnowledgeDocument` (`source='x'`); each DM `sessionId` ingests as one `:ConversationArchive` (`source='x-dm'`, keyed on `conversationIdentity`) via `conversation-archive-ingest.sh`. Mentions, replies, and quote-tweet authors resolve to `:Person` on lowercased `xHandle`; every handle and DM senderId confirms against existing nodes (no auto-create). Per-thread KD granularity and `:Post` / `:DirectMessage` labels are explicitly rejected. | Database operator |
-| `substack-import` | Import a Substack "Export your data" archive — per-essay `:KnowledgeDocument {kind:'substack-post'}` via librarian/document-ingest with synthetic stable `attachmentId = "substack-post-${substackPostId}"` (survives Substack edits); one `:KnowledgeDocument {kind:'substack-subscriber-roster'}` per import run with `:MENTIONS {mentionContext:'substack-subscription', tier, totalOpens, totalClicks, lastOpenedAt, lastClickedAt, engagementWindowDays}` to each subscriber `:Person` MERGEd on `(accountId, email)`. Engagement aggregates parsed from `email_activity.csv` (or `subscriber_activity.csv` / `emails.csv`); overwrite-on-reimport. No new label, no new edge type, no new graph writer. Images attach via canonical `:HAS_ENCLOSURE` (or `:MENTIONS` fallback). Bulk-gate at >200 posts or >2000 subscribers. | Database operator |
+| `notion-import` | Import a Notion workspace export (markdown + CSV) — pages, databases, hierarchy, attachments, schema-bounded relations, `@person` mentions account-filtered | Librarian |
+| `obsidian-import` | Import an extracted Obsidian vault — pages map to `:KnowledgeDocument`, wikilinks resolve to intra-vault pages or existing entities, tags become `:DefinedTerm`, embedded images become `:DigitalDocument`. Two-phase tool (dry-run → operator disambiguation → commit). | Librarian |
+| `x-import` | Import an X (Twitter) Basic Data Export — tweet stream renders as one chronological transcript and ingests as a single `:KnowledgeDocument` (`source='x'`); each DM `sessionId` ingests as one `:ConversationArchive` (`source='x-dm'`, keyed on `conversationIdentity`) via `conversation-archive-ingest.sh`. Mentions, replies, and quote-tweet authors resolve to `:Person` on lowercased `xHandle`; every handle and DM senderId confirms against existing nodes (no auto-create). Per-thread KD granularity and `:Post` / `:DirectMessage` labels are explicitly rejected. | Librarian |
+| `substack-import` | Import a Substack "Export your data" archive — per-essay `:KnowledgeDocument {kind:'substack-post'}` via librarian/document-ingest with synthetic stable `attachmentId = "substack-post-${substackPostId}"` (survives Substack edits); one `:KnowledgeDocument {kind:'substack-subscriber-roster'}` per import run with `:MENTIONS {mentionContext:'substack-subscription', tier, totalOpens, totalClicks, lastOpenedAt, lastClickedAt, engagementWindowDays}` to each subscriber `:Person` MERGEd on `(accountId, email)`. Engagement aggregates parsed from `email_activity.csv` (or `subscriber_activity.csv` / `emails.csv`); overwrite-on-reimport. No new label, no new edge type, no new graph writer. Images attach via canonical `:HAS_ENCLOSURE` (or `:MENTIONS` fallback). Bulk-gate at >200 posts or >2000 subscribers. | Librarian |
 | `memory/skills/conversation-archive` | Source-agnostic conversation transcript ingest. One skill for WhatsApp `_chat.txt`, Telegram, Signal, LinkedIn DMs, Zoom transcript, meeting minutes, iMessage, Slack, X DMs — `--source <enum>` selects the per-source normaliser. Single Bash entry — `bash platform/plugins/memory/bin/conversation-archive-ingest.sh <archive> --source <enum> --participant-person-ids <csv> --scope <admin\|public>` — runs normalise → operator-confirms owner + every distinct sender (owner derived from env via Cypher, no flag) → sessionize at the fixed 8h gap → emit one JSON line carrying prepared sessions (turn-attributed text + per-session cursor). The dispatched specialist iterates the sessions in-turn, produces a typed-section JSON chunking for each, and calls the `memory-ingest` MCP tool with `conversationIdentity` set (writes `:ConversationArchive`, source=<enum>) once per session — chunks + cursor advance commit atomically inside one Cypher transaction, so a kill mid-archive resumes from the next session on re-issue without re-classifying anything already written. Re-imports are delta-append. Auto-creating participants is forbidden — any sender outside the operator-confirmed closed set LOUD-FAILs with `parser-miss`. Distinct from the live `whatsapp` plugin (Baileys). | Database operator |
 | `memory/skills/conversation-archive-enrich` | Phase 2 for any named `:ConversationArchive` — source-agnostic per-row insight derivation. Operator-triggered (never auto-fires on Phase 1 completion). Walks the parent's `:Section` chunks in pages via the read-only MCP tool `mcp__plugin_memory_memory__conversation-archive-list-chunks`; the dispatched specialist reads each chunk in-turn and emits claims under the four-kind contract (`mention`, `task`, `preference`, `observed-relationship`); the skill hands those claims to `mcp__plugin_memory_memory__conversation-archive-derive-insights` for per-kind cypher emission, then runs the per-row operator gate (`wire / skip / reject`). Idempotent on `(elementId(chunk), kind, contentHash)` — re-runs collapse identical claims. Confidence floor is a hedging-avoidance instruction the skill embeds in the specialist's per-chunk prompt, not a numeric post-filter; the LLM step runs in-turn from the dispatched specialist rather than as a server-side OAuth round-trip. | Database operator |
 

package/payload/platform/plugins/memory/PLUGIN.md

@@ -129,7 +129,6 @@ hidden:
   - session-compact
   - session-compact-status
   - image-fetch
-  - memory-typed-edge-pass
 skills:
   - skills/conversational-memory/SKILL.md
   - skills/document-ingest/SKILL.md