@rubytech/create-maxy-code 0.1.427 → 0.1.431

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.427",
+  "version": "0.1.431",
   "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,6 +1,10 @@
-export declare const EMBED_INPUT_MAX_CHARS = 8000;
+export declare const EMBED_INPUT_MAX_CHARS: number;
 export declare const EMBED_SUBBATCH_SIZE: number;
 export declare const EMBED_SUBBATCH_COOLDOWN_MS: number;
+export declare const EMBED_MS_PER_INPUT: number;
+export declare const EMBED_REQUEST_TIMEOUT_MS: number;
+export declare const EMBED_KEEP_ALIVE: number | string;
 export declare function embed(text: string): Promise<number[]>;
+export declare function effectiveSubBatchSize(): 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;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA4BA,eAAO,MAAM,qBAAqB,QASjC,CAAC;AAaF,eAAO,MAAM,mBAAmB,QAA6D,CAAC;AAC9F,eAAO,MAAM,0BAA0B,QAGtC,CAAC;AAWF,eAAO,MAAM,kBAAkB,QAA8D,CAAC;AAQ9F,eAAO,MAAM,wBAAwB,QAGpC,CAAC;AAcF,eAAO,MAAM,gBAAgB,EAAE,MAAM,GAAG,MAEhB,CAAC;AA8EzB,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAG3D;AAKD,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAqBrE"}

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

@@ -6,16 +6,32 @@
 // 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_SUBBATCH_COOLDOWN_MS = exports.EMBED_SUBBATCH_SIZE = exports.EMBED_INPUT_MAX_CHARS = void 0;
+exports.EMBED_KEEP_ALIVE = exports.EMBED_REQUEST_TIMEOUT_MS = exports.EMBED_MS_PER_INPUT = exports.EMBED_SUBBATCH_COOLDOWN_MS = exports.EMBED_SUBBATCH_SIZE = exports.EMBED_INPUT_MAX_CHARS = void 0;
 exports.embed = embed;
+exports.effectiveSubBatchSize = effectiveSubBatchSize;
 exports.embedBatch = embedBatch;
 const OLLAMA_URL = process.env.OLLAMA_URL ?? "http://localhost:11434";
 const EMBED_MODEL = process.env.EMBED_MODEL ?? "nomic-embed-text";
-// nomic-embed-text has a 2048-token context (~8k chars at ~4 chars/token).
-// An over-limit input makes the Ollama embed endpoint error; cap defensively so
-// an oversized body embeds (truncated) instead of throwing and aborting the
-// caller.
-exports.EMBED_INPUT_MAX_CHARS = 8000;
+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;
+}
+// nomic-embed-text's usable embed context is 2048 tokens. The old 8000-char cap
+// assumed ~4 chars/token, but dense emoji/markup content runs richer, so a
+// section that passed the char cap still errored with "input length exceeds the
+// context length". Size the default against a conservative 3 chars/token worst
+// case, reserving a small token margin for the tokenizer's specials, so a capped
+// input is provably under context: (2048 - 48) * 3 = 6000. Context is
+// env-overridable so raising it raises the cap; EMBED_INPUT_MAX_CHARS is also
+// directly overridable.
+const EMBED_MODEL_CONTEXT_TOKENS = Math.max(1, Math.floor(envInt("EMBED_MODEL_CONTEXT_TOKENS", 2048)));
+const EMBED_CONTEXT_MARGIN_TOKENS = 48;
+const EMBED_WORST_CASE_CHARS_PER_TOKEN = 3;
+exports.EMBED_INPUT_MAX_CHARS = Math.max(1, Math.floor(envInt("EMBED_INPUT_MAX_CHARS", (EMBED_MODEL_CONTEXT_TOKENS - EMBED_CONTEXT_MARGIN_TOKENS) *
+    EMBED_WORST_CASE_CHARS_PER_TOKEN)));
 // 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
@@ -27,15 +43,39 @@ exports.EMBED_INPUT_MAX_CHARS = 8000;
 // 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));
+// Throughput-aware sub-batch sizing (Task 1533). On a CPU-only embedder each
+// input takes ~EMBED_MS_PER_INPUT ms; a fixed 32-input POST at the char cap is
+// ~128 s, past the 120 s request timeout, so a full-document batch aborts and
+// the atomic ingest write lands nothing. Bound each POST to 80% of the timeout
+// so it provably completes: derive a duration ceiling and take the smaller of
+// it and the count ceiling (EMBED_SUBBATCH_SIZE, Task 960's thermal cap).
+// EMBED_MS_PER_INPUT is the budgeted worst-case wall-time for one input at the
+// EMBED_INPUT_MAX_CHARS cap on the measured device; env-tunable for other
+// hardware.
+exports.EMBED_MS_PER_INPUT = Math.max(1, Math.floor(envInt("EMBED_MS_PER_INPUT", 6000)));
+const EMBED_TIMEOUT_UTILISATION = 0.8;
+// Explicit per-request timeout, well under undici's 300000ms headers default.
+// Without it a slow or wedged ollama returns no headers and the caller hangs a
+// silent 5 minutes before a bare `fetch failed`. With it the request aborts in
+// seconds and throws a cause-naming error instead. Env-overridable for
+// on-device tuning.
+exports.EMBED_REQUEST_TIMEOUT_MS = Math.max(1, Math.floor(envInt("EMBED_REQUEST_TIMEOUT_MS", 120000)));
+// Model warmth (Task 1533). Keep the embed model resident so an interactive
+// graph query-embed never cold-loads (~10 s) and blows its 5 s timeout, and so
+// a query issued while an ingest runs embeds warm instead of degrading to BM25.
+// Ollama's keep_alive accepts a number (seconds; -1 = keep forever) or a
+// duration string ("30m"). Pass a numeric value through as a number so "-1" is
+// the keep-forever sentinel rather than an unparseable duration string.
+// Treat an empty-string env as unset (matches envInt above), so
+// `EMBED_KEEP_ALIVE=` does not send an empty keep_alive that Ollama rejects.
+const EMBED_KEEP_ALIVE_RAW = process.env.EMBED_KEEP_ALIVE === undefined || process.env.EMBED_KEEP_ALIVE === ""
+    ? "-1"
+    : process.env.EMBED_KEEP_ALIVE;
+exports.EMBED_KEEP_ALIVE = /^-?\d+$/.test(EMBED_KEEP_ALIVE_RAW)
+    ? Number(EMBED_KEEP_ALIVE_RAW)
+    : EMBED_KEEP_ALIVE_RAW;
 function capInput(text) {
     if (text.length <= exports.EMBED_INPUT_MAX_CHARS)
         return text;
@@ -43,49 +83,87 @@ function capInput(text) {
     return text.slice(0, exports.EMBED_INPUT_MAX_CHARS);
 }
 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: inputs }),
