@rubytech/create-maxy-code 0.1.477 → 0.1.479

package/payload/platform/plugins/admin/mcp/dist/tools/cpu-triage.d.ts

@@ -0,0 +1,94 @@
+/**
+ * cpu-triage — start/read pair for the device CPU diagnostic.
+ *
+ * The measurement samples for at least one full 120 s reconcile cycle, because
+ * anything shorter catches a random phase of a sawtooth and produces
+ * contradictory answers (see `platform/scripts/cpu-triage.sh`). No admin tool
+ * exceeds a 12 s envelope, so the run is detached and the caller polls.
+ *
+ * Three files per run live under `<configDir>/logs/`:
+ *
+ *   cpu-triage-<id>.meta.json   written here at start
+ *   cpu-triage-<id>.json        written by the runner, STREAMING
+ *   cpu-triage-<id>.status      written by the runner, last
+ *
+ * `.status` is the only readiness signal. The result file exists from the first
+ * byte of output and is half-written for the whole window, so keying on it
+ * reports a sampling run as complete.
+ */
+/** Shortest window the measurement is trustworthy over — one reconcile cycle. */
+export declare const MIN_WINDOW_SEC = 120;
+/** Runs retained on disk. Older runs are pruned when a new one starts. */
+export declare const RETAINED_RUNS = 20;
+export interface CpuTriagePaths {
+    /** `platform/scripts/cpu-triage.sh` */
+    scriptPath: string;
+    /** `platform/scripts/cpu-triage-run.sh` */
+    runnerPath: string;
+    /** `<configDir>/logs` — where per-run files live */
+    logsDir: string;
+    /** brand log receiving the op=start line */
+    serverLog: string;
+}
+export interface StartOptions {
+    windowSec?: number;
+    intervalSec?: number;
+    thresholdPct?: number;
+    /** A peer brand on the previous build, for like-for-like comparison. */
+    control?: string;
+}
+export interface RunMeta {
+    runId: string;
+    startedAt: string;
+    expectedCompleteAt: string;
+    windowSec: number;
+    args: string[];
+}
+/**
+ * `fault` separates a genuine defect the operator must act on (a missing
+ * script) from an ordinary empty state (nothing has been started yet). Only a
+ * fault is surfaced as an MCP error.
+ */
+export interface Refusal {
+    ok: false;
+    reason: "script-missing" | "runner-missing" | "window-too-short" | "no-runs" | "run-not-found";
+    fault: boolean;
+    detail: string;
+}
+export type StartOutcome = ({
+    ok: true;
+    resultPath: string;
+} & RunMeta) | Refusal;
+export type ReadOutcome = {
+    ok: true;
+    status: "running";
+    runId: string;
+    startedAt: string;
+    expectedCompleteAt: string;
+    windowSec: number;
+} | {
+    ok: true;
+    status: "complete";
+    runId: string;
+    exitCode: number;
+    report: unknown;
+} | {
+    ok: true;
+    status: "failed";
+    runId: string;
+    exitCode: number;
+    stderr: string;
+    detail?: string;
+} | Refusal;
+/** Injection seam so tests drive start without spawning a real process. */
+export type SpawnRunner = (command: string, args: string[]) => void;
+/**
+ * Start a detached triage run. Returns as soon as the run handle is on disk;
+ * the measurement continues in a process this one does not hold open.
+ */
+export declare function startCpuTriage(paths: CpuTriagePaths, opts: StartOptions, spawnRunner?: SpawnRunner): StartOutcome;
+/** Read a triage run. Defaults to the most recent. */
+export declare function readCpuTriage(paths: CpuTriagePaths, opts: {
+    runId?: string;
+}): ReadOutcome;
+//# sourceMappingURL=cpu-triage.d.ts.map

package/payload/platform/plugins/admin/mcp/dist/tools/cpu-triage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpu-triage.d.ts","sourceRoot":"","sources":["../../src/tools/cpu-triage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,iFAAiF;AACjF,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,0EAA0E;AAC1E,eAAO,MAAM,aAAa,KAAK,CAAC;AAKhC,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,SAAS,GAAG,eAAe,CAAC;IAC/F,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GACpB,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,GAC5C,OAAO,CAAC;AAEZ,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChH;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAClF;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAChG,OAAO,CAAC;AAEZ,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;AAqDpE;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,YAAY,EAClB,WAAW,GAAE,WAA2B,GACvC,YAAY,CAgEd;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CA8F1F"}

