@rubytech/create-maxy-code 0.1.340 → 0.1.342

package/dist/__tests__/known-brand-hostnames.test.js

@@ -0,0 +1,40 @@
+// Drift guard: every shipped brand's hostname must appear in
+// KNOWN_BRAND_HOSTNAMES, the allowlist that peerBrandPresent() matches against
+// to decide whether a co-resident brand is still installed. A shipped brand
+// missing from the list makes peerBrandPresent() report "no peer" while that
+// brand survives, so the uninstall wipes device-wide singletons (~/.claude
+// OAuth, ~/.ollama cache, shared Neo4j data, apt packages) it still depends on.
+//
+// The list is intentionally a SUPERSET of brands/ (it carries legacy hostnames
+// and reserved slots that have no brand.json), so this is a subset check, not
+// an equality check. The reverse direction is not constrained.
+//
+// Runs via Node's built-in test runner (the codebase convention — see
+// peer-brand-detect.test.ts). Path resolution mirrors base-toolchain-deps.test.ts.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve, join } from "node:path";
+import { KNOWN_BRAND_HOSTNAMES } from "../known-brands.js";
+// dist/__tests__/known-brand-hostnames.test.js → maxy-code/brands
+const here = dirname(fileURLToPath(import.meta.url));
+const BRANDS_DIR = resolve(here, "../../../../brands");
+function shippedBrandHostnames() {
+    return readdirSync(BRANDS_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => join(BRANDS_DIR, e.name, "brand.json"))
+        .filter((p) => existsSync(p))
+        .map((p) => JSON.parse(readFileSync(p, "utf-8")).hostname);
+}
+test("brands/ directory is discoverable from the test location", () => {
+    assert.ok(existsSync(BRANDS_DIR), `brands dir not found at ${BRANDS_DIR}`);
+    assert.ok(shippedBrandHostnames().length > 0, "no shipped brand.json hostnames found");
+});
+test("every shipped brand hostname is in KNOWN_BRAND_HOSTNAMES", () => {
+    const allow = new Set(KNOWN_BRAND_HOSTNAMES);
+    for (const hostname of shippedBrandHostnames()) {
+        assert.ok(allow.has(hostname), `brands/ ships hostname "${hostname}" but it is absent from KNOWN_BRAND_HOSTNAMES; ` +
+            `peerBrandPresent() would not detect a co-resident "${hostname}" install`);
+    }
+});

package/dist/__tests__/neo4j-teardown.test.js

@@ -0,0 +1,55 @@
+// Contract grid for resolveDedicatedNeo4jTeardown — the pure decision behind
+// the uninstall's dedicated-Neo4j decommission. The wrapper in uninstall.ts
+// owns fs/systemctl; this suite is decision-only, no I/O.
+//
+// The load-bearing guarantee: the dedicated-removal path NEVER targets the
+// bare `neo4j` service / port 7687, including when the brand port is
+// unreadable (undefined). Runs via Node's built-in test runner (the codebase
+// convention — see peer-brand-detect.test.ts).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolveDedicatedNeo4jTeardown, SHARED_NEO4J_PORT } from "../neo4j-teardown.js";
+const HOST = "sitedesk-code";
+test("dedicated port → full teardown plan with install-parity names", () => {
+    const plan = resolveDedicatedNeo4jTeardown({ brandHostname: HOST, neo4jPort: 7689 });
+    assert.notEqual(plan, null);
+    // Names derive from BRAND.hostname exactly as setupDedicatedNeo4j creates them.
+    assert.deepEqual(plan, {
+        service: "neo4j-sitedesk-code",
+        unitFile: "/etc/systemd/system/neo4j-sitedesk-code.service",
+        confDir: "/etc/neo4j-sitedesk-code",
+        dataDir: "/var/lib/neo4j-sitedesk-code",
+        logDir: "/var/log/neo4j-sitedesk-code",
+    });
+});
+test("dedicated plan never names the shared `neo4j` service", () => {
+    const plan = resolveDedicatedNeo4jTeardown({ brandHostname: HOST, neo4jPort: 7689 });
+    assert.notEqual(plan, null);
+    assert.notEqual(plan.service, "neo4j");
+    for (const p of [plan.unitFile, plan.confDir, plan.dataDir, plan.logDir]) {
+        // No teardown path is the shared apt-managed location.
+        assert.notEqual(p, "/var/lib/neo4j");
+        assert.notEqual(p, "/etc/neo4j");
+        assert.notEqual(p, "/var/log/neo4j");
+        assert.notEqual(p, "/etc/systemd/system/neo4j.service");
+    }
+});
+test("shared port 7687 → null (shared path, never the dedicated removal)", () => {
+    assert.equal(resolveDedicatedNeo4jTeardown({ brandHostname: HOST, neo4jPort: SHARED_NEO4J_PORT }), null);
+});
+test("unreadable brand port (undefined) → null, never selects shared", () => {
+    // The defect this guards: a port-read failure must NOT fall through to the
+    // shared `neo4j`/7687. null tells the caller to take the shared path only
+    // when the brand is genuinely shared, never on read failure of a dedicated brand.
+    assert.equal(resolveDedicatedNeo4jTeardown({ brandHostname: HOST, neo4jPort: undefined }), null);
+});
+test("empty hostname → null (cannot form a dedicated unit)", () => {
+    assert.equal(resolveDedicatedNeo4jTeardown({ brandHostname: "", neo4jPort: 7689 }), null);
+});
+test("a different dedicated port still yields a hostname-derived plan", () => {
+    // Unit/dir names depend on hostname, not the port value — a forced
+    // --neo4j-port that differs from brand.json still tears down the same unit.
+    const plan = resolveDedicatedNeo4jTeardown({ brandHostname: "realagent-code", neo4jPort: 7700 });
+    assert.equal(plan.service, "neo4j-realagent-code");
+    assert.equal(plan.dataDir, "/var/lib/neo4j-realagent-code");
+});

