@rubytech/create-maxy-code 0.1.538 → 0.1.540

package/payload/platform/plugins/admin/mcp/dist/tools/agent-config-schema.d.ts

@@ -0,0 +1,9 @@
+export type AgentConfigVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    field: string;
+    detail: string;
+};
+export declare function validateAgentConfig(config: unknown): AgentConfigVerdict;
+//# sourceMappingURL=agent-config-schema.d.ts.map

package/payload/platform/plugins/admin/mcp/dist/tools/agent-config-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config-schema.d.ts","sourceRoot":"","sources":["../../src/tools/agent-config-schema.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,kBAAkB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,kBAAkB,CAuCvE"}

package/payload/platform/plugins/admin/mcp/dist/tools/agent-config-schema.js

@@ -0,0 +1,49 @@
+import { isSelectableModel } from "../../../../../lib/models/dist/index.js";
+// What a public agent's config.json must satisfy to be servable.
+//
+// resolveAgentConfig (platform/ui/app/lib/claude-agent/account.ts) silently
+// defaults every bad field: an unknown status makes the agent unreachable with
+// no error, an unselectable model fails at spawn, a missing displayName renders
+// the slug in the chat header. Refusing at the write boundary turns each of
+// those into a message the operator reads before the file exists.
+//
+// Unknown keys pass. A forward-compatible field written by an unreleased
+// feature must not be rejected by a validator that predates it.
+const LEGAL_STATUS = ["active", "inactive"];
+const LEGAL_IMAGE_SHAPE = ["circle", "rounded"];
+const LEGAL_ACCESS_MODE = ["open", "gated", "paid"];
+const MAX_KNOWLEDGE_KEYWORDS = 5;
+export function validateAgentConfig(config) {
+    if (typeof config !== "object" || config === null || Array.isArray(config)) {
+        return { ok: false, field: "(root)", detail: "config must be a JSON object" };
+    }
+    const c = config;
+    if (typeof c.displayName !== "string" || c.displayName.trim() === "") {
+        return { ok: false, field: "displayName", detail: "required, must be a non-blank string" };
+    }
+    if (typeof c.model !== "string" || !isSelectableModel(c.model)) {
+        return { ok: false, field: "model", detail: "required, must be a selectable platform model id" };
+    }
+    if (typeof c.status !== "string" || !LEGAL_STATUS.includes(c.status)) {
+        return { ok: false, field: "status", detail: `required, must be one of ${LEGAL_STATUS.join(" | ")}` };
+    }
+    if (c.imageShape !== undefined && (typeof c.imageShape !== "string" || !LEGAL_IMAGE_SHAPE.includes(c.imageShape))) {
+        return { ok: false, field: "imageShape", detail: `must be one of ${LEGAL_IMAGE_SHAPE.join(" | ")} when present` };
+    }
+    if (c.accessMode !== undefined && (typeof c.accessMode !== "string" || !LEGAL_ACCESS_MODE.includes(c.accessMode))) {
+        return { ok: false, field: "accessMode", detail: `must be one of ${LEGAL_ACCESS_MODE.join(" | ")} when present` };
+    }
+    if (c.knowledgeKeywords !== undefined) {
+        if (!Array.isArray(c.knowledgeKeywords)) {
+            return { ok: false, field: "knowledgeKeywords", detail: "must be an array of strings when present" };
+        }
+        if (c.knowledgeKeywords.length > MAX_KNOWLEDGE_KEYWORDS) {
+            return { ok: false, field: "knowledgeKeywords", detail: `at most ${MAX_KNOWLEDGE_KEYWORDS} entries` };
+        }
+        if (c.knowledgeKeywords.some((k) => typeof k !== "string")) {
+            return { ok: false, field: "knowledgeKeywords", detail: "every entry must be a string" };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=agent-config-schema.js.map

package/payload/platform/plugins/admin/mcp/dist/tools/agent-config-schema.js.map

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

package/payload/platform/plugins/admin/mcp/dist/tools/agent-write.d.ts

@@ -0,0 +1,64 @@
+export type AgentWriteRefusal = "slug-unsafe" | "config-invalid" | "knowledge-empty" | "exists" | "not-found";
+export type AgentWriteResult = {
+    ok: true;
+    slug: string;
+    filesWritten: string[];
+} | {
+    ok: false;
+    reason: AgentWriteRefusal;
+    detail: string;
+};
+export interface CreateAgentArgs {
+    accountDir: string;
+    platformRoot: string;
+    slug: string;
+    displayName: string;
+    model: string;
+    soul: string;
+    knowledge: string;
+    knowledgeKeywords?: string[];
+    status?: string;
+    showAgentName?: boolean | "none";
+    accessMode?: string;
+}
+export interface UpdateAgentArgs {
+    accountDir: string;
+    slug: string;
+    displayName?: string;
+    model?: string;
+    soul?: string;
+    knowledge?: string;
+    knowledgeKeywords?: string[];
+    status?: string;
+    showAgentName?: boolean | "none";
+    accessMode?: string;
+}
+export declare function createAgent(args: CreateAgentArgs): AgentWriteResult;
+export declare function updateAgent(args: UpdateAgentArgs): AgentWriteResult;
+export interface ProjectOpts {
+    platformPort: string;
+    accountId: string;
+    slug: string;
+    houseAdminScope?: string;
+    /** Injected in tests. Production passes nothing and the global fetch is used. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Project the on-disk agent into the graph through the platform route that
+ * already owns the projector, rather than re-implementing the MERGE here. The
+ * returned `projected` is read from the response, never assumed: a write that
+ * succeeded with `projected=0` is the beagle state (files on disk, no :Agent
+ * node) and must be reportable as such.
+ *
+ * What authorises the call is the loopback peer, not the header:
+ * `authorizeAccountWrite` (platform/ui/server/routes/admin/_account-scope.ts:67)
+ * returns `via: "on-device"` for any 127.0.0.1 caller with no x-forwarded-for,
+ * and never reads x-maxy-caller-account. The header is still sent because it is
+ * the identity every other admin-MCP call to the platform carries, so the
+ * route's gate can tighten without this caller becoming the exception.
+ */
+export declare function projectAgentViaPlatform(opts: ProjectOpts): Promise<{
+    projected: number;
+    error?: string;
+}>;
+//# sourceMappingURL=agent-write.d.ts.map

package/payload/platform/plugins/admin/mcp/dist/tools/agent-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-write.d.ts","sourceRoot":"","sources":["../../src/tools/agent-write.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,gBAAgB,GAChB,iBAAiB,GACjB,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GAClD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8BD,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,gBAAgB,CAsDnE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,gBAAgB,CA4CnE;AAED,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB/G"}

package/payload/platform/plugins/admin/mcp/dist/tools/agent-write.js

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { checkAgentSlug } from "../../../../../lib/agent-slug/dist/index.js";
+import { validateAgentConfig } from "./agent-config-schema.js";
+function agentDirOf(accountDir, slug) {
+    return resolve(accountDir, "agents", slug);
+}
+/** Config fields the tools own. An absent optional is left out of the file
+ *  entirely rather than written as null, so the result matches what the admin
+ *  UI's creation form produces. */
+function buildConfig(base, args) {
+    const next = { ...base };
+    if (args.displayName !== undefined)
+        next.displayName = args.displayName;
+    if (args.model !== undefined)
+        next.model = args.model;
+    if (args.status !== undefined)
+        next.status = args.status;
+    if (args.knowledgeKeywords !== undefined)
+        next.knowledgeKeywords = args.knowledgeKeywords;
+    if (args.showAgentName !== undefined)
+        next.showAgentName = args.showAgentName;
+    if (args.accessMode !== undefined)
+        next.accessMode = args.accessMode;
+    return next;
+}
+export function createAgent(args) {
+    const verdict = checkAgentSlug(args.slug);
+    if (!verdict.ok)
+        return { ok: false, reason: "slug-unsafe", detail: verdict.reason };
+    const dir = agentDirOf(args.accountDir, args.slug);
+    if (existsSync(dir)) {
+        return { ok: false, reason: "exists", detail: `agents/${args.slug}/ already exists` };
+    }
+    if (args.knowledge.trim() === "") {
+        return { ok: false, reason: "knowledge-empty", detail: "KNOWLEDGE.md would be empty" };
+    }
+    const config = buildConfig({}, {
+        displayName: args.displayName,
+        model: args.model,
+        status: args.status ?? "active",
+        knowledgeKeywords: args.knowledgeKeywords,
+        showAgentName: args.showAgentName,
+        accessMode: args.accessMode,
+    });
+    const configVerdict = validateAgentConfig(config);
+    if (!configVerdict.ok) {
+        return { ok: false, reason: "config-invalid", detail: configVerdict.field };
+    }
+    // IDENTITY.md is Rubytech-controlled and copied verbatim. It is not a
+    // caller-supplied field: the toolless-public directive is the one part of a
+    // public agent the operator does not author. Read before mkdir so an absent
+    // template refuses instead of leaving three of the four files on disk.
+    const identityPath = resolve(args.platformRoot, "templates", "agents", "public", "IDENTITY.md");
+    if (!existsSync(identityPath)) {
+        return { ok: false, reason: "not-found", detail: `IDENTITY template missing at ${identityPath}` };
+    }
+    const identity = readFileSync(identityPath, "utf-8");
+    mkdirSync(dir, { recursive: true });
+    try {
+        writeFileSync(resolve(dir, "IDENTITY.md"), identity);
+        writeFileSync(resolve(dir, "SOUL.md"), args.soul);
+        writeFileSync(resolve(dir, "KNOWLEDGE.md"), args.knowledge);
+        writeFileSync(resolve(dir, "config.json"), `${JSON.stringify(config, null, 2)}\n`);
+    }
+    catch (err) {
+        // The directory did not exist before this call, so removing it restores the
+        // pre-call state exactly. A half-written agent is worse than none: it would
+        // fail the `exists` check on the retry.
+        rmSync(dir, { recursive: true, force: true });
+        throw err;
+    }
+    return { ok: true, slug: args.slug, filesWritten: ["IDENTITY.md", "SOUL.md", "KNOWLEDGE.md", "config.json"] };
+}
+export function updateAgent(args) {
+    const verdict = checkAgentSlug(args.slug);
+    if (!verdict.ok)
+        return { ok: false, reason: "slug-unsafe", detail: verdict.reason };
+    const dir = agentDirOf(args.accountDir, args.slug);
+    const configPath = resolve(dir, "config.json");
+    if (!existsSync(configPath)) {
+        return { ok: false, reason: "not-found", detail: `no config.json at agents/${args.slug}/` };
+    }
+    if (args.knowledge !== undefined && args.knowledge.trim() === "") {
+        return { ok: false, reason: "knowledge-empty", detail: "KNOWLEDGE.md would be empty" };
+    }
+    let base;
+    try {
+        base = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: "config-invalid",
+            detail: `existing config.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const config = buildConfig(base, args);
+    const configVerdict = validateAgentConfig(config);
+    if (!configVerdict.ok) {
+        return { ok: false, reason: "config-invalid", detail: configVerdict.field };
+    }
+    const written = [];
+    if (args.soul !== undefined) {
+        writeFileSync(resolve(dir, "SOUL.md"), args.soul);
+        written.push("SOUL.md");
+    }
+    if (args.knowledge !== undefined) {
+        writeFileSync(resolve(dir, "KNOWLEDGE.md"), args.knowledge);
+        written.push("KNOWLEDGE.md");
+    }
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    written.push("config.json");
+    return { ok: true, slug: args.slug, filesWritten: written };
+}
+/**
+ * Project the on-disk agent into the graph through the platform route that
+ * already owns the projector, rather than re-implementing the MERGE here. The
+ * returned `projected` is read from the response, never assumed: a write that
+ * succeeded with `projected=0` is the beagle state (files on disk, no :Agent
+ * node) and must be reportable as such.
+ *
+ * What authorises the call is the loopback peer, not the header:
+ * `authorizeAccountWrite` (platform/ui/server/routes/admin/_account-scope.ts:67)
+ * returns `via: "on-device"` for any 127.0.0.1 caller with no x-forwarded-for,
+ * and never reads x-maxy-caller-account. The header is still sent because it is
+ * the identity every other admin-MCP call to the platform carries, so the
+ * route's gate can tighten without this caller becoming the exception.
+ */
+export async function projectAgentViaPlatform(opts) {
+    const headers = {
+        "content-type": "application/json",
+        "x-maxy-caller-account": opts.accountId,
+    };
+    if (opts.houseAdminScope)
+        headers["x-maxy-house-admin-scope"] = opts.houseAdminScope;
+    const url = `http://127.0.0.1:${opts.platformPort}/api/admin/agents/${opts.slug}/project?accountId=${opts.accountId}`;
+    const doFetch = opts.fetchImpl ?? fetch;
+    try {
+        const res = await doFetch(url, { method: "POST", headers, signal: AbortSignal.timeout(5000) });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            return { projected: 0, error: `projection route returned ${res.status} ${body}`.trim() };
+        }
+        return { projected: 1 };
+    }
+    catch (err) {
+        return { projected: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=agent-write.js.map

package/payload/platform/plugins/admin/mcp/dist/tools/agent-write.js.map

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

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

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:08b03d80446b9b08b4b64926a3ac7d7f55a6f07d4182512dcca1d107c78cc9a2
+content-hash: sha256:3b275a96d70deb1ae39a1fe77c45c8dbc5beb65985a7c5fea62927b99c97e46b
 brand: maxy-code
 product-name: Maxy
 ---
@@ -1695,7 +1695,9 @@ Every turn carries a `source`. Three values exist:
 | `schedule` | The scheduler wrote this turn. The named destination did not send it. |
 | `public-relay` | The platform wrote this turn because a public visitor messaged the account. The named sender is a manager being told, not someone who wrote to you. |
 
-A `public-relay` turn also says so in its own first two lines. If a turn claims a manager wrote something they plainly would not have written, check the source before answering them.
+A `public-relay` turn also says so in its own first two lines, and states which handset its reply tool reaches. That handset is the manager's, never the visitor's: the turn runs in the manager's own admin session, so a reply written to the visitor is delivered to the manager. If a turn claims a manager wrote something they plainly would not have written, check the source before answering them.
+
+**On a `public-relay` turn the reply tool is the only way to reach anyone.** On an ordinary turn the platform forwards your closing text to the sender when you called no reply tool. On a relay-woken turn it does not, because the relay carries its own reply path. So whatever you decide the manager should receive has to go through the reply tool; text you merely write at the end of the turn reaches nobody, and a decision not to reply is silence rather than a message.
 
 ## Which files compose the prompt
 
@@ -1712,7 +1714,7 @@ A public agent's directory also carries `KNOWLEDGE.md` and `config.json`. An acc
 
 ## The switches, and what each one stops
 
-Four settings sit on this path. They are not interchangeable, and reaching for the wrong one is how an operator ends up silencing more than they meant.
+Five settings sit on this path. They are not interchangeable, and reaching for the wrong one is how an operator ends up silencing more than they meant.
 
 | Setting | What it stops | What it leaves running |
 |---|---|---|
@@ -1720,6 +1722,7 @@ Four settings sit on this path. They are not interchangeable, and reaching for t
 | `publicAgentEnabled: false` | The visitor gets no reply. | The manager notification and the relay. |
 | `managerNotifyEnabled: false` | The verbatim copy of the visitor's message. | The relay, and any reply the woken turn sends. |
 | `dispatchInbound: false` | Every agent turn on that account's socket. | Storage: messages are still stored and readable. |
+| `dispatch: false` on one registered party | The public-agent turn for that one phone. | Everything else: storage, the label, the manager notification, the relay, and every other sender on the line. |
 
 `managerNotifyEnabled` is the fine-grained one, and the one to reach for when the notifications are unwanted but the work is not. Unbinding a manager is not a substitute: the manager registry is shared by the notification, the relay and `whatsapp-notify-manager`, so unbinding silences all three.
 
@@ -1727,19 +1730,37 @@ Read the current value with `whatsapp-config {action:'get-manager-notify-enabled
 
 ## When the answer is not here
 
-`logs-read --tail server` and filter on the tags. One public inbound writes this chain, in order, with `account=` and `sender=` on each line:
+`logs-read --tail server` and filter on the tags. One public inbound writes this chain, in order:
+
+```
+[whatsapp:wire]         op=stanza          msgId=<id>
+[wa-notify]             op=eligible        msgId=<id> reason=<how the sender was admitted>
+[whatsapp:route]        op=routed          inboundId=<id> msgIds=<the stanzas this payload covers>
+[whatsapp:notify]       op=public-inbound  inboundId=<id> enabled=0|1 outcome=sent|failed|no-recipients|disabled
+[whatsapp:relay]        op=dispatch        inboundId=<id> outcome=sent|failed|no-recipients
+[whatsapp:party]        op=dispatch-decision  inboundId=<id> party=… dispatch=true|false spawned=0|1   (labelled senders only)
+[whatsapp:public-agent] op=route           inboundId=<id> enabled=… slug=… spawned=0|1
+[whatsapp:public-agent] op=spawn-ok | op=spawn-failed   inboundId=<id>
+```
+
+Follow one inbound by its `inboundId`. That selects the last five lines and nothing else, however many visitors messaged in the same window. For the first two, read `msgIds=` off the `op=routed` line and grep one of those ids. Two greps rather than one, because the debouncer merges stanzas into a single routed payload and the two halves are keyed either side of that merge.
+
+Anything that failed carries the same id: the drop lines, `op=public-inbound-rejected`, `op=dispatch-rejected` and `op=spawn-failed`. Fewer lines than expected, with none of them a failure, means a step emitted nothing at all — which is what the standing audits below are for.
+
+Do not try to follow an inbound by its sender. `sender=` appears on two of these lines, and the same visitor is a LID on `op=stanza` and an E.164 on `op=routed`, so no sender-based filter spans the merge.
+
+`op=spawn-failed` there is the WhatsApp side reporting a 500. What the spawn itself did is in the manager's own lines, correlated by `pid`:
 
 ```
-[whatsapp:wire]         op=stanza
-[wa-notify]             op=eligible        reason=<how the sender was admitted>
-[whatsapp:route]        op=routed          agentType=public
-[whatsapp:notify]       op=public-inbound  enabled=0|1 outcome=sent|failed|no-recipients|disabled
-[whatsapp:relay]        op=dispatch        outcome=sent|failed|no-recipients
-[whatsapp:public-agent] op=route           enabled=… slug=… spawned=0|1
-[whatsapp:public-agent] op=spawn-ok | op=spawn-failed
+op=startup-watch                  state=armed
+op=public-dev-channel-confirmed   channel=<kind> bufferCleared=<bool> bytesDropped=<n>
+op=startup-watch                  state=reset
+op=startup-watch                  state=disposed
 ```
 
-Three standing audits reconcile that chain rather than waiting for someone to notice. `op=public-notify-reconcile` reports `gap`, `relayGap` and `englishGap`, each of which counts a step that a routed inbound reached and the next one did not. `op=spawn-census` reports attempts against successes. A non-zero gap, or attempts with no successes, is a fault even when nothing has been reported.
+The first-run dialog is answered for the session, and the watcher that guards against an *unanswered* one drops what it saw before that answer. `bufferCleared=false` means the confirm fired and the drop did not, which is the shape that killed a resumed spawn on 2026-08-01: the answered dialog's own footer stayed in the buffer, the replayed transcript slid past it, and the spawn was blocked by a line the agent itself had written the day before.
+
+Three standing audits reconcile that chain rather than waiting for someone to notice. `op=public-notify-reconcile` reports `gap`, `relayGap` and `answerGap`, each of which counts a step that a routed inbound reached and the next one did not. `op=spawn-census` reports attempts against successes. A non-zero gap, or attempts with no successes, is a fault even when nothing has been reported.
 
 ---
 # Settings
@@ -3426,6 +3447,8 @@ either is a regression.
 
 **`/chat` empty-state starter chips.** While the admin webchat has no conversation JSONL yet (`GET /api/webchat/session` → `projectDir:null`), `app/chat/page.tsx` renders a "What's up next, {givenName}?" greeting (given name = first whitespace token of the admin session's `userName`; degrades to "What's up next?" without one) above three one-tap starter chips (replacing the earlier read-only lists): **Catch me up** (`Inbox`), **My day** (`CalendarClock`), **To-do** (`ListTodo`). `GreetingPanel` no longer fetches `GET /api/webchat/greeting` — the headline reads from the `userName` prop alone. A tap dispatches the chip's verbatim prompt through the existing `send()` with zero typing, via the same arm/fire path as the `?q=` handoff seed: `dispatchChip` logs `[admin-ui] op=chip-tap id=<catch-up|my-day|to-do> chars=<n>`, sets the composer text, and arms a one-shot effect that fires `send()` once the text matches. Chips gate to `variant` admin/operator; the public surface shows the headline alone. The first journaled turn replaces the panel with the transcript. The `/api/webchat/greeting` route (`server/routes/webchat-greeting.ts`) and `specialist-roster.ts` are now unconsumed by this surface — slimming them is a separate follow-up. The full webchat architecture lives in `.docs/admin-webchat-native-channel.md`.
 
+**`/chat` reply to a specific message.** Each of your own messages and each of the assistant's replies carries a reply control beside its copy button. Clicking it puts a strip above the composer naming who you are replying to and quoting the message; the X on that strip cancels. Sending delivers the quote to the agent as the first line of its context, so "redo that one" resolves to the message you pointed at, and the sent message keeps the quote visible above it when you reload. Two limits are deliberate: a message that arrived while the assistant was mid-turn cannot be quoted (the transcript records that arrival without an id to target), and tool runs, thinking runs and error banners are not reply targets. The quoted text is capped at 500 characters and is read from the conversation's own transcript server-side, never from the browser. The public visitor surface has no reply control. The full path is in `.docs/admin-webchat-native-channel.md`.
+
 **`/chat` composer transport button.** The button at the end of the input shows a **microphone** while the box is empty — tap it to record a voice note. Type a character, or attach a file, and the same button becomes the **send** arrow; while the agent is replying it becomes a **stop** square. So an empty composer offers voice, a composer with something to send offers send, and a running turn offers stop — one button, three states. The microphone-device chooser (which input to record from) stays in the row of icons below the box. This is the same on the admin `/chat`, the public chat, and the maxy-lite webchat.
 
 **`/chat` Conversations flyout + zero-sessions splash.** The admin `/chat` `HeaderMenu` carries a **Conversations** item (rendered only when `onOpenConversations` is wired, which scopes it to `/chat`) that opens an in-chat session-management pane (`app/chat/SessionList.tsx`) hosted by `chat/page.tsx` — distinct from, and sharing endpoints with, the `Sidebar` Sessions list (which stays hidden on narrow viewports). It enumerates the admin's own webchat sessions via `GET /api/admin/sidebar-sessions` (carries the per-row `live` marker and `archived` flag, install-wide), **filtering out `channel:'whatsapp'`/`'telegram'` rows** (those are channel-bound, cannot be chatted in webchat, and live in the WhatsApp/Telegram reader panels; the same endpoint now also feeds the sidebar Sessions list, which does show them), lists the remainder newest-first with the live one marked and archived rows folded under a collapsible subsection, and offers per-row resume (`/chat?session=<id>`), rename, archive/unarchive, two-tap delete, an **End** control on the live row (`session-stop`), plus a New-session control (`session-rc-spawn`) and a copyable full id. The pane header carries the title and a top-right close (X) control that dismisses the flyout (no back-chevron/"Chat" label); the New-session control floats at the pane's bottom-left. When the canonical pointer is `known:false` (`canonical-empty`) and enumeration returns zero rows, the surface renders a splash (brand logo + New session) instead of a dead bootstrap thread; a freshly-spawned New session is `known:true`, so its greeting is preserved. Client breadcrumbs: `[chat-conversations] op=enumerate owned=<n>` and `op=action name=<open|rename|archive|delete|stop> sessionId=<id8>` (`op=action-failed … status=…` on a non-2xx). Detail lives in `.docs/admin-webchat-native-channel.md` ("Conversations flyout + zero-sessions splash").
@@ -3917,6 +3940,40 @@ explicit `?plugin=` parameter, not inferred from `--` in the slug.
 | `DELETE /api/admin/agents/:slug?accountId=` | Public agents only, on the named validated account. Removes the dir after `deleteAgentProjection`; refuses the `admin` slug (403) and a missing/unknown `accountId` (400) with no write. Loud-fail: a graph-cleanup throw aborts the file removal. |
 | `POST /api/admin/agents/:slug/project?accountId=` | Re-projects the named account's on-disk agent into the graph. Same `accountId` contract as delete. |
 
+### Agent write tools (admin MCP)
+
+Public-agent CRUD is tool-only. There is no create or update HTTP route: the three
+admin MCP tools own the write path, and raw file writes reach none of their checks.
+That is what left the `beagle` agent on disk and absent from the graph for a day.
+
+| Tool | Refuses | On success |
+|---|---|---|
+| `agent-create` | `slug-unsafe` (shape, reserved or route-shadowed, by the same rule the router serves by), `exists` (the directory is occupied), `knowledge-empty`, `config-invalid` (naming the field), `not-found` (the platform IDENTITY template is missing). Every check runs before the first write, so a refusal leaves no directory. | Writes `IDENTITY.md` (copied verbatim from `templates/agents/public/`), `SOUL.md`, `KNOWLEDGE.md` and `config.json`, then projects. Returns an error when the write landed but the projection did not. |
+| `agent-update` | `slug-unsafe`, `not-found`, `knowledge-empty` when `knowledge` is supplied, `config-invalid` on the merged config. A refusal leaves the directory byte-identical. | Writes only the fields supplied, merges config fields into the existing file, then re-projects. Called with the slug alone it re-projects and nothing else. |
+| `agent-delete` | The `admin` slug, at the tool boundary as well as at the route. | Calls `DELETE /api/admin/agents/:slug`, which removes the graph projection before the directory and preserves the files if the graph write throws. |
+
+The config schema (`plugins/admin/mcp/src/tools/agent-config-schema.ts`) requires a
+non-blank `displayName`, a `model` passing `isSelectableModel`, and a `status` of
+`active` or `inactive`; it constrains `imageShape`, `accessMode` and
+`knowledgeKeywords` when present, and passes unknown keys so a field written by an
+unreleased feature is not blocked. `KNOWLEDGE-SUMMARY.md` is the one agent file no
+write tool owns; write it directly and the next `agent-update` projects it.
+
+Every call emits one line:
+
+    [admin/agents] op=agent-write action=<create|update|delete> slug=<slug> accountId=<8>
+      outcome=<ok|refused> reason=<slug-unsafe|config-invalid|knowledge-empty|exists|not-found|projection-failed|delete-failed|write-failed|none>
+      detail=<shape|reserved|shadowed|field|error text|-> projected=<n>
+
+`projected` is read from the projection response, never assumed. The
+disk-without-graph signature is `action=create|update outcome=ok projected=0` —
+the action matters, because a successful delete also logs `projected=0`, having
+removed the projection on purpose.
+
+`reason=write-failed` covers an unresolvable account directory or an I/O error.
+It exists because `getAccountDir` throws and the lifeline wrapper re-throws, so
+without a catch in the handler those failures would emit no line at all.
+
 Observability rides `[admin/agents]`, and **every line names the account it acted
 on** (`accountId=<id8>`) — a well-formed answer about the wrong account is
 otherwise indistinguishable from a correct one, which is exactly how an empty
@@ -3937,6 +3994,19 @@ Agents page survived undiagnosed on a multi-account install.
 - `op=<delete|project> rejected reason=<missing-accountId|unknown-accountId>` —
   a caller that did not name its account. A skill that was not updated produces
   this on its first call instead of writing to the wrong account.
+- `op=project rejected reason=agent-not-on-disk accountId=<id8> slug=<…>
+  probed=<agentDir>` — the projection 404. `probed` names the directory that
+  actually resolved, so a "the route says not found, the files are plainly
+  there" report is refutable without reproducing the call; before it existed the
+  route returned that 404 silently and such a report could be neither confirmed
+  nor refuted. Its two siblings are `op=project ok accountId=<id8> slug=<…>
+  nodesWritten=<n>` and `op=project failed accountId=<id8> slug=<…>
+  error="<msg>"` on a projector throw. `nodesWritten` counts nodes MERGEd — the
+  Agent node plus one KnowledgeDocument per present body file — so it stays
+  non-zero on an idempotent re-projection, and **`nodesWritten=0` on an `ok` is
+  the defect signature**: `projectAgent` returns early without throwing on an
+  unsafe slug, a missing `config.json` or a body-file read error, and the route
+  answers `200 {"ok":true}` in all three cases.
 - `op=delete accountId=<id8> slug=<…> outcome=<ok|failed>` with
   `reason=<graph-cleanup-failed|rm-error>` on failure (files preserved on a
   graph-cleanup throw).
@@ -4340,6 +4410,30 @@ The companion `/api/admin/version` and `/api/admin/actions` routes are
 served by `maxy-edge.service`, not this aggregator. The edge process
 keeps the upgrade view alive while the brand service restarts.
 
+### Phone-width layout overflow
+
+If any part of an admin screen is cut off at the right edge on a phone —
+a header pill, a message bubble — the dashboard now reports it by itself
+rather than waiting for a screenshot. Every admin page measures its own
+width after it settles, and posts a record when something sticks out past
+the edge.
+
+Read the reports with:
+
+```
+grep 'op=layout-overflow' ~/.<brand>/logs/client-errors.log
+```
+
+Each line names the page it happened on (`route`) and the element that
+stuck out (`offender`), so the cause is identifiable without reproducing
+it on a handset. A line with a `delta` but an empty `offender` means the
+measurement ran too early, which is a different fault from a cut-off
+page. No lines at all is the healthy state.
+
+These reports share the client-error log, so they also count towards the
+24-hour client-error figure shown on the upgrade view. A rise there with
+`op=layout-overflow` lines behind it is a layout problem, not a crash.
+
 ## System-stats widget
 
 Source:
@@ -5399,7 +5493,7 @@ A `Service` node matched by vector search will have its `PriceSpecification`, `R
 
 ## Keyword Subscriptions — Reactive Per-Agent Knowledge
 
-Each public agent can subscribe to up to 5 keywords via `knowledgeKeywords` in its `config.json`. These subscriptions make the agent reactive to new graph content matching its topics — content added after the agent was created becomes discoverable without manual tag updates.
+Each public agent can subscribe to up to 5 keywords via `knowledgeKeywords` in its `config.json`. Subscriptions default to empty and are opt-in: the operator asks for them or the agent has none. A subscription makes new graph content matching its topics **discoverable at the next refresh** — it surfaces candidate lines for the operator to approve, and never adds anything to a public agent's knowledge on its own. Whatever a public agent can say is a line the operator approved for a stranger to read.
 
 ### Dual search per keyword
 
@@ -5417,7 +5511,7 @@ Results from keyword subscription searches are merged into the same scored map a
 
 ### Lifecycle
 
-Keywords are consumed by the `update-knowledge` admin skill when regenerating KNOWLEDGE.md — the regeneration query broadens the operator-tagged set with keyword matches so newly-added graph content that shares a subscribed topic lands in the next baked snapshot. There is no runtime keyword-injection path on the public PTY surface.
+Keywords are consumed by the `update-knowledge` admin skill when regenerating KNOWLEDGE.md — the regeneration query broadens the operator-tagged set with keyword matches, so newly-added graph content sharing a subscribed topic is *proposed* for the next baked snapshot. It is proposed, not baked: the skill presents the gathered lines and writes only the ones the operator approves. There is no runtime keyword-injection path on the public PTY surface.
 
 ---