package/payload/platform/plugins/admin/mcp/dist/tools/cpu-triage.js

@@ -0,0 +1,229 @@
+/**
+ * cpu-triage — start/read pair for the device CPU diagnostic.
+ *
+ * The measurement samples for at least one full 120 s reconcile cycle, because
+ * anything shorter catches a random phase of a sawtooth and produces
+ * contradictory answers (see `platform/scripts/cpu-triage.sh`). No admin tool
+ * exceeds a 12 s envelope, so the run is detached and the caller polls.
+ *
+ * Three files per run live under `<configDir>/logs/`:
+ *
+ *   cpu-triage-<id>.meta.json   written here at start
+ *   cpu-triage-<id>.json        written by the runner, STREAMING
+ *   cpu-triage-<id>.status      written by the runner, last
+ *
+ * `.status` is the only readiness signal. The result file exists from the first
+ * byte of output and is half-written for the whole window, so keying on it
+ * reports a sampling run as complete.
+ */
+import { spawn } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+/** Shortest window the measurement is trustworthy over — one reconcile cycle. */
+export const MIN_WINDOW_SEC = 120;
+/** Runs retained on disk. Older runs are pruned when a new one starts. */
+export const RETAINED_RUNS = 20;
+/** Grace added to the window when reporting when a run should be readable. */
+const COMPLETION_SLACK_MS = 30_000;
+const spawnDetached = (command, args) => {
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.unref();
+};
+function metaPath(paths, runId) {
+    return join(paths.logsDir, `cpu-triage-${runId}.meta.json`);
+}
+function resultPath(paths, runId) {
+    return join(paths.logsDir, `cpu-triage-${runId}.json`);
+}
+function statusPath(paths, runId) {
+    return join(paths.logsDir, `cpu-triage-${runId}.status`);
+}
+/**
+ * Timestamp-prefixed so "most recent" is a filename sort rather than a stat
+ * walk, and so a run id is legible in a log line without a lookup.
+ */
+function mintRunId(now) {
+    const iso = now.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "");
+    return `${iso}-${randomBytes(2).toString("hex")}`;
+}
+/** Run ids present on disk, oldest first. */
+function listRunIds(paths) {
+    if (!existsSync(paths.logsDir))
+        return [];
+    return readdirSync(paths.logsDir)
+        .filter((f) => f.startsWith("cpu-triage-") && f.endsWith(".meta.json"))
+        .map((f) => f.slice("cpu-triage-".length, -".meta.json".length))
+        .sort();
+}
+function prune(paths, keep) {
+    const ids = listRunIds(paths);
+    for (const id of ids.slice(0, Math.max(0, ids.length - keep))) {
+        for (const p of [metaPath(paths, id), resultPath(paths, id), statusPath(paths, id)]) {
+            rmSync(p, { force: true });
+        }
+    }
+}
+function logLine(paths, line) {
+    try {
+        mkdirSync(dirname(paths.serverLog), { recursive: true });
+        appendFileSync(paths.serverLog, `${new Date().toISOString()} ${line}\n`);
+    }
+    catch {
+        // Best-effort. A log write must never take the diagnostic down with it.
+    }
+}
+/**
+ * Start a detached triage run. Returns as soon as the run handle is on disk;
+ * the measurement continues in a process this one does not hold open.
+ */
+export function startCpuTriage(paths, opts, spawnRunner = spawnDetached) {
+    const windowSec = opts.windowSec ?? 300;
+    // The script refuses a short window with exit 2, but detached that refusal
+    // arrives one full window late. It has to be synchronous.
+    if (windowSec < MIN_WINDOW_SEC) {
+        return {
+            ok: false,
+            reason: "window-too-short",
+            fault: true,
+            detail: `windowSec=${windowSec} is shorter than the ${MIN_WINDOW_SEC}s reconcile cycle. ` +
+                `Samples shorter than the cycle land on a random phase of a sawtooth and contradict each other.`,
+        };
+    }
+    if (!existsSync(paths.scriptPath)) {
+        return {
+            ok: false,
+            reason: "script-missing",
+            fault: true,
+            detail: `cpu-triage.sh is not on this device at ${paths.scriptPath}. No measurement was taken.`,
+        };
+    }
+    if (!existsSync(paths.runnerPath)) {
+        return {
+            ok: false,
+            reason: "runner-missing",
+            fault: true,
+            detail: `cpu-triage-run.sh is not on this device at ${paths.runnerPath}. No measurement was taken.`,
+        };
+    }
+    const now = new Date();
+    const runId = mintRunId(now);
+    const measureArgs = ["--window", String(windowSec)];
+    if (opts.intervalSec !== undefined)
+        measureArgs.push("--interval", String(opts.intervalSec));
+    if (opts.thresholdPct !== undefined)
+        measureArgs.push("--threshold", String(opts.thresholdPct));
+    if (opts.control)
+        measureArgs.push("--control", opts.control);
+    const meta = {
+        runId,
+        startedAt: now.toISOString(),
+        expectedCompleteAt: new Date(now.getTime() + windowSec * 1000 + COMPLETION_SLACK_MS).toISOString(),
+        windowSec,
+        args: measureArgs,
+    };
+    mkdirSync(paths.logsDir, { recursive: true });
+    // Prune before the new run lands so it can never prune itself.
+    prune(paths, RETAINED_RUNS - 1);
+    writeFileSync(metaPath(paths, runId), JSON.stringify(meta, null, 2));
+    logLine(paths, `[cpu-triage] op=start runId=${runId} windowSec=${windowSec}`);
+    spawnRunner(paths.runnerPath, [
+        "--run-id", runId,
+        "--out-dir", paths.logsDir,
+        "--log", paths.serverLog,
+        "--script", paths.scriptPath,
+        "--", ...measureArgs,
+    ]);
+    return { ok: true, ...meta, resultPath: resultPath(paths, runId) };
+}
+/** Read a triage run. Defaults to the most recent. */
+export function readCpuTriage(paths, opts) {
+    const ids = listRunIds(paths);
+    if (ids.length === 0) {
+        return {
+            ok: false,
+            reason: "no-runs",
+            fault: false,
+            detail: "No cpu-triage run has been started on this device. Call cpu-triage-start first.",
+        };
+    }
+    const runId = opts.runId ?? ids[ids.length - 1];
+    if (!ids.includes(runId)) {
+        return {
+            ok: false,
+            reason: "run-not-found",
+            fault: false,
+            detail: `No run ${runId} on this device. Available: ${ids.join(", ")}`,
+        };
+    }
+    let meta;
+    try {
+        meta = JSON.parse(readFileSync(metaPath(paths, runId), "utf-8"));
+    }
+    catch (err) {
+        return {
+            ok: true,
+            status: "failed",
+            runId,
+            exitCode: -1,
+            stderr: "",
+            detail: `run metadata unreadable: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // The status marker is the only readiness signal. The result file is
+    // streamed and exists half-written for the whole sampling window.
+    const status = statusPath(paths, runId);
+    if (!existsSync(status)) {
+        return {
+            ok: true,
+            status: "running",
+            runId,
+            startedAt: meta.startedAt,
+            expectedCompleteAt: meta.expectedCompleteAt,
+            windowSec: meta.windowSec,
+        };
+    }
+    const statusText = readFileSync(status, "utf-8");
+    const match = statusText.match(/^exit=(-?\d+)/);
+    const exitCode = match ? Number(match[1]) : -1;
+    // Split on the first newline rather than slicing from indexOf: a status file
+    // with no trailing newline has indexOf === -1, and slice(0) would hand back
+    // the whole text — reporting `exit=0` itself as the run's stderr.
+    const newline = statusText.indexOf("\n");
+    const stderr = newline === -1 ? "" : statusText.slice(newline + 1).trim();
+    // Exit 1 is the script's sustained-hot-core gate — a finding, not a failure.
+    // Only a precondition failure (2) or an unexpected code is failed.
+    if (exitCode !== 0 && exitCode !== 1) {
+        return { ok: true, status: "failed", runId, exitCode, stderr };
+    }
+    const result = resultPath(paths, runId);
+    // An absent result file and an unparseable one are different conditions and
+    // must not share a message — "will not parse" sends the reader looking at
+    // JSON when the file was never written.
+    if (!existsSync(result)) {
+        return {
+            ok: true,
+            status: "failed",
+            runId,
+            exitCode,
+            stderr,
+            detail: `the run exited ${exitCode} but wrote no report at ${result}`,
+        };
+    }
+    let report;
+    try {
+        report = JSON.parse(readFileSync(result, "utf-8"));
+    }
+    catch (err) {
+        return {
+            ok: true,
+            status: "failed",
+            runId,
+            exitCode,
+            stderr,
+            detail: `the run exited ${exitCode} but its report will not parse: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    return { ok: true, status: "complete", runId, exitCode, report };
+}
+//# sourceMappingURL=cpu-triage.js.map

package/payload/platform/plugins/admin/mcp/dist/tools/cpu-triage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpu-triage.js","sourceRoot":"","sources":["../../src/tools/cpu-triage.ts"],"names":[],"mappings":"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"}

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:fa437825011cbcc1e2d5a13a3d16226ad0d1935a8856ad8fc478d04d16be49d3
+content-hash: sha256:c7a28352289a7121b08a8d8f2d5bcb1e79497a6acda2e355756cf7b02051c3a5
 brand: maxy-code
 product-name: Maxy
 ---
@@ -1285,6 +1285,18 @@ The most common cause is wrong nameservers on the domain. The domain must use Cl
 - The `/data` page handles this itself: files over 95 MB are split into ~48 MB parts and sent one at a time under the cap, and the server reassembles them. No plan change or dashboard action is needed for uploads up to the 2 GB app ceiling.
 - Raising the proxied body limit is a paid-plan change made on the Cloudflare dashboard, not something the agent does.
 
+## The client file portal
+
+A portal gives named people their own passcode-protected page on a custom domain. Two things sit on it.
+
+**What they send you.** Anything they upload lands in the account's own storage, one area per person, and nobody sees anyone else's files.
+
+**What you have prepared for them.** The same page shows the account's deliverable folders — the work produced for that client. Which folders those are is not a setting to maintain: it follows the account's own filing structure, so a business whose work is organised into quotes sees quotes, and a business organised some other way sees that instead. Operator working data, the client's own uploads, and anything internal are never shown.
+
+Folder names and sizes are published to the portal on a schedule, so the client can browse even while the device is off. The files themselves stay on the device. Opening one checks the device is reachable and then hands the browser a link that expires after a few minutes; if the device is down the client is told exactly that, rather than getting a broken download.
+
+Each person is bound to one account when they are enrolled. Someone enrolled before this existed has no account bound and sees no folders until they are enrolled again.
+
 ## What the agent does and does not do
 
 **Does:** invokes `cloudflared` directly via Bash, following `plugins/cloudflare/references/manual-setup.md` step by step; quotes click-paths from the reference files verbatim; verifies external reachability with `curl -I` and surfaces the response.
@@ -2943,7 +2955,7 @@ either is a regression.
 
 **Row title resolution.** Both the sidebar (`/sidebar-sessions`) and the manager's own row payload resolve a row's title in the same order: operator rename → Claude Code `ai-title` → first non-CLI user message → 8-char sessionId prefix. The operator-rename tier is the on-disk `<accountDir>/session-titles.json` (the manager's `UserTitleStore`), keyed by the CC sessionId — the sidebar reads that same file, so a write to the store lights up both surfaces with one write.
 
-**Session row delete, rename, and select mode.** The sidebar Sessions row supports three operator affordances. **Rename** (kebab → Rename) opens the inline edit input with its existing title pre-selected on focus, so the first keystroke replaces the whole title rather than appending to it — on both the sidebar (`conv-name-edit`) and the `/chat` Conversations flyout (`op-conv-rename-input`). **Delete** (kebab → Delete) arms a confirm that names the session (its label plus the 8-char id prefix) and renders as a popover anchored beside the row it will delete — reusing the same `AnchoredPopover` the kebab menu uses, not the shared bottom-right info dock — so the target is unambiguous; it still states the delete is permanent and, for a live row, that the session is stopped first. **Select mode** (a "Select" control in the Sessions header) turns each row into a checkbox and shows a "Delete N" bar; the row body toggles selection instead of opening, the per-row kebab is hidden, and confirming a count-based `BulkDeleteConfirmModal` (which names N and how many are live) loops the single-id `session-delete` over the selection (no route change — `/api/admin/session-delete` stays single-id). Bulk deletion is instrumented with a `[admin-ui] sidebar-bulk-delete op=start count=<N> live=<M>` / `op=done requested=<N> ok=<X> failed=<Y>` envelope around the per-session `sidebar-session-delete` lines, so a silently-dropped item shows as `ok+failed < requested`. Outside select mode the single-delete and row-open behaviours are unchanged.
+**Session row delete, rename, and select mode.** The sidebar Sessions row supports three operator affordances. **Rename** (kebab → Rename) opens the inline edit input with its existing title pre-selected on focus, so the first keystroke replaces the whole title rather than appending to it — on both the sidebar (`conv-name-edit`) and the `/chat` Conversations flyout (`op-conv-rename-input`). **Delete** (kebab → Delete) arms a confirm that names the session (its label plus the 8-char id prefix) and renders as a popover anchored beside the row it will delete — reusing the same `AnchoredPopover` the kebab menu uses, not the shared bottom-right info dock — so the target is unambiguous; it still states the delete is permanent and, for a live row, that the session is stopped first. **Usage & cost** (kebab → Usage & cost) opens the per-day active-time / token / GBP-cost table for that session, and anchors beside its row through the same `AnchoredPopover`, with no scrim, so the rest of the dashboard stays legible and interactive while it is open. `AnchoredPopover` right-aligns to the anchor's rect and clamps horizontally against both viewport edges. Vertically it places below when the popover fits there, above when it fits there instead, and otherwise on whichever side has more room — and in every case it bounds the popover's height to the room on the side it chose. That bound is what keeps a long session's panel anchored: a 30-day usage table is taller than the viewport, and clamping it to fit would push it up over the very row it describes, which is not "anchored" to anything. Instead it sits flush against its row and scrolls internally. Because the bound is derived from the anchor rect and the viewport rather than from the popover's own height, the `ResizeObserver` pass it triggers recomputes the same values and settles in one extra pass. The horizontal right-edge clamp does not engage for a left-docked sidebar row (a popover wider than its anchor overflows left, which the left clamp handles); it is kept because the component is general-purpose and is covered by unit test only. Positioning is instrumented, because a mispositioned client-side panel throws nothing and the operator just sees a menu item that did nothing: every positioning pass (each open, each `ResizeObserver` callback, each window resize) emits `[anchored-popover] op=anchor id=<class>:<sessionId> present=<bool> rect=<x,y,w,h>` then `op=placed … maxH=<px> flipped=<bool> clampedLeft=<bool> clampedRight=<bool>`, and `op=offscreen` at `console.error` when the anchor is detached from layout or a placed rect misses the viewport. A pass that computes exactly what the previous pass did is suppressed, so mount and its trailing `ResizeObserver` callback log once rather than twice; the `op=offscreen` assertion is never suppressed. A healthy open is `present=true` with a non-zero rect followed by `op=placed` and no `op=offscreen`. `present=false` means the row is not in `rowRefs` — the row unmounted or its ref callback did not run — and the panel docks bottom-right rather than vanishing, because an invisible panel is indistinguishable from a broken menu item. An all-zero rect means the anchor is detached. The assertion is gated on the popover having non-zero measured size, so an unlaid-out popover (pre-paint, or jsdom) stays silent; a genuinely zero-size popover in production is therefore not reported. **Select mode** (a "Select" control in the Sessions header) turns each row into a checkbox and shows a "Delete N" bar; the row body toggles selection instead of opening, the per-row kebab is hidden, and confirming a count-based `BulkDeleteConfirmModal` (which names N and how many are live) loops the single-id `session-delete` over the selection (no route change — `/api/admin/session-delete` stays single-id). Bulk deletion is instrumented with a `[admin-ui] sidebar-bulk-delete op=start count=<N> live=<M>` / `op=done requested=<N> ok=<X> failed=<Y>` envelope around the per-session `sidebar-session-delete` lines, so a silently-dropped item shows as `ok+failed < requested`. Outside select mode the single-delete and row-open behaviours are unchanged.
 
 **`/chat` empty-state starter chips.** While the admin webchat has no conversation JSONL yet (`GET /api/webchat/session` → `projectDir:null`), `app/chat/page.tsx` renders a "What's up next, {givenName}?" greeting (given name = first whitespace token of the admin session's `userName`; degrades to "What's up next?" without one) above three one-tap starter chips (replacing the earlier read-only lists): **Catch me up** (`Inbox`), **My day** (`CalendarClock`), **To-do** (`ListTodo`). `GreetingPanel` no longer fetches `GET /api/webchat/greeting` — the headline reads from the `userName` prop alone. A tap dispatches the chip's verbatim prompt through the existing `send()` with zero typing, via the same arm/fire path as the `?q=` handoff seed: `dispatchChip` logs `[admin-ui] op=chip-tap id=<catch-up|my-day|to-do> chars=<n>`, sets the composer text, and arms a one-shot effect that fires `send()` once the text matches. Chips gate to `variant` admin/operator; the public surface shows the headline alone. The first journaled turn replaces the panel with the transcript. The `/api/webchat/greeting` route (`server/routes/webchat-greeting.ts`) and `specialist-roster.ts` are now unconsumed by this surface — slimming them is a separate follow-up. The full webchat architecture lives in `.docs/admin-webchat-native-channel.md`.
 

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

@@ -34,7 +34,7 @@ The plugin registers no agent-facing MCP tools. Every Cloudflare operation is th
 | [cloudflare/SKILL.md](skills/cloudflare/SKILL.md) | The entry point for every Cloudflare operation. Routes each operation class to its reference, names the outcome contracts (tunnel external HTTP 200; hosting deployed URL; D1 round-trip), and states the tool-discipline + secret-redaction rules that bind the agent. |
 | [site-deploy/SKILL.md](skills/site-deploy/SKILL.md) | Assemble one canonical content tree into a live Pages deployment on its custom domain that survives the install device being offline. Names the single-source-tree convention, the reused per-scope token, the form-to-D1 trigger, the R2 binding trigger, Open Graph correctness, and the cache-busted live-`200` done-gate; defers the command blocks to `hosting-sites.md`, `d1-data-capture.md` and `r2-object-storage.md`. Admin-run; a content specialist hands the deploy off to it. |
 | [calendar-site/SKILL.md](skills/calendar-site/SKILL.md) | Assemble and deploy one account's public booking page — a static page plus edge Functions over a D1 `bookings` table — on its own custom domain, so a submission survives the install device being offline. Admin-run; defers the deploy and the live done-gate to `site-deploy`. |
-| [data-portal/SKILL.md](skills/data-portal/SKILL.md) | Stand up one account's gated file-drop portal on its own custom domain: each enrolled person signs in with their own passcode and can upload, list, download and delete only their own files, into one R2 bucket under a per-person prefix with a D1 manifest row per upload. The bucket is created by the owning account's own session — the broker registers ownership to the creator and never reassigns it — while the admin assembles and deploys. Admin-run; defers the deploy and the live done-gate to `site-deploy`. |
+| [data-portal/SKILL.md](skills/data-portal/SKILL.md) | Stand up one account's gated file-drop portal on its own custom domain: each enrolled person signs in with their own passcode and can upload, list, download and delete only their own files, into one R2 bucket under a per-person prefix with a D1 manifest row per upload. The same portal also shows that sub-account's deliverable folders, published from the device as metadata only and opened through a short-lived signed link. The bucket is created by the owning account's own session — the broker registers ownership to the creator and never reassigns it — while the admin assembles and deploys. Admin-run; defers the deploy and the live done-gate to `site-deploy`. |
 
 ### References
 
@@ -69,6 +69,31 @@ The setup-done claim only fires when `curl -I https://<hostname>` issued from ou
 - **Cloudflare account identity** — `cert.pem` from OAuth. One account per brand per device.
 - **Account binding drift** — `~/{configDir}/cloudflared/account-binding.json` is a historical drift marker. Reset by `rm -rf ~/.${BRAND}/cloudflared/` per `references/reset-guide.md` when switching accounts.
 
+## Data-portal folder index
+
+The portal shows a sub-account's deliverable folders alongside what the client uploaded. Which folders those are is never a list in the code: it is derived per account from that account's own `SCHEMA.md` — the buckets in its `<!-- ontology-buckets -->` region plus `output`, intersected with its `allowed-top-level` block. A brand on a different vertical exposes different folders with no code change. `bin/schema-exposed-dirs.mjs` is the only place that decision is made.
+
+`bin/portal-index-push.mjs` walks those folders and full-replaces the account's rows in the portal's D1 `directory` table each cycle. Metadata only — names, sizes, times — so listing survives the device being offline, and a deleted or renamed file converges on the next cycle without a tombstone. The scheduling heartbeat runs it hourly for every account carrying a `data-portal.json`; it is also runnable standalone, which is how it stays operable while the heartbeat spawn path is unproven on a device.
+
+Opening a file reaches the install: the portal probes it, then mints an `/api/portal/fetch` link signed with the account's `PORTAL_FETCH_SECRET` and valid for five minutes. The install verifies the signature **and independently re-derives the exposed folder set**, so a correctly signed link for a non-exposed path is still refused. That second check is the security boundary, not the signature.
+
+What to watch, on the device:
+
+```
+[portal-index] op=resolve account=<id> schemaPresent=<bool> allowed=<n> domainBuckets=<dirs|none> exposed=<dirs|none>
+[portal-index] op=replace account=<id> deleted=all inserted=<n>
+[portal-index] op=verify  account=<id> rowsAfter=<n> expected=<n>
+[portal-index] op=collision account=<id> dir=<dir> claimedBy=plugin-owned
+[portal-index] op=exposed-changed account=<id> added=<dirs|none> removed=<dirs|none>
+[portal-index] op=audit accounts=<n> stale=<n> never-ran=<n>
+```
+
+`exposed=none` where deliverables exist means the schema was missing or carried no ontology region — not that the walk found nothing. `rowsAfter` disagreeing with `expected` is a half-applied replace. An `op=collision` line explains a folder that has silently vanished from the client's view, which nothing else would report. `op=exposed-changed` fires only on a delta, so it is rare and always worth reading; a `removed=` naming a populated bucket is the client-visible regression.
+
+`op=audit` is the standing check, and it is the only one that speaks when the push does **not**. It runs in-process inside the heartbeat rather than as a spawn, and reads only local state, so it cannot be blinded by the same failure it is watching for. It fires hourly even when everything is healthy — an audit that goes quiet on success is indistinguishable from an audit that stopped running. `result=never-ran` on an account with a `data-portal.json` means no cycle has ever succeeded for it; `result=stale` with `ageMin` means cycles have stopped. Its input is written only after `op=verify`, so a stale entry means the push stopped succeeding rather than merely stopped logging.
+
+On the portal side `[data-portal] op=list` carries `account=` and `op=fetch-through` carries the outcome; on the install `[portal-fetch]` logs `op=request` then exactly one of `op=served`, `op=denied`, `op=miss`. A portal `fetch-through` with no matching install `op=request` means the request never arrived, rather than having been refused. `[portal-fetch] op=no-secret account=<id>` is an unconfigured portal, which the `op=denied reason=secret` line alone would not distinguish from a bad signature.
+
 ## Discipline
 
 The agent's permitted surfaces are: direct `cloudflared` and `wrangler` invocations via Bash following the references; Cloudflare API calls authenticated by a reused per-scope narrow token, minted once if absent and persisted to the secrets file (the master token stays in that same file, never on a command line that echoes, never in chat); the reference files; and live verification (`curl -I` for tunnels, the deployed URL for hosting, a `SELECT` for D1). Out of bounds: Playwright or Chrome DevTools driving the dashboard, browser-automating master-token creation, WebSearch-for-CF-recipes, ad-hoc `cloudflared` flag invention not in the runbook, and writing or echoing any token. When a step fails, the agent reports the exact output (secrets redacted), cites the recovery step from `references/reset-guide.md`, and stops.

package/payload/platform/plugins/cloudflare/bin/d1-http.mjs

@@ -0,0 +1,80 @@
+// D1 over the Cloudflare HTTP API, with bound parameters.
+//
+// Not `wrangler d1 execute`: that spawns a process per statement, which is the
+// CPU-burn defect Task 1805 fixed, and it takes a raw SQL string, which would
+// mean interpolating filenames into SQL. The index push writes one row per file,
+// so both matter here.
+//
+// storage-broker's cf-exec.d1Query still spawns wrangler, and the scheduling
+// plugin has its own HTTP client. Converging the three is a follow-up; this
+// client depends on neither, because the cloudflare plugin is where Cloudflare
+// access belongs and importing the scheduling plugin from here would invert that.
+
+const API = 'https://api.cloudflare.com/client/v4'
+
+/**
+ * Always carries the response body into the message. A bare status renders
+ * every failure identical and unactionable.
+ * @param {unknown} parsed @param {number} status @param {string} label
+ * @returns {never}
+ */
+function fail(parsed, status, label) {
+  const errs = /** @type {{errors?: {message?: string}[]}} */ (parsed)?.errors
+  const detail = Array.isArray(errs) && errs.length ? errs.map((e) => e?.message).join('; ') : ''
+  throw new Error(`${label} failed: HTTP ${status}${detail ? ` — ${detail}` : ''}`)
+}
+
+/**
+ * @param {{ accountId: string, token: string, dbName: string,
+ *           fetchFn?: (url: string, init: object) => Promise<{ ok: boolean, status: number, json: () => Promise<unknown> }> }} opts
+ */
+export function createD1Client(opts) {
+  const fetchFn = opts.fetchFn ?? /** @type {never} */ (globalThis.fetch)
+  const headers = { Authorization: `Bearer ${opts.token}`, 'Content-Type': 'application/json' }
+  /** @type {string | undefined} */ let databaseId
+  let statements = 0
+
+  async function resolveId() {
+    if (databaseId !== undefined) return databaseId
+    const url = `${API}/accounts/${opts.accountId}/d1/database?name=${encodeURIComponent(opts.dbName)}`
+    const res = await fetchFn(url, { method: 'GET', headers })
+    const parsed = await res.json()
+    if (!res.ok) fail(parsed, res.status, 'd1 database lookup')
+    const list = /** @type {{result?: {name?: string, uuid?: string}[]}} */ (parsed).result ?? []
+    // Exact name match, never "the first result": `?name=` is a filter whose
+    // matching rule is not documented, so taking position on trust would let a
+    // near-name run this account's statements against the wrong database.
+    const hit = list.find((d) => d.name === opts.dbName)
+    if (!hit || typeof hit.uuid !== 'string') {
+      throw new Error(`no D1 database named "${opts.dbName}" in account ${opts.accountId}`)
+    }
+    databaseId = hit.uuid
+    return databaseId
+  }
+
+  /** @param {string} sql @param {unknown[]} [params] */
+  async function query(sql, params = []) {
+    const id = await resolveId()
+    // Counted before the await: `statements` is what reached D1, and a
+    // statement that was issued and then errored still went. Counting successes
+    // only would report 0 both for "the lookup failed so nothing was sent" and
+    // for "one statement was sent and errored".
+    statements++
+    const res = await fetchFn(`${API}/accounts/${opts.accountId}/d1/database/${id}/query`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ sql, params }),
+    })
+    const parsed = await res.json()
+    if (!res.ok) fail(parsed, res.status, 'd1 query')
+    const first = (/** @type {{result?: {results?: unknown}[]}} */ (parsed).result ?? [])[0]
+    return /** @type {Record<string, unknown>[]} */ (first?.results ?? [])
+  }
+
+  return {
+    query,
+    get statements() {
+      return statements
+    },
+  }
+}

package/payload/platform/plugins/cloudflare/bin/portal-enrol.mjs

@@ -20,7 +20,7 @@
 //
 // Usage:
 //   node platform/plugins/cloudflare/bin/portal-enrol.mjs --owner <ownerId> --name <name> \
-//     | npx wrangler d1 execute <db> --remote --file=-
+//     --account <accountId> | npx wrangler d1 execute <db> --remote --file=-
 
 import {
   PASSCODE_LENGTH,
@@ -60,6 +60,17 @@ if (!OWNER_ID.test(/** @type {string} */ (ownerId))) {
 // the literal harmlessly — but it breaks the pipeable contract, so refuse it.
 if (/[\r\n]/.test(/** @type {string} */ (name))) die('--name cannot contain a line break')
 
+// The sub-account whose deliverable folders this person may read. Required, and
+// validated to the same charset the account partition uses: a person enrolled
+// with no account resolves to an EMPTY folder list, which is indistinguishable
+// from a sub-account that simply has no deliverables. That is a failure nobody
+// diagnoses, so it fails here instead — loudly, before the row exists.
+const accountId = arg('--account')
+if (!accountId) die('--account <accountId> is required')
+if (!/^[A-Za-z0-9-]+$/.test(/** @type {string} */ (accountId))) {
+  die('--account must match ^[A-Za-z0-9-]+$ — an account id, not a path')
+}
+
 const saltBytes = new Uint8Array(16)
 crypto.getRandomValues(saltBytes)
 const saltHex = randomSaltHex(saltBytes)
@@ -84,8 +95,12 @@ const createdAt = new Date().toISOString()
 //
 // `createdAt` is deliberately absent from the DO UPDATE: it records when the
 // person was enrolled, and rotating a passcode is not creating a person.
+//
+// `accountId` IS in the DO UPDATE: re-enrolling someone against a different
+// sub-account has to move them, or they keep reading folders they no longer
+// belong to.
 console.log(
-  `INSERT INTO people (ownerId, name, salt, hash, createdAt) VALUES ('${ownerId}', '${sqlName}', '${saltHex}', '${hash}', '${createdAt}') ON CONFLICT(ownerId) DO UPDATE SET name=excluded.name, salt=excluded.salt, hash=excluded.hash;`,
+  `INSERT INTO people (ownerId, name, salt, hash, createdAt, accountId) VALUES ('${ownerId}', '${sqlName}', '${saltHex}', '${hash}', '${createdAt}', '${accountId}') ON CONFLICT(ownerId) DO UPDATE SET name=excluded.name, salt=excluded.salt, hash=excluded.hash, accountId=excluded.accountId;`,
 )
 
 // stderr: everything for the human. Never stdout — see the note at the top.