package/dist/known-brands.js

@@ -0,0 +1,24 @@
+// Allowlist of brand hostnames in the Maxy ecosystem. peerBrandPresent() in
+// uninstall.ts matches systemd unit filenames (`<hostname>.service` and
+// `<hostname>-edge.service`) against this list to decide whether a co-resident
+// brand is still installed — the gate on every device-wide teardown step
+// (shared ~/.claude / ~/.ollama wipe, shared Neo4j data wipe, apt purge,
+// Ollama/Samba teardown). Matching only these filenames, not any stray
+// `.service` file, keeps stale units and unrelated user services from counting
+// as peer evidence.
+//
+// This list is a SUPERSET of the brands shipped under `brands/`: `maxy` and
+// `realagent` are legacy hostnames, `maxy-2/3/4` are reserved slots. Every
+// hostname under `brands/*/brand.json` MUST appear here, or peerBrandPresent()
+// fails to detect that brand as a peer. known-brand-hostnames.test.ts enforces
+// that subset relationship and fails when a new shipped brand is missing.
+export const KNOWN_BRAND_HOSTNAMES = [
+    "maxy",
+    "maxy-code",
+    "realagent",
+    "realagent-code",
+    "sitedesk-code",
+    "maxy-2",
+    "maxy-3",
+    "maxy-4",
+];

package/dist/neo4j-teardown.js

@@ -0,0 +1,45 @@
+// Pure dedicated-Neo4j teardown resolution. Extracted from uninstall.ts so the
+// "does this brand run a dedicated Neo4j, and what does its full decommission
+// target?" decision can be unit-tested with concrete inputs, no fs/systemctl.
+// Mirrors the peer-brand-detect.ts pattern: inputs in, plan out, no I/O.
+//
+// The uninstaller wraps this with the privileged stop/disable/rm and the
+// daemon-reload; this module owns only the naming + the shared-instance guard.
+/** The apt-installed shared Neo4j binds this bolt port. A brand on this port
+ *  is NOT dedicated — it shares the device-wide instance. */
+export const SHARED_NEO4J_PORT = 7687;
+/**
+ * Resolve the dedicated-Neo4j teardown plan for a brand, or `null` when the
+ * brand does not run a dedicated instance.
+ *
+ * Returns `null` — i.e. the dedicated-removal path must NOT act, and the caller
+ * falls back to its shared handling — in every case where targeting a dedicated
+ * unit would be wrong or unsafe:
+ *   - `neo4jPort === undefined`: the port is unreadable. A read failure must
+ *     never select the shared `neo4j`/7687 service; returning null keeps the
+ *     dedicated path inert rather than guessing.
+ *   - `neo4jPort === SHARED_NEO4J_PORT`: the brand genuinely shares 7687.
+ *   - empty `brandHostname`: no hostname means no `neo4j-<hostname>` unit can
+ *     exist; refuse rather than form a degenerate `neo4j-` name.
+ *
+ * When a plan IS returned, `service` is always `neo4j-<hostname>` and can never
+ * equal the bare `neo4j` — the hard guard against ever stopping or deleting the
+ * shared instance.
+ */
+export function resolveDedicatedNeo4jTeardown(args) {
+    const { brandHostname, neo4jPort } = args;
+    if (neo4jPort === undefined)
+        return null;
+    if (neo4jPort === SHARED_NEO4J_PORT)
+        return null;
+    if (!brandHostname)
+        return null;
+    const service = `neo4j-${brandHostname}`;
+    return {
+        service,
+        unitFile: `/etc/systemd/system/${service}.service`,
+        confDir: `/etc/neo4j-${brandHostname}`,
+        dataDir: `/var/lib/neo4j-${brandHostname}`,
+        logDir: `/var/log/neo4j-${brandHostname}`,
+    };
+}

package/dist/uninstall.js