-    });
+// One POST to the embed endpoint for an already-capped input (a single string
+// for embed(), an array for a sub-batch). Both paths route through here so the
+// timeout and the cause-naming error apply on every embed call. The wire shape
+// of `input` is preserved (string vs array) so the ollama request is unchanged.
+// On timeout or failure the error's first line names the cause (timeout vs HTTP
+// status), the input count, and the largest input size, so a slow or failing
+// ollama is legible immediately rather than after a 5-minute silent hang.
+async function embedRequest(input) {
+    const inputs = Array.isArray(input) ? input : [input];
+    const maxChars = inputs.reduce((m, s) => Math.max(m, s.length), 0);
+    const target = `${OLLAMA_URL}/api/embed`;
+    const startedAt = Date.now();
+    let res;
+    try {
+        res = await fetch(target, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ model: EMBED_MODEL, input, keep_alive: exports.EMBED_KEEP_ALIVE }),
+            signal: AbortSignal.timeout(exports.EMBED_REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        const name = err instanceof Error ? err.name : "";
+        if (name === "TimeoutError" || name === "AbortError") {
+            process.stderr.write(`[embed] op=timeout ms=${exports.EMBED_REQUEST_TIMEOUT_MS} inputs=${inputs.length} maxChars=${maxChars}\n`);
+            throw new Error(`Ollama embed request timed out after ${exports.EMBED_REQUEST_TIMEOUT_MS}ms (inputs=${inputs.length}, largestInputChars=${maxChars}) at ${target}; ollama did not respond in time (slow, cold-loading, or CPU-saturated). Raise EMBED_REQUEST_TIMEOUT_MS or check ollama.`);
+        }
+        // undici throws TypeError("fetch failed", { cause }) on a connection error
+        // (ollama down, refused, DNS). The legible cause is on err.cause, not the
+        // "fetch failed" message, so name it so "network is down" reads distinctly
+        // from "ollama is slow".
+        let detail = err instanceof Error ? err.message : String(err);
+        const cause = err instanceof Error ? err.cause : undefined;
+        if (cause !== undefined) {
+            detail += `: ${cause instanceof Error ? cause.message : String(cause)}`;
+        }
+        throw new Error(`Ollama embed request failed (inputs=${inputs.length}, largestInputChars=${maxChars}) at ${target}: ${detail}`);
+    }
     if (!res.ok) {
         const body = await res.text();
-        throw new Error(`Ollama batch embedding failed (${res.status}): ${body}`);
+        throw new Error(`Ollama embed request failed (HTTP ${res.status}, inputs=${inputs.length}, largestInputChars=${maxChars}): ${body}`);
     }
     const data = (await res.json());
+    // Per-POST breadcrumb (Task 1533). One line per successful POST so an
+    // oversized or slow sub-batch is visible before it times out and the
+    // throughput-aware sizing is verifiable from the log. inputs is the POST's
+    // sub-batch size; maxChars its largest input.
+    process.stderr.write(`[embed] op=post inputs=${inputs.length} maxChars=${maxChars} ms=${Date.now() - startedAt}\n`);
     return data.embeddings;
 }
