@rubytech/create-maxy-code 0.1.539 → 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:e737732428725be0a3852ca8ba4cd1f9dd5f62bdcd6f7c0a85b82f4ac1c9bccc
+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,18 +1730,36 @@ 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
-[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
+[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`:
+
+```
+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
+```
+
+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.
 
 ---
@@ -3919,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
@@ -3939,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).
@@ -5425,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
 
@@ -5443,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.
 
 ---