@@ -4,6 +4,8 @@ import { resolve, join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { removeBrandStanza, hasAnyBrandStanza } from "./samba-provision.js";
+import { resolveDedicatedNeo4jTeardown } from "./neo4j-teardown.js";
+import { KNOWN_BRAND_HOSTNAMES } from "./known-brands.js";
 const HOME = homedir();
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive brand-specific installation paths.
@@ -97,13 +99,6 @@ function commandExists(cmd) {
 export function isMaxyInstalled() {
     return existsSync(INSTALL_DIR);
 }
-/** Known brand hostnames in the Maxy ecosystem. Each brand ships a main unit
- *  (`<hostname>.service`) and a per-brand edge unit
- *  (`<hostname>-edge.service`). Peer detection matches only these filenames, not any stray
- *  `.service` file — stale units, gnome-keyring disable markers, and unrelated
- *  user services are not peer evidence. When a third brand is
- *  added under `brands/`, append its hostname here. */
-const KNOWN_BRAND_HOSTNAMES = ["maxy", "maxy-code", "realagent", "realagent-code", "maxy-2", "maxy-3", "maxy-4"];
 /** Detect whether another brand is installed on this device.
  *  device-wide steps (apt package purge, Ollama binary removal, apt
  *  repo cleanup, ~/.claude / ~/.ollama wipes) must skip when a peer brand is
@@ -166,20 +161,26 @@ function stopServices() {
     catch {
         console.log(`  ${edgeUnitShort} not running`);
     }
-    // Stop Neo4j — dedicated branded instance if this brand uses one, else shared.
-    // Brand isolation: never stop `neo4j.service` when this brand runs
-    // a dedicated `neo4j-<hostname>.service` — stopping the shared instance would
-    // break every other brand on the device.
-    const neo4jPortForStop = readNeo4jPortFromEnv();
-    const neo4jService = neo4jPortForStop !== undefined && neo4jPortForStop !== 7687
-        ? `neo4j-${BRAND.hostname}`
-        : "neo4j";
-    try {
-        spawnSync("sudo", ["systemctl", "stop", neo4jService], { stdio: "pipe", timeout: 15_000 });
-        console.log(`  Stopped ${neo4jService}`);
+    // Stop Neo4j. A dedicated brand's instance is stopped AND disabled here so it
+    // does not return at the next boot; the unit file and data/config/log dirs are
+    // removed in step 5 (removeNeo4jData). Hard guard: when the brand is dedicated
+    // the target is always `neo4j-<hostname>` — the shared `neo4j`/7687 instance is
+    // never stopped, even if `.env` is unreadable (dedicatedNeo4jTeardown falls
+    // back to brand.json, never to the shared service). A genuinely shared brand
+    // (port 7687 / no dedicated port) stops the shared `neo4j` as before.
+    const neo4jTeardown = dedicatedNeo4jTeardown();
+    if (neo4jTeardown) {
+        if (privilegedSystemctl("stop", neo4jTeardown.service)) {
+            console.log(`  Stopped ${neo4jTeardown.service}`);
+        }
+        if (privilegedSystemctl("disable", neo4jTeardown.service)) {
+            console.log(`  Disabled ${neo4jTeardown.service}`);
+        }
     }
-    catch {
-        console.log(`  ${neo4jService} not running`);
+    else {
+        if (privilegedSystemctl("stop", "neo4j")) {
+            console.log("  Stopped neo4j (shared instance)");
+        }
     }
     // Stop the cloudflared service for this brand (Task 757 — the connector now
     // runs as a supervised cloudflared-<brand>.service, not a transient scope).
@@ -438,22 +439,36 @@ function removeNeo4jData() {
     // 7687 data is skipped entirely when a peer brand is present. Dedicated
     // branded instances live at /var/lib/neo4j-<hostname>/ and are always
     // this-brand-owned by construction.
-    const envPort = readNeo4jPortFromEnv();
-    const isDedicated = envPort !== undefined && envPort !== 7687;
-    const dataDir = isDedicated ? `/var/lib/neo4j-${BRAND.hostname}` : "/var/lib/neo4j";
-    if (!isDedicated && peerBrandPresent()) {
-        console.log(`  Shared Neo4j instance on 7687 — peer brand present, skipping data wipe.`);
+    const teardown = dedicatedNeo4jTeardown();
+    if (teardown) {
+        // Full decommission of the dedicated instance. Stop + disable already ran
+        // in step 1 (stopServices); here we remove every artifact the installer's
+        // setupDedicatedNeo4j() created — unit file, config dir, data dir, log dir —
+        // then daemon-reload so systemd forgets the unit. Removing the whole data
+        // dir (not just data/) also clears the install's plugins/ and import/ trees;
+        // the log dir is /var/log/neo4j-<hostname> (server.directories.logs), not a
+        // subdir of the data dir.
+        const paths = [teardown.unitFile, teardown.confDir, teardown.dataDir, teardown.logDir];
+        for (const p of paths) {
+            if (existsSync(p)) {
+                try {
+                    shell("rm", ["-rf", p], { sudo: true });
+                    console.log(`  Removed ${p}`);
+                }
+                catch (err) {
+                    console.log(`  Failed to remove ${p}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        privilegedSystemctl("daemon-reload");
         return;
     }
-    const paths = [`${dataDir}/data`, `${dataDir}/logs`];
-    if (isDedicated) {
-        // Also clean up the dedicated config dir and systemd unit — install-time
-        // code creates both at /etc/neo4j-<hostname>/ and /etc/systemd/system/
-        // neo4j-<hostname>.service. Shared instance owns neither.
-        paths.push(`/etc/neo4j-${BRAND.hostname}`);
-        paths.push(`/etc/systemd/system/neo4j-${BRAND.hostname}.service`);
+    // Shared instance on 7687 — skip entirely when a peer brand still depends on it.
+    if (peerBrandPresent()) {
+        console.log(`  Shared Neo4j instance on 7687 — peer brand present, skipping data wipe.`);
+        return;
     }
-    for (const p of paths) {
+    for (const p of ["/var/lib/neo4j/data", "/var/lib/neo4j/logs"]) {
         if (existsSync(p)) {
             try {
                 shell("rm", ["-rf", p], { sudo: true });
@@ -464,15 +479,9 @@ function removeNeo4jData() {
             }
         }
     }
-    if (isDedicated) {
-        try {
-            spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "pipe" });
-        }
-        catch { /* ignore */ }
-    }
 }
 /** Read NEO4J_URI port from this brand's .env. Returns undefined when the
- *  file is missing or malformed — caller treats that as "assume shared 7687". */
+ *  file is missing or malformed — caller folds in the brand.json fallback. */
 function readNeo4jPortFromEnv() {
     const envPath = join(CONFIG_DIR, ".env");
     if (!existsSync(envPath))
@@ -488,6 +497,46 @@ function readNeo4jPortFromEnv() {
         return undefined;
     }
 }