+// POST one already-capped sub-batch of inputs to the embed endpoint.
+async function postBatch(inputs) {
+    return embedRequest(inputs);
+}
 async function embed(text) {
-    const input = capInput(text);
-    const res = await fetch(`${OLLAMA_URL}/api/embed`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ model: EMBED_MODEL, input }),
-    });
-    if (!res.ok) {
-        const body = await res.text();
-        throw new Error(`Ollama embedding failed (${res.status}): ${body}`);
-    }
-    const data = (await res.json());
-    return data.embeddings[0];
+    const data = await embedRequest(capInput(text));
+    return data[0];
+}
+// The POST size actually used by embedBatch: the smaller of the count ceiling
+// (thermal, Task 960) and the duration ceiling (throughput, Task 1533). At
+// defaults: min(32, floor(120000*0.8/6000)) = min(32, 16) = 16.
+function effectiveSubBatchSize() {
+    const durationCap = Math.max(1, Math.floor((exports.EMBED_REQUEST_TIMEOUT_MS * EMBED_TIMEOUT_UTILISATION) / exports.EMBED_MS_PER_INPUT));
+    return Math.min(exports.EMBED_SUBBATCH_SIZE, durationCap);
 }
 async function embedBatch(texts) {
     const inputs = texts.map(capInput);
+    const subBatch = effectiveSubBatchSize();
     // Common case — an array within the sub-batch size is one POST, unchanged.
-    if (inputs.length <= exports.EMBED_SUBBATCH_SIZE) {
+    if (inputs.length <= subBatch) {
         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) {
+    for (let i = 0; i < inputs.length; i += subBatch) {
         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);
+        const chunk = inputs.slice(i, i + subBatch);
         out.push(...(await postBatch(chunk)));
     }
     return out;

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"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;;;AAqKhD,sBAGC;AAKD,sDAMC;AAED,gCAqBC;AAxMD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,wBAAwB,CAAC;AACtE,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,kBAAkB,CAAC;AAElE,SAAS,MAAM,CAAC,IAAY,EAAE,GAAW;IACvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,GAAG,CAAC;IAChD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACtC,CAAC;AAED,gFAAgF;AAChF,2EAA2E;AAC3E,gFAAgF;AAChF,+EAA+E;AAC/E,iFAAiF;AACjF,sEAAsE;AACtE,8EAA8E;AAC9E,wBAAwB;AACxB,MAAM,0BAA0B,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,4BAA4B,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AACvG,MAAM,2BAA2B,GAAG,EAAE,CAAC;AACvC,MAAM,gCAAgC,GAAG,CAAC,CAAC;AAC9B,QAAA,qBAAqB,GAAG,IAAI,CAAC,GAAG,CAC3C,CAAC,EACD,IAAI,CAAC,KAAK,CACR,MAAM,CACJ,uBAAuB,EACvB,CAAC,0BAA0B,GAAG,2BAA2B,CAAC;IACxD,gCAAgC,CACnC,CACF,CACF,CAAC;AAEF,uEAAuE;AACvE,0EAA0E;AAC1E,4EAA4E;AAC5E,2EAA2E;AAC3E,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,8EAA8E;AAC9E,sEAAsE;AACtE,sEAAsE;AACtE,qCAAqC;AACxB,QAAA,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AACjF,QAAA,0BAA0B,GAAG,IAAI,CAAC,GAAG,CAChD,CAAC,EACD,MAAM,CAAC,4BAA4B,EAAE,IAAI,CAAC,CAC3C,CAAC;AAEF,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,0EAA0E;AAC1E,+EAA+E;AAC/E,0EAA0E;AAC1E,YAAY;AACC,QAAA,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9F,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAEtC,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,uEAAuE;AACvE,oBAAoB;AACP,QAAA,wBAAwB,GAAG,IAAI,CAAC,GAAG,CAC9C,CAAC,EACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,0BAA0B,EAAE,MAAM,CAAC,CAAC,CACvD,CAAC;AAEF,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,yEAAyE;AACzE,+EAA+E;AAC/E,wEAAwE;AACxE,gEAAgE;AAChE,6EAA6E;AAC7E,MAAM,oBAAoB,GACxB,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,EAAE;IAC/E,CAAC,CAAC,IAAI;IACN,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;AACtB,QAAA,gBAAgB,GAAoB,SAAS,CAAC,IAAI,CAAC,oBAAoB,CAAC;IACnF,CAAC,CAAC,MAAM,CAAC,oBAAoB,CAAC;IAC9B,CAAC,CAAC,oBAAoB,CAAC;AAEzB,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;AAED,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAC1C,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAEpD,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,0EAA0E;AAC1E,KAAK,UAAU,YAAY,CAAC,KAAwB;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,GAAG,UAAU,YAAY,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,wBAAgB,EAAE,CAAC;YACjF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gCAAwB,CAAC;SACtD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,IAAI,IAAI,KAAK,cAAc,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;YACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yBAAyB,gCAAwB,WAAW,MAAM,CAAC,MAAM,aAAa,QAAQ,IAAI,CACnG,CAAC;YACF,MAAM,IAAI,KAAK,CACb,wCAAwC,gCAAwB,cAAc,MAAM,CAAC,MAAM,uBAAuB,QAAQ,QAAQ,MAAM,0HAA0H,CACnQ,CAAC;QACJ,CAAC;QACD,2EAA2E;QAC3E,0EAA0E;QAC1E,2EAA2E;QAC3E,yBAAyB;QACzB,IAAI,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAE,GAA2B,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACpF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1E,CAAC;QACD,MAAM,IAAI,KAAK,CACb,uCAAuC,MAAM,CAAC,MAAM,uBAAuB,QAAQ,QAAQ,MAAM,KAAK,MAAM,EAAE,CAC/G,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,qCAAqC,GAAG,CAAC,MAAM,YAAY,MAAM,CAAC,MAAM,uBAAuB,QAAQ,MAAM,IAAI,EAAE,CACpH,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA+B,CAAC;IAC9D,sEAAsE;IACtE,qEAAqE;IACrE,2EAA2E;IAC3E,8CAA8C;IAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0BAA0B,MAAM,CAAC,MAAM,aAAa,QAAQ,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,CAC9F,CAAC;IACF,OAAO,IAAI,CAAC,UAAU,CAAC;AACzB,CAAC;AAED,qEAAqE;AACrE,KAAK,UAAU,SAAS,CAAC,MAAgB;IACvC,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAEM,KAAK,UAAU,KAAK,CAAC,IAAY;IACtC,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,2EAA2E;AAC3E,gEAAgE;AAChE,SAAgB,qBAAqB;IACnC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,CAAC,EACD,IAAI,CAAC,KAAK,CAAC,CAAC,gCAAwB,GAAG,yBAAyB,CAAC,GAAG,0BAAkB,CAAC,CACxF,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,CAAC,2BAAmB,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC;AAEM,KAAK,UAAU,UAAU,CAAC,KAAe;IAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;IAEzC,2EAA2E;IAC3E,IAAI,MAAM,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,yEAAyE;IACzE,2EAA2E;IAC3E,uDAAuD;IACvD,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC;QACjD,IAAI,CAAC,GAAG,CAAC,IAAI,kCAA0B,GAAG,CAAC,EAAE,CAAC;YAC5C,MAAM,KAAK,CAAC,kCAA0B,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC5C,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

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

@@ -8,11 +8,34 @@
 const OLLAMA_URL = process.env.OLLAMA_URL ?? "http://localhost:11434";
 const EMBED_MODEL = process.env.EMBED_MODEL ?? "nomic-embed-text";
 
-// nomic-embed-text has a 2048-token context (~8k chars at ~4 chars/token).
-// An over-limit input makes the Ollama embed endpoint error; cap defensively so
-// an oversized body embeds (truncated) instead of throwing and aborting the
-// caller.
-export const EMBED_INPUT_MAX_CHARS = 8000;
+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;
+}
+
+// nomic-embed-text's usable embed context is 2048 tokens. The old 8000-char cap
+// assumed ~4 chars/token, but dense emoji/markup content runs richer, so a
+// section that passed the char cap still errored with "input length exceeds the
+// context length". Size the default against a conservative 3 chars/token worst
+// case, reserving a small token margin for the tokenizer's specials, so a capped
+// input is provably under context: (2048 - 48) * 3 = 6000. Context is
+// env-overridable so raising it raises the cap; EMBED_INPUT_MAX_CHARS is also
+// directly overridable.
+const EMBED_MODEL_CONTEXT_TOKENS = Math.max(1, Math.floor(envInt("EMBED_MODEL_CONTEXT_TOKENS", 2048)));
+const EMBED_CONTEXT_MARGIN_TOKENS = 48;
+const EMBED_WORST_CASE_CHARS_PER_TOKEN = 3;
+export const EMBED_INPUT_MAX_CHARS = Math.max(
+  1,
+  Math.floor(
+    envInt(
+      "EMBED_INPUT_MAX_CHARS",
+      (EMBED_MODEL_CONTEXT_TOKENS - EMBED_CONTEXT_MARGIN_TOKENS) *
+        EMBED_WORST_CASE_CHARS_PER_TOKEN,
+    ),
+  ),
+);
 
 // 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
@@ -25,18 +48,50 @@ export const EMBED_INPUT_MAX_CHARS = 8000;
 // 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),
 );
 
