@rubytech/create-maxy-code 0.1.440 → 0.1.442

package/dist/index.js

@@ -856,6 +856,89 @@ function installSystemDeps() {
     catch (err) {
         console.error(`  WARNING: failed to provision swap: ${err instanceof Error ? err.message : String(err)}`);
     }
+    // Task 1593 — zram compressed-RAM swap ahead of the SD dphys swapfile. On a
+    // Pi, swapping to the SD card thrashes I/O and turns an approach-to-OOM into
+    // an apparent hard-freeze (the muvin 2026-07-13 incident). zram swaps to
+    // compressed RAM first (default priority 100 vs dphys -2), removing the
+    // thrash and adding effective headroom; dphys stays as the low-priority
+    // last-resort overflow tier. Best-effort: a failure warns but never aborts.
+    try {
+        console.log("  [privileged] apt-get install zram-tools");
+        shell("apt-get", ["install", "-y", "zram-tools"], { sudo: true, bestEffort: true });
+        const desiredZram = "ALGO=zstd\nPERCENT=50\n";
+        const zramConfPath = "/etc/default/zramswap";
+        let zramCurrent = "";
+        if (existsSync(zramConfPath)) {
+            try {
+                zramCurrent = readFileSync(zramConfPath, "utf-8");
+            }
+            catch {
+                zramCurrent = "";
+            }
+        }
+        if (zramCurrent.includes("ALGO=zstd") && zramCurrent.includes("PERCENT=50")) {
+            logFile("  zram: already configured (ALGO=zstd PERCENT=50)");
+        }
+        else {
+            const zramTmp = `/tmp/zramswap.${process.pid}`;
+            writeFileSync(zramTmp, desiredZram);
+            console.log("  [privileged] install /etc/default/zramswap (ALGO=zstd PERCENT=50)");
+            shell("cp", [zramTmp, zramConfPath], { sudo: true });
+            spawnSync("rm", ["-f", zramTmp]);
+            console.log("  [privileged] systemctl restart zramswap");
+            shell("systemctl", ["restart", "zramswap"], { sudo: true, bestEffort: true });
+            logFile("  zram: configured ALGO=zstd PERCENT=50 and restarted zramswap");
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to provision zram: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Task 1593 — earlyoom userspace killer. Under sustained pressure it SIGTERMs
+    // the largest process at 10% MemAvailable (SIGKILL at 5%) BEFORE the kernel
+    // oom-killer wedges the box; systemd's Restart=on-failure then restarts the
+    // service, so a leak becomes "one process dies and comes back" instead of a
+    // hard freeze. --avoid protects sshd (keeps the box reachable, so SSH never
+    // drops during a kill) and systemd (init). Neo4j runs as comm=java and is
+    // crash-safe (recovers from its transaction log on restart), so it is
+    // intentionally not protected. Best-effort. The 10%/5% thresholds are the
+    // calibration target of the on-device induced-pressure test.
+    try {
+        console.log("  [privileged] apt-get install earlyoom");
+        shell("apt-get", ["install", "-y", "earlyoom"], { sudo: true, bestEffort: true });
+        // No inner quotes around the --avoid regex: the Debian earlyoom.service
+        // runs `ExecStart=/usr/bin/earlyoom $EARLYOOM_ARGS`, and systemd expands the
+        // variable by whitespace-splitting WITHOUT shell quote removal, so inner
+        // single-quotes would survive into the regex and never match sshd/systemd.
+        // The regex `^(sshd|systemd)$` contains no whitespace, so it stays one token.
+        const desiredEarlyoom = "EARLYOOM_ARGS=\"-m 10,5 -r 3600 --avoid ^(sshd|systemd)$\"\n";
+        const earlyoomConfPath = "/etc/default/earlyoom";
+        let earlyoomCurrent = "";
+        if (existsSync(earlyoomConfPath)) {
+            try {
+                earlyoomCurrent = readFileSync(earlyoomConfPath, "utf-8");
+            }
+            catch {
+                earlyoomCurrent = "";
+            }
+        }
+        if (earlyoomCurrent.includes("-m 10,5") && earlyoomCurrent.includes("--avoid ^(sshd|systemd)$")) {
+            logFile("  earlyoom: already configured (-m 10,5 --avoid sshd|systemd)");
+        }
+        else {
+            const eoTmp = `/tmp/earlyoom.${process.pid}`;
+            writeFileSync(eoTmp, desiredEarlyoom);
+            console.log("  [privileged] install /etc/default/earlyoom (-m 10,5 -r 3600)");
+            shell("cp", [eoTmp, earlyoomConfPath], { sudo: true });
+            spawnSync("rm", ["-f", eoTmp]);
+            console.log("  [privileged] systemctl enable --now earlyoom");
+            shell("systemctl", ["enable", "--now", "earlyoom"], { sudo: true, bestEffort: true });
+            shell("systemctl", ["restart", "earlyoom"], { sudo: true, bestEffort: true });
+            logFile("  earlyoom: configured -m 10,5 -r 3600 --avoid sshd|systemd and enabled");
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to provision earlyoom: ${err instanceof Error ? err.message : String(err)}`);
+    }
     // Hostname resolution — four sources, in priority order:
     //   1. --hostname flag (unconditional — the caller is the authority)
     //   2. OS detection on same-brand upgrade (service exists → keep whatever is currently set)
@@ -4218,6 +4301,17 @@ function installService() {
     const rssSamplerUnitName = `${BRAND.hostname}-rss-sampler.service`;
     const rssSamplerScriptPath = resolve(INSTALL_DIR, "platform/scripts/rss-sampler.sh");
     const rssSamplerLogPath = join(persistDir, "rss-sampler.log");
+    // Task 1593 — the per-service unit names the sampler reads for its
+    // op=mem-sample line, kept brand-agnostic by passing them as env. Neo4j runs
+    // as a dedicated per-brand unit when it is off the default port, else the
+    // shared system unit. MEM_PRESSURE_PCT sets the approach-to-OOM warning line
+    // as a percentage of MemTotal; 20% sits above earlyoom's 10% SIGTERM line on
+    // every fleet RAM size (8-16 GB), so the warning is logged before the kill
+    // (a fixed MB value cannot stay above a percentage kill line across both).
+    const memBrandService = `${BRAND.hostname}.service`;
+    const memEdgeService = edgeUnitName;
+    const memNeo4jUnit = NEO4J_DEDICATED ? `neo4j-${BRAND.hostname}.service` : "neo4j.service";
+    const memPressurePct = "20";
     const rssSamplerUnit = `[Unit]
 Description=${BRAND.productName} RSS Sampler
 
@@ -4225,6 +4319,10 @@ Description=${BRAND.productName} RSS Sampler
 Type=simple
 ExecStart=/bin/bash ${rssSamplerScriptPath}
 Environment=LOG_PATH=${rssSamplerLogPath}
+Environment=BRAND_SERVICE=${memBrandService}
+Environment=EDGE_SERVICE=${memEdgeService}
+Environment=NEO4J_UNIT=${memNeo4jUnit}
+Environment=MEM_PRESSURE_PCT=${memPressurePct}
 Restart=on-failure
 RestartSec=10
 
@@ -4232,7 +4330,7 @@ RestartSec=10
 WantedBy=default.target
 `;
     writeFileSync(join(serviceDir, rssSamplerUnitName), rssSamplerUnit);
-    logFile(`  rss-sampler installed: ${rssSamplerUnitName} LOG_PATH=${rssSamplerLogPath}`);
+    logFile(`  rss-sampler installed: ${rssSamplerUnitName} LOG_PATH=${rssSamplerLogPath} BRAND_SERVICE=${memBrandService} EDGE_SERVICE=${memEdgeService} NEO4J_UNIT=${memNeo4jUnit} MEM_PRESSURE_PCT=${memPressurePct}`);
     // the edge service: always-on front door that owns the public
     // port (PORT) and the VNC stack (Xtigervnc + websockify). Its lifecycle is
     // independent of the main brand service, so an in-place upgrade triggered

package/package.json

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

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:81b544b4ce131682cab873b1c561b196496d3f57fade3f76245646e3fc16aacc
+content-hash: sha256:93408025e99adfc1e44893f43734ca04b95c7991c596a4af5c7f471e00e884d8
 brand: maxy-code
 product-name: Maxy
 ---
@@ -2031,6 +2031,7 @@ The `outlook` plugin gives the admin agent access to Microsoft 365 / Outlook.com
 2. **Per account: register the Outlook account** — in admin chat, ask the agent to "register my Outlook account". The agent runs `outlook-account-register`, which returns a short user code and the URL `microsoft.com/devicelogin` and relays both to you.
 3. **Consent on any device** — open `microsoft.com/devicelogin` on your phone or laptop, enter the code, sign in to your Microsoft account, and consent to the requested scopes (`offline_access`, `User.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.ReadWrite`, `Contacts.Read`). `Mail.Send` enables sending and `Calendars.ReadWrite` enables calendar control; a mailbox last consented on an older read-only scope set must re-register before send or any calendar write succeeds. The agent finishes by calling `outlook-account-register-poll`.
 4. **Done.** Subsequent tool calls (mail, calendar, contacts) use the persisted refresh token transparently.
+5. **Several mailboxes on one account.** Register again to add a second mailbox; it is stored alongside the first, not in place of it. Every operational tool then takes an optional `mailbox` argument — an email address or graphUserId. With one mailbox, omit it. With two or more, name it; omitting it returns a refusal listing the connected mailboxes. `outlook-mailbox-list` shows every connected mailbox. Only one registration runs at a time per account; starting another while one is live returns an in-progress signal.
 
 ## Tools
 
@@ -2048,7 +2049,8 @@ The `outlook` plugin gives the admin agent access to Microsoft 365 / Outlook.com
 | `outlook-calendar-respond` | Accept, decline, or tentatively accept an invite. |
 | `outlook-calendar-freebusy` | Availability for one or more addresses over a window. |
 | `outlook-contacts-list` | Top contacts. Default top=50. |
-| `outlook-mailbox-info` | Health probe — auth state, refresh-window, folder count. |
+| `outlook-mailbox-info` | Health probe for one mailbox — auth state, refresh-window, folder count. Name the mailbox with `mailbox` when several are attached. |
+| `outlook-mailbox-list` | Every connected mailbox with its email, scopes, and token health. Local only — no network — so it also flags a mailbox whose stored credentials cannot be read. |
 | `outlook-mail-send` | Send a message (`POST /me/sendMail`). to/cc/bcc arrays, subject, body, isHtml. Success asserted on Graph 202. Needs `Mail.Send`. |
 | `outlook-draft` | Create a draft in Drafts (`POST /me/messages`). Same body model. Returns the draft id. Needs `Mail.ReadWrite`. |
 | `outlook-draft-send` | Send an existing draft by id (`POST /me/messages/{id}/send`). Graph consumes the draft, returns 202. Needs `Mail.Send`. |
@@ -2066,7 +2068,9 @@ All log lines start with `[outlook-mcp]` and write to `server.log`. They are key
 | Pending-store census | `pending-store-census account=<id> live=<N>` |
 | Pending cleared | `pending-cleared account=<id> verified=<bool>` |
 | /me failed post-token | `me-failed account=<id> status=<N>` |
-| Auth ok | `auth-ok account=<id> graphUserId=<id> scopes=<csv> tokenExpSec=<N>` |
+| Auth ok | `auth-ok account=<id> graphUserId=<id> mail=<addr> scopes=<csv> tokenExpSec=<N>` |
+| Registration already in flight | `register-in-progress account=<id>` (start refused; one device-code flow at a time) |
+| Credential resolve | `cred-resolve account=<id> mailbox=<id-or-empty> source=arg|sole|none|refused` — names the resolved mailbox and how it was chosen; `source=refused` is the ambiguity/not-found refusal |
 | Token refreshed | `token-refreshed account=<id> oldExpSec=<N> newExpSec=<N>` |
 | Refresh failed | `token-refresh-failed account=<id> reason=<err>` (terminal) |
 | Mail list | `mail-list op=resolve account=<id> folderIn=<name> folderResolved=<token> asRawId=<bool> count=<N> elapsedMs=<N>` (on error, `error=<msg>` replaces `count`) |
@@ -2081,6 +2085,7 @@ All log lines start with `[outlook-mcp]` and write to `server.log`. They are key
 | Scope insufficient | `scope-insufficient tool=<t> account=<id> missing=Calendars.ReadWrite` (stale read-only consent) |
 | Contacts list | `contacts-list account=<id> count=<N> elapsedMs=<N>` |
 | Mailbox info | `mailbox-info account=<id> tokenWithinRefreshWindow=<bool> folderCount=<N>` |
+| Mailbox list | `mailbox-list account=<id> count=<N> unreadable=<N>` (unreadable>0 flags an orphaned or corrupt mailbox store) |
 | Graph error | `graph-error account=<id> status=<N> code=<graphErrorCode> retryAfterMs=<N-or-null>` — writes flow through the same `callGraph` loop, so a failed write logs `graph-error` too |
 | On-prem rejected | `on-prem-rejected account=<id> mailServer=<host>` (terminal) |
 | Scope insufficient | `scope-insufficient account=<id> tool=<t> missing=Mail.Send` (terminal — re-register to grant send) |
@@ -2292,7 +2297,7 @@ A `pendingUnreconciled` number that stays above zero across several runs means t
 
 ## What this does not do
 
-One meeting type only (one length, one weekly window, one buffer). No syncing to Google or iCloud calendars: your meetings in Maxy are the source of truth. No rescheduling or cancellation links, reminders, or visitor time-zone selection. The booking page shows availability live from your device, so while your device is offline the page can still take a booking but may not show fresh open times until it is back.
+One meeting type only (one length, one weekly window, one buffer). No syncing to Google or iCloud calendars: your meetings in Maxy are the source of truth. No rescheduling or cancellation links, reminders, or visitor time-zone selection. The booking page shows open times from a snapshot your device publishes to the edge on a short timer, so the page keeps showing availability and taking bookings even while your device is offline — a slot that gets booked drops off at once, and times that have passed are never shown. If your device stays offline a long time the open times can go stale, but they never vanish; they refresh the moment it is back online.
 
 ---
 # LinkedIn Extension
@@ -2758,7 +2763,7 @@ 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 / voice-note 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, insert emoji (a codepoint-data picker — no OS input, so the `check-no-emoji-in-jsx` gate stays green), record a voice note (MediaRecorder → the existing audio send path), attach a file **from device storage** (a modal browsing the DATA_ROOT tree via `GET /api/admin/files`, sent by reference — the OS file dialog is no longer the reader's picker), reply to a specific message (a per-bubble affordance that quotes the original in the composer and threads natively on WhatsApp), and search the loaded transcript (a header control that filters to matching turns and highlights the match). The header carries only that Search control — the former Video / Phone / menu icons are gone, because no call or presence data exists behind them. Sent files honour the webchat allowlist (`SUPPORTED_MIME_SET` / 50 MB / 5 files); a device-file reference is read server-side under the same account-scope guard the `/data` download route applies. **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 render **inline** in the store reader (image thumbnail / pdf preview / audio player / download chip), because the manual-send path records the message with the servable `attachmentId`. 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 in-bubble delivered-tick is cosmetic (no read-receipt data is stored); inbound bubbles keep their sender name so group threads stay attributable, and both directions carry a WhatsApp callout tail (`.wa-web`-scoped only). 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`.
+**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, insert emoji (a codepoint-data picker — no OS input, so the `check-no-emoji-in-jsx` gate stays green), record a voice note (MediaRecorder → the existing audio send path), attach a file **from device storage** (a modal browsing the DATA_ROOT tree via `GET /api/admin/files`, sent by reference — the OS file dialog is no longer the reader's picker), reply to a specific message (a per-bubble affordance that quotes the original in the composer and threads natively on WhatsApp), and search the loaded transcript (a header control that filters to matching turns and highlights the match). The header carries only that Search control — the former Video / Phone / menu icons are gone, because no call or presence data exists behind them. Sent files honour the webchat allowlist (`SUPPORTED_MIME_SET` / 50 MB / 5 files); a device-file reference is read server-side under the same account-scope guard the `/data` download route applies. **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 render **inline** in the store reader (image thumbnail / pdf preview / audio player / download chip), because the manual-send path records the message with the servable `attachmentId`. 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 in-bubble delivered-tick is cosmetic (no read-receipt data is stored); inbound bubbles keep their sender name so group threads stay attributable, and both directions carry a WhatsApp callout tail (`.wa-web`-scoped only). 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`. **Composer sizing matches the webchat composer:** the reply textarea auto-grows to fit multi-line content (measured from `scrollHeight`, clamped to a one-row minimum and a `viewport/3` maximum, scrollable past the cap with the scrollbar hidden), and a top-border grab handle drags (pointer) or nudges (ArrowUp/ArrowDown, keyboard-focusable) to an explicit height in the same clamp; a manual drag pins the height and overrides auto-grow until the field is cleared, which releases it back to auto-grow. A completed manual resize logs `[operator-ui] op=wa-composer-resize mode=drag|key h=<px>`; a bare click on the handle (no drag) logs nothing.
 
 **`/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).
 
@@ -3182,8 +3187,10 @@ Source: https://docs.getmaxy.com/graph.md
 # Graph View
 
 The **Graph** admin page (`/graph`) renders a force-directed view of your
-account's Neo4j subgraph. Labels on the canvas follow the zoom level, so you
-see the most useful identity at every scale.
+account's Neo4j subgraph. Node captions are hidden on first load so the
+whole-graph overview stays uncluttered, and appear the moment you interact.
+Once shown, captions follow the zoom level so you see the most useful identity
+at every scale.
 
 ## Default view
 
@@ -3239,11 +3246,25 @@ This is an in-page overlay, so the browser tab and address bar stay put. It is
 not the operating system's full-screen mode. The maximize button shows only on
 the `/graph` page, not where the graph is embedded in another pane.
 
+## Captions hidden on first load
+
+When you open `/graph` (or refresh the page) the whole graph auto-fits into the
+viewport, which on a busy graph would render every caption at once and overlap
+them into unreadable clutter. So captions start hidden. They appear on your
+first interaction of any kind — zoom, drag, a filter chip, a search, clicking a
+node — and stay visible for the rest of that visit. To get the clean
+caption-free overview back, reload the page.
+
+This is a one-off marker tied to page load, not a zoom threshold: after the
+first interaction, captions follow the zoom tiers below and do not hide again
+until the next reload.
+
 ## Conversation label tiers
 
 Conversation nodes carry the most operator-meaningful identity in the
 subgraph (the conversation name or summary, the date it started, the message
-count). They render in one of three tiers, switched by canvas scale:
+count). Once captions are showing they render in one of three tiers, switched
+by canvas scale:
 
 | Zoom | Label shape | Example |
 |------|-------------|---------|
@@ -4699,6 +4720,41 @@ Maxy has access to all platform logs and can filter them for you.
 
 ---
 
+## Box went unreachable, suspected memory exhaustion
+
+**Symptom:** The Pi stopped responding to everything (no web, no SSH, no ping) and needed a power-cycle. This is the signature of memory exhaustion: the box fills RAM and swap, then wedges while the kernel tries to free memory.
+
+**What protects against it:** Every install runs a standing memory audit every 30 seconds, zram compressed swap so pressure hits RAM instead of the SD card, and earlyoom, which kills the single largest process before the kernel freezes the box. A kill shows up as one service restarting, not a whole-box outage, and SSH is protected so the box stays reachable.
+
+**Check the approach to OOM after a reboot.** The audit log survives reboot. Read it:
+
+```
+~/<install>/platform/scripts/logs-read.sh --tail mem 100
+```
+
+Replace `<install>` with the install directory (for example `realagent-code`). Then:
+
+- Look for `op=mem-pressure` lines. They fire when available memory crosses the low-water mark, before any kill, and name the heaviest service (`topSlice`).
+- A single service's reading (`ptys`, `neo4j`, `brand`, `edge`, `vnc`) rising over time while the others stay flat is a memory leak in that service.
+- `op=mem-sample` lines that read `na` for the per-service fields are normal until the kernel memory controller is enabled on that box; available memory, swap, and the pressure warning still work.
+
+**Confirm a kill happened and the service came back:**
+
+```
+journalctl -t earlyoom --since -1h
+journalctl --user -u <hostname>.service --since -1h | grep -iE "Started|Scheduled restart"
+```
+
+**Check whether the kernel OOM-killer fired anyway** (it should not, if earlyoom pre-empted it):
+
+```
+journalctl -b -1 -k | grep -i oom
+```
+
+A kernel `invoked oom-killer` line means the mitigation did not pre-empt the kernel on that occasion. A gap in the `op=mem-sample` timestamps means the sampler itself stopped. Both are worth escalating.
+
+---
+
 ## Cloudflare Tunnel Down (Remote Access Broken)
 
 **Symptom:** You can reach Maxy on your local network but not via your public domain.

package/payload/platform/plugins/cloudflare/skills/calendar-site/SKILL.md

@@ -24,7 +24,11 @@ A booking visitor and the admin look at the booking from opposite sides — the
 | Admin calendar (4 views) | the install, at `/calendar` on the admin host (resolve via `admin-hostname`) | admin sign-in | every time-bound item for the account — booked and imported meetings, agent-scheduled appointments, and tasks with a due date |
 | Public booking page | Cloudflare Pages, on the booking domain | open | free/busy only, never any meeting detail |
 
-Only the public page is deployed here, because it must stay reachable and keep capturing bookings even when the install device is briefly offline. The admin calendar is dynamic, account-scoped, and authenticated, so it is served by the install over the tunnel and is same-origin with its data. Do not try to put the admin calendar on Pages.
+Only the public page is deployed here, because it must stay reachable and keep capturing bookings even when the install device is offline. The admin calendar is dynamic, account-scoped, and authenticated, so it is served by the install over the tunnel and is same-origin with its data. Do not try to put the admin calendar on Pages.
+
+## Availability survives the device going offline
+
+The booking page does not fetch open times from the device. It reads them same-origin from its own edge Function, `functions/api/calendar/free-busy.ts`, which serves a snapshot stored in the D1 `availability_snapshot` table minus any slot already booked (so a taken slot disappears at once, and two visitors never see the same slot) and with past slots filtered out (so a stale snapshot never offers an expired time). The snapshot is kept fresh by a publish job the platform server arms on a short timer: while the device is online it pushes the account's computed free/busy into `availability_snapshot`; while the device is off it simply does not run and the edge keeps serving the last snapshot until the device returns. There is no per-account cron or setup; the server arms it for the account it resolves, which is the one account whose booking site this install serves.
 
 ## Set the availability window first
 
@@ -34,7 +38,7 @@ The public page shows open slots computed as the weekly window minus busy `:Meet
 <accountDir>/calendar-availability.json
 ```
 
-Collect from the operator, then write the file: the account `timezone` (IANA), the meeting `durationMins`, the `bufferMins` between meetings, and the `weekly` window as `{ mon: [["09:00","17:00"]], ... }` with an empty array for days that are closed. Also collect `daysAhead` (the booking horizon — a positive integer count of days the page lets visitors book into, e.g. `14`) and `allowMultiSlot` (a boolean: may a visitor combine consecutive open slots into one longer back-to-back booking? default `false`). Add the `apiBase` (the brand tunnel origin that serves free/busy, `https://<brand-tunnel-domain>`), the `bookingDomain` (the custom domain the page will answer on), and `bookingDbName` (the D1 database name chosen below). Re-running this skill with new numbers is how availability — including the horizon and the multi-slot choice — is changed later; there is no separate editor.
+Collect from the operator, then write the file: the account `timezone` (IANA), the meeting `durationMins`, the `bufferMins` between meetings, and the `weekly` window as `{ mon: [["09:00","17:00"]], ... }` with an empty array for days that are closed. Also collect `daysAhead` (the booking horizon — a positive integer count of days the page lets visitors book into, e.g. `14`) and `allowMultiSlot` (a boolean: may a visitor combine consecutive open slots into one longer back-to-back booking? default `false`). Add the `bookingDomain` (the custom domain the page will answer on) and `bookingDbName` (the D1 database name chosen below). Re-running this skill with new numbers is how availability — including the horizon and the multi-slot choice — is changed later; there is no separate editor. The device-side job that keeps the edge snapshot fresh is armed by the always-running platform server, so there is nothing per-account to schedule.
 
 ## Assemble the canonical tree
 
@@ -44,11 +48,11 @@ Copy the skill template into the one canonical Pages source path `site-deploy` e
 <accountDir>/pages/<project>/
 ```
 
-The template ships `public/index.html`, `public/booking.js`, `public/booking.css`, `functions/api/book.ts`, `wrangler.toml`, and `schema.sql`. The substitutions that make it concrete are: in `public/index.html`, set the `<meta name="api-base">` content to the `apiBase` value (the booking page fetches free/busy cross-origin from the brand tunnel), set `<meta name="days-ahead">` content to `daysAhead`, and set `<meta name="allow-multi-slot">` content to `allowMultiSlot` as the literal `true` or `false`; and fill `wrangler.toml`'s `__PROJECT_NAME__`, `__D1_DATABASE_NAME__`, and `__D1_DATABASE_ID__` from the project name and the database created below. Leave no `__...__` placeholder in the assembled tree.
+The template ships `public/index.html`, `public/booking.js`, `public/booking.css`, `functions/api/book.ts`, `functions/api/calendar/free-busy.ts`, `wrangler.toml`, and `schema.sql`. The substitutions that make it concrete are: in `public/index.html`, set `<meta name="days-ahead">` content to `daysAhead` and set `<meta name="allow-multi-slot">` content to `allowMultiSlot` as the literal `true` or `false`; and fill `wrangler.toml`'s `__PROJECT_NAME__`, `__D1_DATABASE_NAME__`, and `__D1_DATABASE_ID__` from the project name and the database created below. Leave `<meta name="api-base">` empty as it ships; the page reads availability same-origin from the site's own `free-busy` edge Function (see the snapshot section below), never the device tunnel. Leave no `__...__` placeholder in the assembled tree.
 
 ## Provision the D1 bookings table
 
-This is a `bookings` table, not the `leads` table of a contact form, so the booking-specific schema ships with the template. Load the stable `<brand>-pages-d1` token from the account secrets file, minting it once only if absent and persisting it, exactly as `references/api.md` and `references/d1-data-capture.md` prescribe; the token needs both Pages Edit and D1 Edit. Create the database, record its id into `wrangler.toml`, and apply `schema.sql` to the remote database. The token is never written into the tree, never committed, never echoed.
+The booking-specific schema ships with the template: `schema.sql` creates both the `bookings` table (written by the booking page) and the `availability_snapshot` table (the single-row free/busy cache the publish job upserts and the `free-busy` edge Function reads). Applying `schema.sql` provisions both. Load the stable `<brand>-pages-d1` token from the account secrets file, minting it once only if absent and persisting it, exactly as `references/api.md` and `references/d1-data-capture.md` prescribe; the token needs both Pages Edit and D1 Edit. Create the database, record its id into `wrangler.toml`, and apply `schema.sql` to the remote database. The token is never written into the tree, never committed, never echoed.
 
 ## Deploy through site-deploy
 
@@ -59,7 +63,13 @@ Hand the assembled tree to `cloudflare:site-deploy`: it builds nothing for a sta
 Done is a live behavioural signal on the booking domain, surfaced verbatim:
 
 - The booking domain returns `HTTP/2 200` on a cache-busted request.
-- The page's free/busy call succeeds: `curl` the brand tunnel free/busy endpoint and confirm it returns a `slots` array and carries no meeting title, description, or location field. A `404` here means availability was not written; a blocked or unauthenticated response means the free/busy path is not reachable on the brand host.
+- The page's free/busy call succeeds same-origin: `curl` the booking domain's own `free-busy` edge Function and confirm it returns a `slots` array (with `updatedAt`) and carries no meeting title, description, or location field. Immediately after deploy it may return `{"slots":[],"updatedAt":null,"stale":true}` until the platform server's publish job runs once (within ~5 minutes); re-check until `updatedAt` is fresh and `slots` is populated. A response missing the `slots` field means the edge Function did not deploy; empty-with-`stale` after several minutes means the publish job is not reaching D1 (check the brand journal for `[calendar-availability]`).
+
+```bash
+curl -s "https://<booking-domain>/api/calendar/free-busy?from=$(date -u +%Y-%m-%dT00:00:00Z)&to=$(date -u -v+14d +%Y-%m-%dT00:00:00Z)" | head -c 400
+```
+
+The device's own free/busy (the publish job's source) should also return a `slots` array; a `404` there means the availability window was not written:
 
 ```bash
 curl -s "https://<brand-tunnel-domain>/api/calendar/free-busy?from=$(date -u +%Y-%m-%dT00:00:00Z)&to=$(date -u -v+14d +%Y-%m-%dT00:00:00Z)" | head -c 400

package/payload/platform/plugins/cloudflare/skills/calendar-site/template/functions/api/calendar/free-busy.ts

@@ -0,0 +1,152 @@
+// Edge free/busy Function (calendar-site skill) — offline-resilient availability.
+//
+// Served at GET /api/calendar/free-busy on the booking domain, same-origin with
+// the page. It serves open times from a snapshot the device publishes into D1
+// on a short timer (platform/ui server → publish-availability), MINUS any slot
+// already booked in the D1 `bookings` table:
+//   - Serving the snapshot means the public page keeps showing availability
+//     while the install device is offline (the device's own tunnel free/busy is
+//     then unreachable, but the snapshot survives on the edge).
+//   - Subtracting accepted bookings here — at the edge — means a booked slot
+//     disappears the instant it is taken, with no wait for the device to
+//     reconcile and republish, so two visitors are never shown the same slot.
+//   - Past slots are always filtered out, so a stale snapshot never offers a
+//     time that has already passed.
+//
+// Split like book.ts so the logic is verifiable without the Pages runtime:
+// computeFreeBusy takes an injected DB + logger and returns the HTTP shape.
+
+interface D1PreparedStatement {
+  bind: (...values: unknown[]) => D1PreparedStatement
+  first: <T = Record<string, unknown>>() => Promise<T | null>
+  all: <T = Record<string, unknown>>() => Promise<{ results?: T[] }>
+}
+interface D1Database {
+  prepare: (query: string) => D1PreparedStatement
+}
+interface FreeBusyEnv {
+  DB: D1Database
+}
+
+interface Slot {
+  start: string
+  end: string
+}
+interface Snapshot {
+  durationMins?: number
+  timezone?: string
+  slots?: Slot[]
+}
+
+type Logger = (line: string) => void
+
+interface FreeBusyQuery {
+  from?: string | null
+  to?: string | null
+  nowMs: number
+}
+
+// Default horizon when `to` is absent — a generous ceiling so a snapshot always
+// covers the page's own (operator-set) horizon.
+const DEFAULT_HORIZON_MS = 31 * 24 * 3600 * 1000
+
+export interface FreeBusyResult {
+  durationMins: number | null
+  timezone: string | null
+  slots: Slot[]
+  updatedAt: string | null
+  stale?: boolean
+}
+
+export async function computeFreeBusy(
+  env: FreeBusyEnv,
+  query: FreeBusyQuery,
+  log: Logger,
+): Promise<FreeBusyResult> {
+  const { nowMs } = query
+  const from = query.from ? Date.parse(query.from) : nowMs
+  const to = query.to ? Date.parse(query.to) : nowMs + DEFAULT_HORIZON_MS
+
+  let row: { payload?: string; updatedAt?: string } | null = null
+  try {
+    row = await env.DB
+      .prepare('SELECT payload, updatedAt FROM availability_snapshot WHERE id = 1')
+      .first<{ payload?: string; updatedAt?: string }>()
+  } catch {
+    row = null
+  }
+
+  // No snapshot published yet (first deploy) is distinct from a corrupt payload
+  // below — both otherwise collapse to empty slots, so name them apart in the log.
+  if (!row || !row.payload) {
+    log('[calendar-availability] op=serve result=no-snapshot slots=0')
+    return { durationMins: null, timezone: null, slots: [], updatedAt: null, stale: true }
+  }
+
+  let snap: Snapshot
+  try {
+    snap = JSON.parse(row.payload) as Snapshot
+  } catch {
+    log('[calendar-availability] op=serve result=corrupt slots=0')
+    return { durationMins: null, timezone: null, slots: [], updatedAt: row.updatedAt ?? null, stale: true }
+  }
+
+  const lower = Math.max(Number.isNaN(from) ? nowMs : from, nowMs)
+  const upper = Number.isNaN(to) ? nowMs + DEFAULT_HORIZON_MS : to
+
+  // Slots already taken (optimistic subtraction). Bound the scan to bookings at
+  // or after `lower`: reconcile only marks rows swept, never de-accepts them, so
+  // without this the accepted set grows without bound over the calendar's life —
+  // and a past booking can never match a snapshot slot that survives the
+  // start >= lower filter below, so the bound drops nothing. A failed read
+  // serves the snapshot as-is rather than 500 — the booking page still works.
+  const booked = new Set<string>()
+  try {
+    const res = await env.DB
+      .prepare("SELECT slotStart FROM bookings WHERE status = 'accepted' AND slotStart >= ?1")
+      .bind(new Date(lower).toISOString())
+      .all<{ slotStart?: string }>()
+    for (const b of res.results || []) {
+      if (b && typeof b.slotStart === 'string') booked.add(b.slotStart)
+    }
+  } catch {
+    /* keep the snapshot as-is */
+  }
+  const slots = (snap.slots || []).filter((s) => {
+    const t = Date.parse(s.start)
+    return !Number.isNaN(t) && t >= lower && t < upper && !booked.has(s.start)
+  })
+
+  const ageMs = row.updatedAt ? nowMs - Date.parse(row.updatedAt) : null
+  log(`[calendar-availability] op=serve result=ok slots=${slots.length} ageMs=${ageMs ?? 'na'}`)
+
+  return {
+    durationMins: snap.durationMins ?? null,
+    timezone: snap.timezone ?? null,
+    slots,
+    updatedAt: row.updatedAt ?? null,
+  }
+}
+
+interface PagesContext {
+  request: Request
+  env: FreeBusyEnv
+}
+
+export async function onRequestGet(context: PagesContext): Promise<Response> {
+  const url = new URL(context.request.url)
+  const result = await computeFreeBusy(
+    context.env,
+    {
+      from: url.searchParams.get('from'),
+      to: url.searchParams.get('to'),
+      nowMs: Date.now(),
+    },
+    (line) => console.log(line),
+  )
+  // Free/busy carries no credentials; a wildcard origin keeps it readable if a
+  // page ever fetches it cross-origin, matching the device endpoint's CORS.
+  return Response.json(result, {
+    headers: { 'Access-Control-Allow-Origin': '*' },
+  })
+}

package/payload/platform/plugins/cloudflare/skills/calendar-site/template/public/index.html

@@ -3,9 +3,12 @@
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <!-- The calendar-site skill rewrites the content of this tag to the brand
-       tunnel origin that serves /api/calendar/free-busy. -->
-  <meta name="api-base" content="__API_BASE__" />
+  <!-- Availability is read same-origin from this site's own edge Function
+       (functions/api/calendar/free-busy.ts), which serves the snapshot the
+       device publishes to D1. Empty = same-origin, so the page keeps working
+       when the install device is offline. Left blank deliberately; do not point
+       it at the device tunnel. -->
+  <meta name="api-base" content="" />
   <!-- Operator-set booking horizon (positive integer days). The skill rewrites
        the content; booking.js falls back to 14 when it is left unsubstituted. -->
   <meta name="days-ahead" content="__DAYS_AHEAD__" />

package/payload/platform/plugins/cloudflare/skills/calendar-site/template/schema.sql

@@ -16,3 +16,14 @@ CREATE TABLE IF NOT EXISTS bookings (
 );
 
 CREATE INDEX IF NOT EXISTS bookings_unswept ON bookings (status, swept);
+
+-- Single-row cache of the account's computed free/busy, published by the device
+-- on a short timer (platform/ui server → publish-availability). The booking
+-- page's edge free/busy Function serves open times from this snapshot minus any
+-- accepted booking, so the public page keeps showing availability while the
+-- device is offline. id is pinned to 1: one account per booking site, one row.
+CREATE TABLE IF NOT EXISTS availability_snapshot (
+  id        INTEGER PRIMARY KEY CHECK (id = 1),
+  payload   TEXT,
+  updatedAt TEXT
+);

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

@@ -75,7 +75,7 @@ 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 / voice-note 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, insert emoji (a codepoint-data picker — no OS input, so the `check-no-emoji-in-jsx` gate stays green), record a voice note (MediaRecorder → the existing audio send path), attach a file **from device storage** (a modal browsing the DATA_ROOT tree via `GET /api/admin/files`, sent by reference — the OS file dialog is no longer the reader's picker), reply to a specific message (a per-bubble affordance that quotes the original in the composer and threads natively on WhatsApp), and search the loaded transcript (a header control that filters to matching turns and highlights the match). The header carries only that Search control — the former Video / Phone / menu icons are gone, because no call or presence data exists behind them. Sent files honour the webchat allowlist (`SUPPORTED_MIME_SET` / 50 MB / 5 files); a device-file reference is read server-side under the same account-scope guard the `/data` download route applies. **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 render **inline** in the store reader (image thumbnail / pdf preview / audio player / download chip), because the manual-send path records the message with the servable `attachmentId`. 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 in-bubble delivered-tick is cosmetic (no read-receipt data is stored); inbound bubbles keep their sender name so group threads stay attributable, and both directions carry a WhatsApp callout tail (`.wa-web`-scoped only). 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`.
+**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, insert emoji (a codepoint-data picker — no OS input, so the `check-no-emoji-in-jsx` gate stays green), record a voice note (MediaRecorder → the existing audio send path), attach a file **from device storage** (a modal browsing the DATA_ROOT tree via `GET /api/admin/files`, sent by reference — the OS file dialog is no longer the reader's picker), reply to a specific message (a per-bubble affordance that quotes the original in the composer and threads natively on WhatsApp), and search the loaded transcript (a header control that filters to matching turns and highlights the match). The header carries only that Search control — the former Video / Phone / menu icons are gone, because no call or presence data exists behind them. Sent files honour the webchat allowlist (`SUPPORTED_MIME_SET` / 50 MB / 5 files); a device-file reference is read server-side under the same account-scope guard the `/data` download route applies. **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 render **inline** in the store reader (image thumbnail / pdf preview / audio player / download chip), because the manual-send path records the message with the servable `attachmentId`. 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 in-bubble delivered-tick is cosmetic (no read-receipt data is stored); inbound bubbles keep their sender name so group threads stay attributable, and both directions carry a WhatsApp callout tail (`.wa-web`-scoped only). 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`. **Composer sizing matches the webchat composer:** the reply textarea auto-grows to fit multi-line content (measured from `scrollHeight`, clamped to a one-row minimum and a `viewport/3` maximum, scrollable past the cap with the scrollbar hidden), and a top-border grab handle drags (pointer) or nudges (ArrowUp/ArrowDown, keyboard-focusable) to an explicit height in the same clamp; a manual drag pins the height and overrides auto-grow until the field is cleared, which releases it back to auto-grow. A completed manual resize logs `[operator-ui] op=wa-composer-resize mode=drag|key h=<px>`; a bare click on the handle (no drag) logs nothing.
 
 **`/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).
 

package/payload/platform/plugins/docs/references/calendar-booking.md

@@ -55,4 +55,4 @@ A `pendingUnreconciled` number that stays above zero across several runs means t
 
 ## What this does not do
 
-One meeting type only (one length, one weekly window, one buffer). No syncing to Google or iCloud calendars: your meetings in Maxy are the source of truth. No rescheduling or cancellation links, reminders, or visitor time-zone selection. The booking page shows availability live from your device, so while your device is offline the page can still take a booking but may not show fresh open times until it is back.
+One meeting type only (one length, one weekly window, one buffer). No syncing to Google or iCloud calendars: your meetings in Maxy are the source of truth. No rescheduling or cancellation links, reminders, or visitor time-zone selection. The booking page shows open times from a snapshot your device publishes to the edge on a short timer, so the page keeps showing availability and taking bookings even while your device is offline — a slot that gets booked drops off at once, and times that have passed are never shown. If your device stays offline a long time the open times can go stale, but they never vanish; they refresh the moment it is back online.

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

@@ -1,8 +1,10 @@
 # Graph View
 
 The **Graph** admin page (`/graph`) renders a force-directed view of your
-account's Neo4j subgraph. Labels on the canvas follow the zoom level, so you
-see the most useful identity at every scale.
+account's Neo4j subgraph. Node captions are hidden on first load so the
+whole-graph overview stays uncluttered, and appear the moment you interact.
+Once shown, captions follow the zoom level so you see the most useful identity
+at every scale.
 
 ## Default view
 
@@ -58,11 +60,25 @@ This is an in-page overlay, so the browser tab and address bar stay put. It is
 not the operating system's full-screen mode. The maximize button shows only on
 the `/graph` page, not where the graph is embedded in another pane.
 
+## Captions hidden on first load
+
+When you open `/graph` (or refresh the page) the whole graph auto-fits into the
+viewport, which on a busy graph would render every caption at once and overlap
+them into unreadable clutter. So captions start hidden. They appear on your
+first interaction of any kind — zoom, drag, a filter chip, a search, clicking a
+node — and stay visible for the rest of that visit. To get the clean
+caption-free overview back, reload the page.
+
+This is a one-off marker tied to page load, not a zoom threshold: after the
+first interaction, captions follow the zoom tiers below and do not hide again
+until the next reload.
+
 ## Conversation label tiers
 
 Conversation nodes carry the most operator-meaningful identity in the
 subgraph (the conversation name or summary, the date it started, the message
-count). They render in one of three tiers, switched by canvas scale:
+count). Once captions are showing they render in one of three tiers, switched
+by canvas scale:
 
 | Zoom | Label shape | Example |
 |------|-------------|---------|