+/** Resolve this brand's dedicated-Neo4j teardown plan, or null when the brand
+ *  runs the shared instance. The port is `.env` (the actual running config,
+ *  preserving the installer's own port priority — this is where a `--neo4j-port`
+ *  override lands) with brand.json as the robust fallback. The result is
+ *  memoised on first call: stopServices (step 1) is the first caller and runs
+ *  while `~/<configDir>/.env` still exists; removeAppDirs (step 4) deletes that
+ *  `.env` before removeNeo4jData (step 5) calls again, so without the cache the
+ *  two call sites could classify dedication differently (step 1 sees the
+ *  override port, step 5 sees only brand.json) and orphan the dedicated dirs.
+ *  Caching the first (env-informed) resolution keeps stop/disable and dir
+ *  removal targeting the same instance. A read failure can never fall through
+ *  to the shared `neo4j`/7687 service. Dedicated names are `neo4j-<hostname>`,
+ *  matching `setupDedicatedNeo4j()`. */
+let _dedicatedNeo4jTeardownResolved = false;
+let _dedicatedNeo4jTeardownPlan = null;
+function dedicatedNeo4jTeardown() {
+    if (_dedicatedNeo4jTeardownResolved)
+        return _dedicatedNeo4jTeardownPlan;
+    const neo4jPort = readNeo4jPortFromEnv() ?? BRAND.neo4jPort;
+    _dedicatedNeo4jTeardownPlan = resolveDedicatedNeo4jTeardown({ brandHostname: BRAND.hostname, neo4jPort });
+    _dedicatedNeo4jTeardownResolved = true;
+    return _dedicatedNeo4jTeardownPlan;
+}
+/** Run a privileged `systemctl <args...>` interactively so a password prompt is
+ *  visible (the silent `stdio:"pipe"` no-op is the defect being fixed). Exit 5
+ *  (no such unit) is an acceptable end-state — the unit is already absent, which
+ *  keeps re-runs idempotent. Any other non-zero is a genuine failure (e.g. sudo
+ *  auth declined) and is surfaced loudly rather than swallowed. Returns true on
+ *  success or "already absent". Cannot delegate to shell(): shell() throws on
+ *  any non-zero, which would abort the uninstall on an already-absent unit. */
+function privilegedSystemctl(...args) {
+    const result = spawnSync("sudo", ["systemctl", ...args], { stdio: "inherit", timeout: 30_000 });
+    if (result.status === 0)
+        return true;
+    if (result.status === 5)
+        return true; // no such unit — already gone
+    const reason = result.signal ? `signal ${result.signal}` : `exit ${result.status}`;
+    console.error(`  FAILED: sudo systemctl ${args.join(" ")} (${reason}) — privileged step did not complete`);
+    return false;
+}
 // ---------------------------------------------------------------------------
 // Step 6: Purge system packages
 // ---------------------------------------------------------------------------

package/package.json

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

package/payload/platform/config/brand.json