+// Throughput-aware sub-batch sizing (Task 1533). On a CPU-only embedder each
+// input takes ~EMBED_MS_PER_INPUT ms; a fixed 32-input POST at the char cap is
+// ~128 s, past the 120 s request timeout, so a full-document batch aborts and
+// the atomic ingest write lands nothing. Bound each POST to 80% of the timeout
+// so it provably completes: derive a duration ceiling and take the smaller of
+// it and the count ceiling (EMBED_SUBBATCH_SIZE, Task 960's thermal cap).
+// EMBED_MS_PER_INPUT is the budgeted worst-case wall-time for one input at the
+// EMBED_INPUT_MAX_CHARS cap on the measured device; env-tunable for other
+// hardware.
+export const EMBED_MS_PER_INPUT = Math.max(1, Math.floor(envInt("EMBED_MS_PER_INPUT", 6000)));
+const EMBED_TIMEOUT_UTILISATION = 0.8;
+
+// Explicit per-request timeout, well under undici's 300000ms headers default.
+// Without it a slow or wedged ollama returns no headers and the caller hangs a
+// silent 5 minutes before a bare `fetch failed`. With it the request aborts in
+// seconds and throws a cause-naming error instead. Env-overridable for
+// on-device tuning.
+export const EMBED_REQUEST_TIMEOUT_MS = Math.max(
+  1,
+  Math.floor(envInt("EMBED_REQUEST_TIMEOUT_MS", 120000)),
+);
+
+// Model warmth (Task 1533). Keep the embed model resident so an interactive
+// graph query-embed never cold-loads (~10 s) and blows its 5 s timeout, and so
+// a query issued while an ingest runs embeds warm instead of degrading to BM25.
+// Ollama's keep_alive accepts a number (seconds; -1 = keep forever) or a
+// duration string ("30m"). Pass a numeric value through as a number so "-1" is
+// the keep-forever sentinel rather than an unparseable duration string.
+// Treat an empty-string env as unset (matches envInt above), so
+// `EMBED_KEEP_ALIVE=` does not send an empty keep_alive that Ollama rejects.
+const EMBED_KEEP_ALIVE_RAW =
+  process.env.EMBED_KEEP_ALIVE === undefined || process.env.EMBED_KEEP_ALIVE === ""
+    ? "-1"
+    : process.env.EMBED_KEEP_ALIVE;
+export const EMBED_KEEP_ALIVE: number | string = /^-?\d+$/.test(EMBED_KEEP_ALIVE_RAW)
+  ? Number(EMBED_KEEP_ALIVE_RAW)
+  : EMBED_KEEP_ALIVE_RAW;
+
 function capInput(text: string): string {
   if (text.length <= EMBED_INPUT_MAX_CHARS) return text;
   process.stderr.write(
@@ -48,41 +103,93 @@ function capInput(text: string): string {
 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: inputs }),
-  });
+// One POST to the embed endpoint for an already-capped input (a single string
+// for embed(), an array for a sub-batch). Both paths route through here so the
+// timeout and the cause-naming error apply on every embed call. The wire shape
+// of `input` is preserved (string vs array) so the ollama request is unchanged.
+// On timeout or failure the error's first line names the cause (timeout vs HTTP
+// status), the input count, and the largest input size, so a slow or failing
+// ollama is legible immediately rather than after a 5-minute silent hang.
+async function embedRequest(input: string | string[]): Promise<number[][]> {
+  const inputs = Array.isArray(input) ? input : [input];
+  const maxChars = inputs.reduce((m, s) => Math.max(m, s.length), 0);
+  const target = `${OLLAMA_URL}/api/embed`;
+  const startedAt = Date.now();
+  let res: Response;
+  try {
+    res = await fetch(target, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model: EMBED_MODEL, input, keep_alive: EMBED_KEEP_ALIVE }),
+      signal: AbortSignal.timeout(EMBED_REQUEST_TIMEOUT_MS),
+    });
+  } catch (err) {
+    const name = err instanceof Error ? err.name : "";
+    if (name === "TimeoutError" || name === "AbortError") {
+      process.stderr.write(
+        `[embed] op=timeout ms=${EMBED_REQUEST_TIMEOUT_MS} inputs=${inputs.length} maxChars=${maxChars}\n`,
+      );
+      throw new Error(
+        `Ollama embed request timed out after ${EMBED_REQUEST_TIMEOUT_MS}ms (inputs=${inputs.length}, largestInputChars=${maxChars}) at ${target}; ollama did not respond in time (slow, cold-loading, or CPU-saturated). Raise EMBED_REQUEST_TIMEOUT_MS or check ollama.`,
+      );
+    }
+    // undici throws TypeError("fetch failed", { cause }) on a connection error
+    // (ollama down, refused, DNS). The legible cause is on err.cause, not the
+    // "fetch failed" message, so name it so "network is down" reads distinctly
+    // from "ollama is slow".
+    let detail = err instanceof Error ? err.message : String(err);
+    const cause = err instanceof Error ? (err as { cause?: unknown }).cause : undefined;
+    if (cause !== undefined) {
+      detail += `: ${cause instanceof Error ? cause.message : String(cause)}`;
+    }
+    throw new Error(
+      `Ollama embed request failed (inputs=${inputs.length}, largestInputChars=${maxChars}) at ${target}: ${detail}`,
+    );
+  }
   if (!res.ok) {
     const body = await res.text();
-    throw new Error(`Ollama batch embedding failed (${res.status}): ${body}`);
+    throw new Error(
+      `Ollama embed request failed (HTTP ${res.status}, inputs=${inputs.length}, largestInputChars=${maxChars}): ${body}`,
+    );
   }
   const data = (await res.json()) as { embeddings: number[][] };