@@ -39,7 +39,8 @@
   "assets": {
     "logo": "maxy-square.png",
     "icon": "maxy-monochrome.png",
-    "favicon": "favicon.ico"
+    "favicon": "favicon.ico",
+    "ogCard": "maxy-og-image.png"
   },
 
   "npm": {

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:629438b78a0fc02b849e76a11b93ffcaa69ae9f39af7fde2a5788b823424c039
+content-hash: sha256:7276f9a571c11e5350ab9a29cdc60f6416f4f0b685f58679217efff1b53413e9
 brand: maxy-code
 product-name: Maxy
 ---
@@ -2334,6 +2334,8 @@ either is a regression.
 
 **`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp reader (`/whatsapp`) omits the prop and keeps the default `renderTimeline`, so its rendering is unchanged; both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.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`.
 
+**`/chat` live activity line.** While a turn is in flight the transcript tail shows one ephemeral `ChatActivity` line (mounted only while `busy`, admin/operator only). It tracks real activity, not a timer: while a `Task` subagent runs it shows that subagent's headline (`agentType · description`, prefixed `N agents ·` when ≥2 are concurrent), sourced from `agent-<hex>.meta.json` via named `activity` SSE events the admin reader pushes from the session's `subagents/` dir; with no subagent active it shows a neutral word that advances only on a real turn arrival. The line carries a turn-elapsed clock and flips to a `stalled` state once nothing has been written for 5 minutes (`now − lastEmitAt`), so the operator can tell a wedge from progress without SSH. It is never added to the persisted timeline. Detail and the `[webchat-activity]` observability live in [`admin-webchat-native-channel.md`](../../../.docs/admin-webchat-native-channel.md).
+
 **maxy title for public sessions.** A `role=public` webchat spawn never produces a useful Claude Code `ai-title` (an anonymous one-line visitor turn), so every public row would otherwise read identically. The webchat route (`chat.ts`) composes a deterministic title — `Web · <senderId[:8]>[ · <personId>] · <UTC YYYY-MM-DD HH:mm>` (personId present only for gated visitors) — and threads it through the native webchat gateway's public spawn (`handleInbound` → `buildPublicWebchatSpawnRequest` → `managerSpawn`) to the manager `POST /public-spawn` body as `name`. `/spawn` validates it with `validateUserTitle` and, for `role=public` only, writes it into `UserTitleStore` so it occupies the operator-rename tier and wins over `ai-title`. Admin (`/rc-spawn`) and WhatsApp titling are unchanged. Observability: every public spawn logs `[spawn] role=public … title="…"` (or `title=missing`); the manager's row builder emits `[public-title] sessionId=… unexpected titleSource=<ai|null>` on the next list read for any public row that did not resolve from the user tier.
 
 **Public visitor surface.** The public-host root (`GET /`), the `/:slug` agent routes, and the admin-host `/public` / `/public-chat` previews all serve one shell, `public.html` → [`app/public-entry.tsx`](../../../ui/app/public-entry.tsx) → `PublicChat`. `PublicChat` reuses `useSession` purely as the magic-link gatekeeper — it drives `AccessGate`, resolves the agent slug from the path, and handles `?token=` verification; once the grant is satisfied it mounts `ChatSurface variant="public"`, whose transcript reads the visitor-scoped, **delivered-only** stream `GET /api/public-reader/stream` ([`server/routes/public-reader.ts`](../../../ui/server/routes/public-reader.ts)) — the visitor sees the agent's delivered prose, never the tool/tool-result/directive bytes the legacy `/api/chat` SSE render exposed. The human visitor's branding is resolved client-side by `useSession`. For the head only, the server injects per-agent link-preview meta — `<title>`, `og:title`/`og:description`/`og:image`, `theme-color`, and a per-agent favicon, resolved from the same branding cache `useSession` reads — into the served shell, so a link-preview crawler (which never runs the client bundle) gets a branded card per agent instead of one generic shell; an agent with no branding cache gets the clean brand-default shell with no empty meta tags. There is exactly one public client surface and it is 1:1 visitor↔agent: the earlier `?surface=next` A/B handle is retired, group messaging is retired (not a supported product surface), and a former `/g/<slug>` group URL now serves the same 1:1 shell — a stale bookmark gets the 1:1 chat, never a broken render.

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

@@ -32,6 +32,7 @@ The plugin registers no agent-facing MCP tools. Every Cloudflare operation is th
 | Skill | Purpose |
 |---|---|
 | [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, Open Graph correctness, and the cache-busted live-`200` done-gate; defers the command blocks to `hosting-sites.md` and `d1-data-capture.md`. Admin-run; a content specialist hands the deploy off to it. |
 
 ### References
 

package/payload/platform/plugins/cloudflare/skills/cloudflare/SKILL.md

@@ -16,6 +16,7 @@ This is the entry point for every Cloudflare task on the install. Pick the opera
 | Tear down corrupt tunnel state and start clean | `references/reset-guide.md` | a fresh `manual-setup.md` run reaches `200` |
 | Call the Cloudflare API (DNS, zones, tunnels, Access, token list/reuse/revoke) | `references/api.md` | the API call returns success and the change is observable |
 | Deploy a static / Next.js site to Cloudflare Pages | `references/hosting-sites.md` | the deployed URL serves the new build |
+| Take an approved content tree to a live site on its custom domain (canonical source, OG, optional D1 form, live verify) | `Skill site-deploy` | cache-busted `200` on the custom domain with correct content + `og:*`; a form site records a test POST to D1 |
 | Capture form/waitlist submissions into a database | `references/d1-data-capture.md` | a test POST appears in `SELECT … WHERE swept = 0` |
 | Diagnose / enable Web Analytics on a site (0 visitors, no data) | `references/web-analytics.md` | beacon present in live HTML (`curl -s https://<host>/ \| grep cloudflareinsights`) |
 

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

@@ -0,0 +1,84 @@
+---
+name: site-deploy
+description: Assemble an approved content tree into a live Cloudflare Pages deployment on its custom domain that survives the install device being offline. This is the skill behind "deploy this site", "put this landing page / investor site / microsite live on its own domain", "publish the waitlist site", and "the live site is stale / shows the wrong brand". It takes one canonical source tree, reuses the per-scope Pages-and-D1 token from the account secrets file, runs `wrangler pages deploy` to the production alias, attaches the custom domain, wires a contact or waitlist form to D1 when the tree carries one, and gates "done" on a cache-busted live `200` with correct content and Open Graph metadata on the production domain. Admin-run; it holds Bash and the account secrets surface. Distinct from `admin:publish-site` (device-tunnel hosting that dies when the device goes offline) and from `sitedesk:microsite` (single-page builder that stops before deploy).
+---
+
+# Deploy a site to Cloudflare Pages
+
+Run by the admin/main session, the operator-infra surface that holds the `Bash` tool and reads the account secrets file. A content specialist authors and approves the site tree; the deploy itself is admin work because it touches the Cloudflare account credentials. When a `content-producer` finishes a site, it hands the deploy off to admin, which loads this skill.
+
+This skill is an outcome contract, not a second copy of the Pages mechanics. The mechanics live in the cloudflare references; this skill names the canonical source convention, the auth discipline, the form-to-D1 wiring trigger, the Open Graph correctness check, and the live done-gate, then defers each command block to the matching reference. Read `references/hosting-sites.md` (build, `wrangler pages deploy`, custom domain) and `references/d1-data-capture.md` (form to Pages Function to D1) via `plugin-read` before issuing those commands; read `references/api.md` for the token discipline.
+
+## When this skill, not another
+
+| Situation | Skill |
+|---|---|
+| A standalone site (landing, investor, waitlist, microsite output) goes live on its own custom domain, hosted on Cloudflare's edge, surviving the install device being offline | **this skill** |
+| Serve content that the install device itself renders, at a custom domain over the brand tunnel | `admin:publish-site` (device-tunnel `/sites/` path) |
+| Build a single-page site from a brief | `sitedesk:microsite` (it stops before deploy; its output tree is then deployed by this skill) |
+
+`admin:publish-site` serves from the install device through the brand tunnel: when the device is offline the site is unreachable. This skill puts the site on Cloudflare Pages, so it stays up independent of the device. Name the distinction when the operator's intent is ambiguous, and pick by whether the site must survive the device going offline.
+
+## One canonical source tree
+
+Each site is driven by exactly one source tree at:
+
+```
+<accountDir>/pages/<project>/
+```
+
+`<project>` is the slug of the site's graph node (the `:Organization` or site entity the site represents), so there is one deterministic path per site and no second copy to reconcile. The tree holds the framework source, `wrangler.toml`, the built output directory, and `functions/api/contact.ts` when the site captures form data.
+
+There is never a `sites/<brand>/` versus `output/<brand>-site/` pair, a `.bak` clone, or a stale sibling. If more than one candidate tree exists when you start, reconcile to the single canonical path first: confirm which tree is current, move it to `<accountDir>/pages/<project>/`, and remove the others before deploying. Deploying from an unreconciled tree is the root cause of the dev/live drift this skill exists to prevent. `<accountDir>/pages/` is distinct from `<accountDir>/sites/`, which belongs to the device-tunnel `admin:publish-site` path; the two never share a directory.
+
+## Auth: reuse the per-scope token, never mint ad hoc
+
+A Pages deploy needs **Account · Cloudflare Pages · Edit**. A site with a D1-backed form also needs **Account · D1 · Edit** on the same token. 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` § Provisioning and reusing a stable per-scope token and `references/d1-data-capture.md` § 0 prescribe. The token is never written into the project tree, never committed, never echoed into chat. The master token stays in the secrets file. Surface every command as verb plus target ("deploying Pages project `<project>`"); `wrangler` prints the deployment URL, which is what gets relayed.
+
+## Deploy and attach the custom domain
+
+Follow `references/hosting-sites.md`: build the framework output, write `wrangler.toml` (the project name is `<project>`, the output dir is the framework default), and `wrangler pages deploy <output-dir> --project-name <project> --branch=main` to the production alias. Attach the custom domain to the Pages project via the Cloudflare API with the reused `<brand>-pages-d1` token (the operator clicks **Workers & Pages → project → Custom domains** in the dashboard only when they prefer to do it by hand), so the site answers on the operator's domain, not only on `<project>.pages.dev`.
+
+Attaching the custom domain to the project is not the same as the domain resolving. The attach leaves validation **pending** until a DNS record in the zone points the hostname at the Pages site; until that record exists the domain returns `NXDOMAIN` and the page is unreachable. Confirm the record exists and create it when it does not:
+
+- A **subdomain** custom domain (`investors.example.com`) needs a `CNAME` to `<project>.pages.dev`.
+- An **apex** custom domain (`example.com`) cannot hold a literal CNAME, so it needs a **proxied (flattened) CNAME** at the apex to `<project>.pages.dev`, plus a `www` CNAME if `www` is also served. This is the case the attach most often leaves pending.
+
+Creating that DNS record is a **DNS-scope** operation, not a Pages-scope one: the `<brand>-pages-d1` token returns a `10000 Authentication error` on the DNS endpoint. Use the DNS-scoped `<brand>-dns` token, exactly as `cloudflare/SKILL.md` § Apex hostnames and `references/api.md` § DNS records prescribe, minting it once if absent. The hostname's zone must be on the same Cloudflare account; a hostname whose zone lives in a different account is reached with that account's own `<brand>-dns` token, never by probing a drawer of ad-hoc `CF_DNS_TOKEN_*` strays (that token sprawl is what the `references/api.md` reconcile pass exists to clear). The custom domain is the surface the done-gate checks, so a missing record fails the gate rather than passing silently.
+
+## Wire the form to D1 when one exists
+
+When the canonical tree carries a contact or waitlist form, the deploy is not complete until that form records to D1. Follow `references/d1-data-capture.md`: create the database, add the `[[d1_databases]]` binding to `wrangler.toml`, create the table, and ship `functions/api/contact.ts`. The token from the auth step already carries D1 Edit, so the form does not silently 500 at the insert. A site with no form skips this section.
+
+## Open Graph correctness
+
+The live page must carry brand-correct Open Graph metadata: `<meta property="og:title">`, `og:description`, `og:image`, and `og:url` reflecting this site and this brand, not a leftover from whatever the tree was cloned from. Stale OG (a live card still naming a previous brand) is a recorded failure mode of hand deployment. Confirm the `og:*` tags in the deployed HTML are correct before claiming done; if they are stale, fix them in the source tree, redeploy, and re-check.
+
+## Done-gate: a live cache-busted 200 on the custom domain
+
+"Done" is never "I ran deploy". It is a live behavioural signal on the **production custom domain**, surfaced verbatim in chat:
+
+```bash
+curl -s "https://<custom-domain>/?cb=$(date +%s)" -D - -o /tmp/site.html | head -1
+grep -o '<meta property="og:[^>]*>' /tmp/site.html
+```
+
+The done-gate passes only when all hold:
+
+- the domain resolves at all: a `NXDOMAIN` or "could not resolve host" means the custom-domain DNS record was never created, so go back to the custom-domain step and create the CNAME with the `<brand>-dns` token; a `522` is the certificate-provisioning window, so wait and re-curl rather than treating it as done,
+- the status line is `HTTP/2 200` (or `HTTP/1.1 200 OK`),
+- the body carries an expected content marker for this site (a brand string or headline you can name in advance), not a stale marker from a previous brand,
+- the `og:*` tags are present and brand-correct,
+- for a form-bearing site, a test POST appears in D1 unswept, per `references/d1-data-capture.md` § Outcome contract. This sub-check reuses the same `${PAGES_D1}` token and `<db-name>` already loaded when the form was wired, not a fresh token:
+
+```bash
+curl -sS -X POST -d "email=test@example.com&name=verify" "https://<custom-domain>/api/contact" -i | head -1
+CLOUDFLARE_API_TOKEN="${PAGES_D1}" wrangler d1 execute <db-name> --remote --command \
+  "SELECT email FROM leads WHERE swept = 0;"
+```
+
+Any other status, a missing or stale content marker, an OG mismatch, or a form POST that does not land in D1 blocks "done" and is reported with the exact failing URL. Record the deployment alias and the cache-busted verification command in the result so a later operator re-runs the same check against the custom domain to confirm live state without reading source.
+
+## Tool discipline
+
+The permitted surface is `wrangler`, `curl`, and the Cloudflare API via Bash following the cloudflare references, using the reused per-scope token. The agent does not mint a fresh token per deploy, does not drive the dashboard with Playwright or Chrome DevTools, does not synthesise `wrangler` flags from web search, and never writes or echoes a token. When a step fails, report the exact output with secrets redacted, name the failing URL or command, and stop.

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

@@ -69,6 +69,8 @@ either is a regression.
 
 **`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp reader (`/whatsapp`) omits the prop and keeps the default `renderTimeline`, so its rendering is unchanged; both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.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`.
 
+**`/chat` live activity line.** While a turn is in flight the transcript tail shows one ephemeral `ChatActivity` line (mounted only while `busy`, admin/operator only). It tracks real activity, not a timer: while a `Task` subagent runs it shows that subagent's headline (`agentType · description`, prefixed `N agents ·` when ≥2 are concurrent), sourced from `agent-<hex>.meta.json` via named `activity` SSE events the admin reader pushes from the session's `subagents/` dir; with no subagent active it shows a neutral word that advances only on a real turn arrival. The line carries a turn-elapsed clock and flips to a `stalled` state once nothing has been written for 5 minutes (`now − lastEmitAt`), so the operator can tell a wedge from progress without SSH. It is never added to the persisted timeline. Detail and the `[webchat-activity]` observability live in [`admin-webchat-native-channel.md`](../../../.docs/admin-webchat-native-channel.md).
+
 **maxy title for public sessions.** A `role=public` webchat spawn never produces a useful Claude Code `ai-title` (an anonymous one-line visitor turn), so every public row would otherwise read identically. The webchat route (`chat.ts`) composes a deterministic title — `Web · <senderId[:8]>[ · <personId>] · <UTC YYYY-MM-DD HH:mm>` (personId present only for gated visitors) — and threads it through the native webchat gateway's public spawn (`handleInbound` → `buildPublicWebchatSpawnRequest` → `managerSpawn`) to the manager `POST /public-spawn` body as `name`. `/spawn` validates it with `validateUserTitle` and, for `role=public` only, writes it into `UserTitleStore` so it occupies the operator-rename tier and wins over `ai-title`. Admin (`/rc-spawn`) and WhatsApp titling are unchanged. Observability: every public spawn logs `[spawn] role=public … title="…"` (or `title=missing`); the manager's row builder emits `[public-title] sessionId=… unexpected titleSource=<ai|null>` on the next list read for any public row that did not resolve from the user tier.
 
 **Public visitor surface.** The public-host root (`GET /`), the `/:slug` agent routes, and the admin-host `/public` / `/public-chat` previews all serve one shell, `public.html` → [`app/public-entry.tsx`](../../../ui/app/public-entry.tsx) → `PublicChat`. `PublicChat` reuses `useSession` purely as the magic-link gatekeeper — it drives `AccessGate`, resolves the agent slug from the path, and handles `?token=` verification; once the grant is satisfied it mounts `ChatSurface variant="public"`, whose transcript reads the visitor-scoped, **delivered-only** stream `GET /api/public-reader/stream` ([`server/routes/public-reader.ts`](../../../ui/server/routes/public-reader.ts)) — the visitor sees the agent's delivered prose, never the tool/tool-result/directive bytes the legacy `/api/chat` SSE render exposed. The human visitor's branding is resolved client-side by `useSession`. For the head only, the server injects per-agent link-preview meta — `<title>`, `og:title`/`og:description`/`og:image`, `theme-color`, and a per-agent favicon, resolved from the same branding cache `useSession` reads — into the served shell, so a link-preview crawler (which never runs the client bundle) gets a branded card per agent instead of one generic shell; an agent with no branding cache gets the clean brand-default shell with no empty meta tags. There is exactly one public client surface and it is 1:1 visitor↔agent: the earlier `?surface=next` A/B handle is retired, group messaging is retired (not a supported product surface), and a former `/g/<slug>` group URL now serves the same 1:1 shell — a stale bookmark gets the 1:1 chat, never a broken render.

package/payload/platform/templates/specialists/agents/content-producer.md

@@ -44,6 +44,8 @@ When a brief carries a "host this website" / "publish this site" / "put this onl
 
 Confirm the slug with the operator before publishing. The slug is one or more `/`-separated segments under `<accountDir>/sites/`. Refusals are loud-fail; relay the tool's `Operator action:` line verbatim and stop. On success, take the `pathSlug` from the tool response, call `mcp__plugin_admin_admin__public-hostname`, and surface `https://<hostname><pathSlug>` to the operator as one line.
 
+`publish-site` serves from the install device through the brand tunnel: when the device is offline the site is unreachable. When the brief instead wants a site live on its **own custom domain that survives the device being offline** (a Cloudflare Pages deployment), that is a different hosting model and a different seat. You do not hold Cloudflare account authority, so you do not deploy it yourself. Assemble and approve the one canonical source tree at `<accountDir>/pages/<project>/` (`<project>` = the slug of the site's graph node; no `sites/`-vs-`output/` duplicate), then hand the deploy back to the admin session to run `Skill site-deploy`, which owns the Cloudflare credentials, the form-to-D1 wiring, the Open Graph check, and the live cache-busted done-gate on the custom domain. Return to admin naming the canonical tree path and the expected custom domain.
+
 ## File delivery
 
 To deliver a generated file, write it under `accounts/<accountId>/output/` (any depth) and report its full `output/` path in your result. As a subagent you do not send the file yourself; the main session delivers it, and the path you report is what it delivers. On a turn that arrived over a message channel (web chat, WhatsApp, Telegram) the main session calls `SendUserFile` with the path and the platform forwards the file to that conversation as an attachment. On the admin dashboard the same `output/` file appears in the Artefacts panel and is reachable on the file share. See the `file-presentation` skill for the wording.

package/payload/server/{chunk-NE7G5GT7.js → chunk-5BG6CHGH.js}

@@ -3113,6 +3113,22 @@ function renderLoginPage(opts) {
   const displayFont = opts?.displayFont ?? "'Newsreader', Georgia, serif";
   const bodyFont = opts?.bodyFont ?? "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
   const logoContainsName = opts?.logoContainsName ?? false;
+  const tagline = opts?.tagline ?? "";
+  const origin = opts?.origin ?? "";
+  const ogCardPath = opts?.ogCardPath ?? "";
+  const ogBlock = origin && ogCardPath ? [
+    `<meta property="og:title" content="Sign in \u2014 ${escapeHtml(productName)}">`,
+    `<meta property="og:description" content="${escapeHtml(tagline)}">`,
+    `<meta property="og:type" content="website">`,
+    `<meta property="og:url" content="${escapeHtml(origin)}">`,
+    `<meta property="og:image" content="${escapeHtml(origin + ogCardPath)}">`,
+    `<meta property="og:image:width" content="1200">`,
+    `<meta property="og:image:height" content="630">`,
+    `<meta name="twitter:card" content="summary_large_image">`,
+    `<meta name="twitter:title" content="Sign in \u2014 ${escapeHtml(productName)}">`,
+    `<meta name="twitter:description" content="${escapeHtml(tagline)}">`,
+    `<meta name="twitter:image" content="${escapeHtml(origin + ogCardPath)}">`
+  ].join("\n  ") : "";
   const errorHtml = error ? `<p class="msg msg--error">${escapeHtml(error)}</p>` : "";
   const changeErrorHtml = changeError ? `<p class="msg msg--error">${escapeHtml(changeError)}</p>` : "";
   const successHtml = success ? `<p class="msg msg--success">${escapeHtml(success)}</p>` : "";
@@ -3148,6 +3164,7 @@ function renderLoginPage(opts) {
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Sign in \u2014 ${escapeHtml(productName)}</title>
   <link rel="icon" href="${escapeHtml(faviconPath)}">
+  ${ogBlock}
   ${googleFontsLink}
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }

package/payload/server/maxy-edge.js

@@ -16,7 +16,7 @@ import {
   sanitizeClientCorrId,
   vncLog,
   websockifyLog
-} from "./chunk-NE7G5GT7.js";
+} from "./chunk-5BG6CHGH.js";
 import "./chunk-PFF6I7KP.js";
 
 // server/edge.ts