+  // Per-POST breadcrumb (Task 1533). One line per successful POST so an
+  // oversized or slow sub-batch is visible before it times out and the
+  // throughput-aware sizing is verifiable from the log. inputs is the POST's
+  // sub-batch size; maxChars its largest input.
+  process.stderr.write(
+    `[embed] op=post inputs=${inputs.length} maxChars=${maxChars} ms=${Date.now() - startedAt}\n`,
+  );
   return data.embeddings;
 }
 
+// POST one already-capped sub-batch of inputs to the embed endpoint.
+async function postBatch(inputs: string[]): Promise<number[][]> {
+  return embedRequest(inputs);
+}
+
 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" },
-    body: JSON.stringify({ model: EMBED_MODEL, input }),
-  });
-  if (!res.ok) {
-    const body = await res.text();
-    throw new Error(`Ollama embedding failed (${res.status}): ${body}`);
-  }
-  const data = (await res.json()) as { embeddings: number[][] };
-  return data.embeddings[0];
+  const data = await embedRequest(capInput(text));
+  return data[0];
+}
+
+// The POST size actually used by embedBatch: the smaller of the count ceiling
+// (thermal, Task 960) and the duration ceiling (throughput, Task 1533). At
+// defaults: min(32, floor(120000*0.8/6000)) = min(32, 16) = 16.
+export function effectiveSubBatchSize(): number {
+  const durationCap = Math.max(
+    1,
+    Math.floor((EMBED_REQUEST_TIMEOUT_MS * EMBED_TIMEOUT_UTILISATION) / EMBED_MS_PER_INPUT),
+  );
+  return Math.min(EMBED_SUBBATCH_SIZE, durationCap);
 }
 
 export async function embedBatch(texts: string[]): Promise<number[][]> {
   const inputs = texts.map(capInput);
+  const subBatch = effectiveSubBatchSize();
 
   // Common case — an array within the sub-batch size is one POST, unchanged.
-  if (inputs.length <= EMBED_SUBBATCH_SIZE) {
+  if (inputs.length <= subBatch) {
     return postBatch(inputs);
   }
 
@@ -90,11 +197,11 @@ export async function embedBatch(texts: string[]): Promise<number[][]> {
   // 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) {
+  for (let i = 0; i < inputs.length; i += subBatch) {
     if (i > 0 && EMBED_SUBBATCH_COOLDOWN_MS > 0) {
       await sleep(EMBED_SUBBATCH_COOLDOWN_MS);
     }
-    const chunk = inputs.slice(i, i + EMBED_SUBBATCH_SIZE);
+    const chunk = inputs.slice(i, i + subBatch);
     out.push(...(await postBatch(chunk)));
   }
   return out;

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:a557577a5292537ca408682f87fd5ab625194fc595602a4f2e886088d1ae40c1
+content-hash: sha256:a90edd8c9297c7c033814a6b4892c5d2550ffbda700d27f74a6ee58e70101af2
 brand: maxy-code
 product-name: Maxy
 ---
@@ -554,6 +554,72 @@ Omit the target and each tool acts on the session's own account, exactly like th
 
 A standing background check reconciles live sessions against the account roles and raises an alarm if any session still holds house authority for an account that is no longer the house account, so a stale grant cannot sit unnoticed. Each cross-account tool call also records its decision — who called, which account it targeted, whether it was allowed, and why — before it touches the graph or disk, and a rejected filesystem path escape is recorded on its own line. In normal operation neither an allowed cross-account call from a non-house session nor a path escape ever appears.
 
+---
+# Workflows Guide
+Source: https://docs.getmaxy.com/workflows.md
+
+# Workflows Guide
+
+## What a Workflow Is
+
+A workflow is a saved, named sequence of steps that Maxy runs for you on demand. Each step calls one tool, and steps can pass their results to later steps. Use a workflow when you have a recurring process with two or more steps that you would otherwise ask for by hand every time. A single one-off action does not need a workflow.
+
+Examples of good workflows:
+
+- "When a new lead comes in, create a contact, log it, and send me a notification."
+- "Every time I book a viewing, add the calendar event and message the client the details."
+
+## Creating a Workflow
+
+Describe the process to Maxy naturally:
+
+- "Set up a workflow: when I get a new lead, create the contact and send a Telegram notification."
+- "Make a follow-up workflow that adds a calendar reminder and drafts an email."
+
+Maxy will confirm the name, the steps, and how data flows between them before saving. If a step needs a tool from a plugin you have not installed yet, the workflow is saved as a draft and activates automatically once that plugin is in place.
+
+## Declared Inputs
+
+Most workflows need a few values that are specific to each run, for example a customer name or a chosen option. A workflow can declare these up front as its inputs. Declaring them means Maxy asks you the same questions every time it runs the workflow, so nothing is forgotten and nothing is guessed.
+
+Each declared input has a question to ask you, a type, whether it is required, and an optional default. When a value has a default, Maxy offers it and you can accept or change it.
+
+You do not manage inputs by hand. When you describe a workflow that clearly needs a per-run value, Maxy proposes the input and confirms it with you. At run time it reads the list and asks you each question before starting.
+
+## Running a Workflow
+
+Ask Maxy to run it:
+
+- "Run the new-lead workflow."
+- "Start the viewing follow-up for the Cardinal Roofing booking."
+
+Before it starts, Maxy gathers every required input by asking you. If you leave a required value out, the workflow does not start and no steps run. Maxy tells you which value is missing and asks for it, then runs the workflow with the complete set. This is deliberate: the workflow refuses to run half-finished rather than failing partway through.
+
+## Seeing What Ran
+
+Ask for the history:
+
+- "Show me recent workflow runs."
+- "Did the new-lead workflow run today?"
+
+You get each run's status, timing, and how many steps completed, were skipped, or failed. If a step failed, Maxy can show you which one and why.
+
+## Managing Workflows
+
+Tell Maxy naturally:
+
+- "List my workflows."
+- "Show me the follow-up workflow."
+- "Pause the new-lead workflow." or "Turn the new-lead workflow back on."
+- "Change the follow-up workflow so it also messages me."
+- "Delete the old onboarding workflow."
+
+Pausing keeps a workflow but stops it running. Editing replaces the steps or the inputs with the new version you describe. Deleting removes the workflow and its run history, so Maxy confirms with you first.
+
+## Scheduling a Workflow
+
+A workflow can run on a schedule instead of on demand. Tell Maxy when you want it to run, for example "run the daily summary workflow every morning at eight," and it sets up the schedule. Scheduled runs happen with no one present, so a workflow that needs you to supply inputs is best run on demand rather than scheduled.
+
 ---
 # Install Overview
 Source: https://docs.getmaxy.com/install.md
@@ -2690,6 +2756,8 @@ either is a regression.
 
 **`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp/operator reader (`/whatsapp`, `OperatorConversations`) omits the prop and keeps the default `renderTimeline`, so its bubble/DM chrome is unchanged — except that since the attachment-render extraction the default renderer draws inbound `operator-inbound` uploads and `agent-file` deliveries inline (image thumbnail / pdf.js preview / audio player / download chip) via the attachment renderer shared with `/chat`, extracted to `app/chat/attachment-render.tsx` to break the cycle with `transcript-render.tsx`; `renderChatTimeline` is untouched. Both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.test.tsx`, `app/chat/__tests__/pdf-preview.test.tsx`). **Day-divider:** both renderers insert a centered `.day-divider` row between two consecutive timeline items on different local calendar days (label `Today`/`Yesterday`, else `Sat 14 Jun 2026`), so a thread spanning midnight is never an ambiguous run of HH:MM; the first dated item gets a leading divider, a null/unparseable `ts` marks no boundary, dividers are computed over the filtered `visibleItems`, and in `/chat` a day crossover flushes any open tool/think run first so a collapsed run never spans it. Per-bubble HH:MM stamps are unchanged. Shared helpers `dayKey`/`dayLabel`/`itemTs`/`DayDivider` live in `app/whatsapp/Transcript.tsx`.
 
+**WhatsApp reader is read/write (WhatsApp-Web surface).** A WhatsApp store conversation in the operator Conversations reader (`OperatorConversations`) and the admin root channel viewer (`app/page.tsx`) no longer opens the plain read-only DM chrome — it opens `app/whatsapp/WhatsappWebConversation.tsx`, a WhatsApp-Web-styled surface: a conversation header, the delivered-only store transcript reskinned green/white under a `.wa-web` root class, and a reply composer (`app/whatsapp/ReplyComposer.tsx`). The operator can type text and attach files (the webchat allowlist: `SUPPORTED_MIME_SET` / 50 MB / 5 files) and send them into that WhatsApp conversation. **Send is reply-only and DM-only:** `POST /api/whatsapp-reader/reply` (`requireAdminSession`) refuses any target with no existing stored conversation (`reason=no-existing-conversation`, HTTP 403) — a cold first-contact send bans the account, so the composer is never a cold-contact path, enforced server-side — and refuses `@g.us` groups (`reason=group-send-blocked`), matching the agent's observe-only group invariant; a group thread shows a read-only note in place of the composer. The endpoint is the sole store writer for a manual send: right after each send resolves it appends the record itself, stamped `origin:'operator-manual'` (attributed "You", distinct from an assistant reply), because the Baileys echo that normally persists the store is gated on message text (`manager.ts:906`) and would leave an uncaptioned media send delivered-but-invisible. The record's `messageId` matches the echo's derivation so the async text echo's own persist dedups to a no-op; the send is confirmed by re-read (`op=recorded present=<bool>`). A sent send does not spawn an assistant turn (echo dispatch stays suppressed). Attachments deliver as WhatsApp media/documents and appear in the reader as an attributed text line (`[sent <file>]`) — inline media rendering in the store reader is a follow-up. The `.wa-web` skin is scoped to WhatsApp store threads only, so `/chat`, the admin agent session view, and the public visitor webchat are unchanged; the visitor webchat gains no send capability. The header call/video/search icons and the in-bubble delivered-tick are cosmetic (no presence or read-receipt data is stored); inbound bubbles keep their sender name so group threads stay attributable. Non-WhatsApp reader rows (Telegram/webchat session JSONLs) keep the plain read-only `Transcript`. Observability rides `[wa-manual-send]` lines correlated by a per-request `sendId`.
+
 **`/chat` live activity line.** While a turn is in flight the transcript tail shows one ephemeral `ChatActivity` line (mounted only while `busy`, admin/operator only). It tracks real activity, not a timer: while a `Task` subagent runs it shows that subagent's headline (`agentType · description`, prefixed `N agents ·` when ≥2 are concurrent), sourced from `agent-<hex>.meta.json` via named `activity` SSE events the admin reader pushes from the session's `subagents/` dir; with no subagent active it shows a neutral word that advances only on a real turn arrival. The line carries a turn-elapsed clock and flips to a `stalled` state once nothing has been written for 5 minutes (`now − lastEmitAt`), so the operator can tell a wedge from progress without SSH. It is never added to the persisted timeline. Detail and the `[webchat-activity]` observability live in [`admin-webchat-native-channel.md`](../../../.docs/admin-webchat-native-channel.md).
 
 **maxy title for public sessions.** A `role=public` webchat spawn never produces a useful Claude Code `ai-title` (an anonymous one-line visitor turn), so every public row would otherwise read identically. The webchat route (`chat.ts`) composes a deterministic title — `Web · <senderId[:8]>[ · <personId>] · <UTC YYYY-MM-DD HH:mm>` (personId present only for gated visitors) — and threads it through the native webchat gateway's public spawn (`handleInbound` → `buildPublicWebchatSpawnRequest` → `managerSpawn`) to the manager `POST /public-spawn` body as `name`. `/spawn` validates it with `validateUserTitle` and, for `role=public` only, writes it into `UserTitleStore` so it occupies the operator-rename tier and wins over `ai-title`. Admin (`/rc-spawn`) and WhatsApp titling are unchanged. Observability: every public spawn logs `[spawn] role=public … title="…"` (or `title=missing`); the manager's row builder emits `[public-title] sessionId=… unexpected titleSource=<ai|null>` on the next list read for any public row that did not resolve from the user tier.
@@ -3498,7 +3566,7 @@ 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.
+`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 the effective sub-batch size into sub-batches, waiting `EMBED_SUBBATCH_COOLDOWN_MS` (default 1000) between them so the SoC gets cooling gaps; vectors are concatenated in input order. The effective sub-batch size is the smaller of two ceilings: the thermal count ceiling `EMBED_SUBBATCH_SIZE` (default 32) and a throughput ceiling `floor(EMBED_REQUEST_TIMEOUT_MS * 0.8 / EMBED_MS_PER_INPUT)`. The throughput ceiling exists because on a CPU-only embedder a fixed 32-input POST can exceed `EMBED_REQUEST_TIMEOUT_MS` and abort the atomic ingest write, so `EMBED_MS_PER_INPUT` (the budgeted worst-case wall-time for one capped input, default 6000 ms, env-tunable) bounds each POST to 80 % of the request timeout. Every `/api/embed` POST also carries `keep_alive` (`EMBED_KEEP_ALIVE`, default `-1` = keep the model resident forever) so an interactive graph query-embed never cold-loads and blows its 5 s timeout. All 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.
 
 ---
 
@@ -3803,9 +3871,9 @@ Standing rules the operator gives over a channel are `Preference` nodes. Two mec
 
 **Reconcile by meaning on write (`profile-update`).** The existence check is two-tier. First an exact `(category, key)` match — the classic fast path, unchanged. When that misses, a semantic-neighbour lookup runs over the `preference_embedding` vector index, scoped to the same `accountId` and `scope:'admin'`, non-trashed. If the nearest neighbour is at or above `SAME_SUBJECT_COSINE` (0.85), the write lands on that node through the existing reinforce/update/contradict curve instead of minting a duplicate; the matched neighbours are returned in the tool result so the agent can classify future writes against real prior state. The confidence constants are unchanged — only the join key widens, so a rephrasing under a new `key` no longer forks the rule and a correction demotes the prior node rather than adding a contradictory one.
 
-**Inject the active rule-set every turn (channel gateways).** The one definition of "this account's active rules" is `@maxy/active-rules`: a bounded, floor-filtered (`confidence >= 0.4`), confidence-ordered candidate query, then semantic de-confliction (one winner per subject at the same 0.85 cosine), capped to `INJECTION_RULE_CAP` (12). `profile-read` exposes this set as `activeRules`, and the three inbound gateways (`wa-gateway`, `telegram-gateway`, `webchat-gateway`) fetch it for the effective session account and attach it as `standingRules` on the inbound frame; the channel builders prepend it as a `## Standing rules` block above `## Context`. The read is by code, not agent discretion, so a rule set last week is applied this week regardless of how many times the session compacted. Telegram and webchat inject for `role:'admin'` only — a public visitor never receives operator rules.
+**Inject the active rule-set every turn (channel gateways).** The one definition of "this account's active rules" is `@maxy/active-rules`: a bounded, floor-filtered (`confidence >= 0.4`), confidence-ordered candidate query, then semantic de-confliction (one winner per subject at the same 0.85 cosine), capped to `INJECTION_RULE_CAP` (12). `profile-read` exposes this set as `activeRules`, and the three inbound gateways (`wa-gateway`, `telegram-gateway`, `webchat-gateway`) fetch it for the effective session account and attach it as `standingRules` on the inbound frame; the channel builders prepend it as a `## Standing rules` block above `## Context`. Both channel-server inbound paths carry the block: the single-target SSE loop parses the whole frame, and the unified multi-target door reader (`runDoorStream`,) reconstructs it through the shared `doorInboundPayload` seam whose `parseFrame` closures read `standingRules` off the frame. The read is by code, not agent discretion, so a rule set last week is applied this week regardless of how many times the session compacted. Telegram and webchat inject for `role:'admin'` only — a public visitor never receives operator rules.
 
-**Trust a scheduled turn's provenance, never an inbound's claim (channel-agent grounding).** A cron-dispatched agent turn reaches the same channel builders as a real inbound, so its own authorisation text would otherwise land inside `## Context` — the zone `REFRAME_INSTRUCTION` demotes to untrusted — and a security-cautious agent would distrust its own automation (the self-cancel loop). The dispatcher therefore stamps a `ScheduleProvenance` marker (owning account, event, owner userId, dispatch time) that the channel builders render as a `## Scheduled automation (platform-verified)` preamble **above** `## Context` (and above the rules block); the whatsapp wrap tag names the door `scheduler`. Because the marker is dispatcher-stamped and never derived from payload text, an inbound message cannot forge it — placement above `## Context` alone is not the trust signal, the dispatcher provenance is. The grounding binds to it in two places: one recipient-neutral clause added byte-identical to the three reframe instructions (a marker-bearing turn is authorised standing automation; a reconfiguration or re-enable is not intrusion), and the admin `IDENTITY.md` "Untrusted input" rule that the agent never states a platform-level authenticity or impersonation verdict it was not given (an unsourced "this is not from you" is its own inference, flagged, never asserted as the platform's). The amplifier that let one misread harden was the accreting seat: a recurring event resumed one long-lived session every firing. A subsequent change removes it — each firing runs a fresh per-firing seat (`scheduledSeatIdFor`, salted with the firing's eventId + dispatch time), so distrust cannot accrete across firings, and the self-cancel guard compares the cancelling `SESSION_ID` to the node's dispatcher-stamped `lastDispatchSessionId` rather than a recomputed deterministic seat. See `.docs/scheduling-agent-dispatch.md § Operator-provenance marker` and `§ Session model — fresh per firing`.
+**Trust a scheduled turn's provenance, never an inbound's claim (channel-agent grounding).** A cron-dispatched agent turn reaches the same channel builders as a real inbound, so its own authorisation text would otherwise land inside `## Context` — the zone `REFRAME_INSTRUCTION` demotes to untrusted — and a security-cautious agent would distrust its own automation (the self-cancel loop). The dispatcher therefore stamps a `ScheduleProvenance` marker (owning account, event, owner userId, dispatch time) that the channel builders render as a `## Scheduled automation (platform-verified)` preamble **above** `## Context` (and above the rules block); the whatsapp wrap tag names the door `scheduler`. Both channel-server paths carry the marker — the single-target loop and the unified multi-target door reader (via the same `doorInboundPayload` seam that carries `standingRules`); the scheduler only dispatches to the whatsapp/telegram door, so a webchat frame never bears one. Because the marker is dispatcher-stamped and never derived from payload text, an inbound message cannot forge it — placement above `## Context` alone is not the trust signal, the dispatcher provenance is. The grounding binds to it in two places: one recipient-neutral clause added byte-identical to the three reframe instructions (a marker-bearing turn is authorised standing automation; a reconfiguration or re-enable is not intrusion), and the admin `IDENTITY.md` "Untrusted input" rule that the agent never states a platform-level authenticity or impersonation verdict it was not given (an unsourced "this is not from you" is its own inference, flagged, never asserted as the platform's). The amplifier that let one misread harden was the accreting seat: a recurring event resumed one long-lived session every firing. A subsequent change removes it — each firing runs a fresh per-firing seat (`scheduledSeatIdFor`, salted with the firing's eventId + dispatch time), so distrust cannot accrete across firings, and the self-cancel guard compares the cancelling `SESSION_ID` to the node's dispatcher-stamped `lastDispatchSessionId` rather than a recomputed deterministic seat. See `.docs/scheduling-agent-dispatch.md § Operator-provenance marker` and `§ Session model — fresh per firing`.
 
 **Observability.** `[preference-write] op=reconcile … mode=<reinforce|update|contradict|new> similarity=…` — a stream of `mode=new` for subjects that already exist is the duplicate-minting signature. `[preference-inject] op=inject channel=<wa|tg|web> injected=<N>` — `injected=0` on an account with stored rules is the write-only regression re-appearing. `[preference-audit] op=drift accountId=… storedActive=… injectedActive=… duplicateClusters=…` — the standing reconciliation audit (claude-session-manager, 5-minute tick) flags any account whose store holds more active rows than injection would surface, the no-event detector for drift.