@rubytech/create-sitedesk-code 0.1.518 → 0.1.520

package/dist/__tests__/edge-bind-template-wiring.test.js

@@ -0,0 +1,37 @@
+// Nothing else in the repo ties the edge unit template's placeholders to the
+// substitutions in index.ts, so either half can be edited alone and the whole
+// suite stays green. Two silent failures this closes:
+//
+//   - substitution added, template left at a literal value → the replace is a
+//     no-op, the unit still binds 0.0.0.0, and the Task 2082 security fix ships
+//     inert with every pickEdgeBindDecision test passing;
+//   - template placeholder added, substitution forgotten → the unit ships a
+//     literal `Environment=EDGE_HOSTNAME=__EDGE_HOSTNAME__`, which edge.ts's
+//     `process.env.EDGE_HOSTNAME ?? '0.0.0.0'` does NOT catch, because the
+//     variable is present, just not an address, so server.listen() gets a
+//     non-address and the edge restart-loops.
+//
+// Both files are read from disk at runtime, the same pattern as
+// macos-darwin-branch.test.ts and base-toolchain-deps.test.ts.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+// dist/__tests__/edge-bind-template-wiring.test.js → ../../src/index.ts
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = resolve(here, "../../src/index.ts");
+// dist/__tests__ → up four is the maxy-code root that holds platform/.
+const EDGE_TEMPLATE = resolve(here, "../../../../platform/templates/systemd/edge.service.template");
+const SRC = readFileSync(INDEX_TS, "utf-8");
+const TEMPLATE = readFileSync(EDGE_TEMPLATE, "utf-8");
+test("edge template: EDGE_HOSTNAME is a placeholder, not a hardcoded address", () => {
+    assert.match(TEMPLATE, /^Environment=EDGE_HOSTNAME=__EDGE_HOSTNAME__$/m, "edge.service.template must take EDGE_HOSTNAME from the installer's bind decision (Task 2082), not hardcode it");
+});
+test("edge template: every placeholder has a matching substitution in index.ts", () => {
+    const placeholders = [...new Set(TEMPLATE.match(/__[A-Z0-9_]+__/g) ?? [])].sort();
+    assert.ok(placeholders.includes("__EDGE_HOSTNAME__"), "template must carry __EDGE_HOSTNAME__");
+    for (const p of placeholders) {
+        assert.ok(SRC.includes(`.replace(/${p}/g,`), `${p} appears in edge.service.template but index.ts has no .replace(/${p}/g, ...) — the rendered unit would ship the literal placeholder`);
+    }
+});

package/dist/__tests__/samba-provision.test.js

@@ -6,7 +6,7 @@
 // style and runs under `node --test dist/__tests__/*.test.js` after build.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { renderBrandStanza, renderGlobalSection, renderFullSmbConf, isPrivateIPv4, pickBindDecision, mergeSmbConf, removeBrandStanza, hasAnyBrandStanza, formatSambaMarker, SAMBA_STEPS, SAMBA_ENABLE_UNITS, } from "../samba-provision.js";
+import { renderBrandStanza, renderGlobalSection, renderFullSmbConf, isPrivateIPv4, pickBindDecision, pickEdgeBindDecision, formatEdgeBindDecision, mergeSmbConf, removeBrandStanza, hasAnyBrandStanza, formatSambaMarker, SAMBA_STEPS, SAMBA_ENABLE_UNITS, } from "../samba-provision.js";
 // ---------------------------------------------------------------------------
 // Fixtures
 // ---------------------------------------------------------------------------
@@ -49,6 +49,42 @@ const MIXED_PUBLIC_AND_PRIVATE = {
     eth0: [{ address: "178.105.251.82", netmask: "255.255.255.255", family: "IPv4", mac: "96:00:00:00:00:02", internal: false, cidr: "178.105.251.82/32" }],
     wg0: [{ address: "10.8.0.3", netmask: "255.255.255.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: false, cidr: "10.8.0.3/24" }],
 };
+// Hetzner Cloud shape: public eth0 plus a provider private network on ens10.
+// pickBindDecision calls this `lan`; the edge must still bind loopback.
+const HETZNER_CLOUD_PUBLIC_PLUS_PRIVNET = {
+    lo: [{ address: "127.0.0.1", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: true, cidr: "127.0.0.1/8" }],
+    eth0: [{ address: "167.233.21.246", netmask: "255.255.255.255", family: "IPv4", mac: "96:00:00:00:00:03", internal: false, cidr: "167.233.21.246/32" }],
+    ens10: [{ address: "10.0.0.2", netmask: "255.255.0.0", family: "IPv4", mac: "96:00:00:00:00:04", internal: false, cidr: "10.0.0.2/16" }],
+};
+// Private wlan0 plus a public address elsewhere. Reaches pickBindDecision's
+// wlan0 early return, which MIXED_PUBLIC_AND_PRIVATE never does because its
+// private address is on wg0.
+const PRIVATE_WLAN0_PLUS_PUBLIC = {
+    lo: [{ address: "127.0.0.1", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: true, cidr: "127.0.0.1/8" }],
+    wlan0: [{ address: "192.168.1.50", netmask: "255.255.255.0", family: "IPv4", mac: "aa:bb:cc:dd:ee:ff", internal: false, cidr: "192.168.1.50/24" }],
+    eth0: [{ address: "203.0.113.7", netmask: "255.255.255.255", family: "IPv4", mac: "96:00:00:00:00:05", internal: false, cidr: "203.0.113.7/32" }],
+};
+// Private eth0 plus a public address elsewhere. Reaches the eth0 early return.
+const PRIVATE_ETH0_PLUS_PUBLIC = {
+    lo: [{ address: "127.0.0.1", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: true, cidr: "127.0.0.1/8" }],
+    eth0: [{ address: "10.0.0.5", netmask: "255.255.255.0", family: "IPv4", mac: "11:11:11:11:11:11", internal: false, cidr: "10.0.0.5/24" }],
+    ens5: [{ address: "198.51.100.9", netmask: "255.255.255.255", family: "IPv4", mac: "96:00:00:00:00:06", internal: false, cidr: "198.51.100.9/32" }],
+};
+// One interface carrying both a public and a private IPv4. No other fixture in
+// this file has a multi-address interface.
+const ONE_IFACE_PUBLIC_AND_PRIVATE = {
+    lo: [{ address: "127.0.0.1", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: true, cidr: "127.0.0.1/8" }],
+    eth0: [
+        { address: "192.0.2.44", netmask: "255.255.255.255", family: "IPv4", mac: "96:00:00:00:00:07", internal: false, cidr: "192.0.2.44/32" },
+        { address: "172.16.4.9", netmask: "255.255.0.0", family: "IPv4", mac: "96:00:00:00:00:07", internal: false, cidr: "172.16.4.9/16" },
+    ],
+};
+// CGNAT-only host. isPrivateIPv4 counts 100.64/10 as private, so this binds
+// 0.0.0.0. Pinned so the outcome is declared rather than incidental.
+const CGNAT_ONLY = {
+    lo: [{ address: "127.0.0.1", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: true, cidr: "127.0.0.1/8" }],
+    eth0: [{ address: "100.100.3.14", netmask: "255.192.0.0", family: "IPv4", mac: "96:00:00:00:00:08", internal: false, cidr: "100.100.3.14/10" }],
+};
 // ---------------------------------------------------------------------------
 // isPrivateIPv4 — RFC1918 / CGNAT / link-local classification
 // ---------------------------------------------------------------------------
@@ -107,6 +143,72 @@ test("pickBindDecision: none when the only non-loopback iface has no IPv4", () =
     assert.deepEqual(pickBindDecision(PI_IPV6_ONLY_LAN), { kind: "none" });
 });
 // ---------------------------------------------------------------------------
+// pickEdgeBindDecision — 0.0.0.0 only when private exists and public does not
+// ---------------------------------------------------------------------------
+test("pickEdgeBindDecision: private-only hosts keep the public bind", () => {
+    for (const [name, ifaces] of [
+        ["PI_WLAN0_ONLY", PI_WLAN0_ONLY],
+        ["PI_BOTH_IFACES", PI_BOTH_IFACES],
+        ["PI_ETH0_ONLY", PI_ETH0_ONLY],
+        ["PI_USB0_FALLBACK", PI_USB0_FALLBACK],
+        ["CGNAT_ONLY", CGNAT_ONLY],
+    ]) {
+        assert.equal(pickEdgeBindDecision(ifaces).hostname, "0.0.0.0", name);
+    }
+});
+// The fail-open this task exists to close: pickBindDecision calls every one of
+// these `lan`, so keeping its verdict verbatim would leave the edge public on a
+// cloud box that happens to carry a provider private network.
+test("pickEdgeBindDecision: a public IPv4 forces loopback even when a private one exists", () => {
+    for (const [name, ifaces] of [
+        ["MIXED_PUBLIC_AND_PRIVATE", MIXED_PUBLIC_AND_PRIVATE],
+        ["HETZNER_CLOUD_PUBLIC_PLUS_PRIVNET", HETZNER_CLOUD_PUBLIC_PLUS_PRIVNET],
+        ["PRIVATE_WLAN0_PLUS_PUBLIC", PRIVATE_WLAN0_PLUS_PUBLIC],
+        ["PRIVATE_ETH0_PLUS_PUBLIC", PRIVATE_ETH0_PLUS_PUBLIC],
+        ["ONE_IFACE_PUBLIC_AND_PRIVATE", ONE_IFACE_PUBLIC_AND_PRIVATE],
+    ]) {
+        const d = pickEdgeBindDecision(ifaces);
+        assert.equal(d.hostname, "127.0.0.1", name);
+        assert.equal(d.kind, "lan", `${name} still classifies as lan for smbd`);
+    }
+});
+test("pickEdgeBindDecision: public-only host binds loopback", () => {
+    const d = pickEdgeBindDecision(HETZNER_PUBLIC_ETH0_ONLY);
+    assert.equal(d.hostname, "127.0.0.1");
+    assert.equal(d.kind, "loopback-only");
+});
+// Unlike the Samba call site, which throws on `none`, the edge binds loopback
+// and lets the install finish: a loopback edge still serves the tunnel.
+test("pickEdgeBindDecision: no non-loopback IPv4 binds loopback rather than throwing", () => {
+    for (const ifaces of [PI_LO_ONLY, PI_IPV6_ONLY_LAN]) {
+        const d = pickEdgeBindDecision(ifaces);
+        assert.equal(d.hostname, "127.0.0.1");
+        assert.equal(d.kind, "none");
+        assert.deepEqual(d.privateAddresses, []);
+        assert.deepEqual(d.publicAddresses, []);
+    }
+});
+test("pickEdgeBindDecision: reports the interface and addresses it decided from", () => {
+    assert.deepEqual(pickEdgeBindDecision(MIXED_PUBLIC_AND_PRIVATE), {
+        hostname: "127.0.0.1",
+        kind: "lan",
+        iface: "wg0",
+        publicAddresses: ["178.105.251.82"],
+        privateAddresses: ["10.8.0.3"],
+    });
+    assert.deepEqual(pickEdgeBindDecision(PI_WLAN0_ONLY), {
+        hostname: "0.0.0.0",
+        kind: "lan",
+        iface: "wlan0",
+        publicAddresses: [],
+        privateAddresses: ["192.168.1.50"],
+    });
+});
+test("formatEdgeBindDecision: carries both grep tokens and never leaves an empty field", () => {
+    assert.equal(formatEdgeBindDecision(pickEdgeBindDecision(PI_WLAN0_ONLY)), "[edge-bind-decision] kind=lan iface=wlan0 private=192.168.1.50 public=none EDGE_HOSTNAME=0.0.0.0");
+    assert.equal(formatEdgeBindDecision(pickEdgeBindDecision(HETZNER_PUBLIC_ETH0_ONLY)), "[edge-bind-decision] kind=loopback-only iface=none private=none public=167.233.21.246 EDGE_HOSTNAME=127.0.0.1");
+});
+// ---------------------------------------------------------------------------
 // renderBrandStanza — exact spec match
 // ---------------------------------------------------------------------------
 test("renderBrandStanza emits the spec directives in order", () => {

package/dist/index.js

@@ -29,7 +29,7 @@ import { classifyPortHolder } from "./preflight-port-classifier.js";
 import { memoryControllerMissing, cmdlineAlreadyPatched, patchCmdline } from "./cgroup-memory-controller.js";
 import { parsePluginList, computeInstallActions, parseExternalPlugins, findUnregisteredResyncs, discoverMarketplaceCandidateDirs, } from "./lib/plugin-install.js";
 import { findPremiumMcpDirs } from "./lib/premium-mcp-discover.js";
-import { pickBindDecision, mergeSmbConf, formatSambaMarker, SAMBA_ENABLE_UNITS, } from "./samba-provision.js";
+import { pickBindDecision, pickEdgeBindDecision, formatEdgeBindDecision, mergeSmbConf, formatSambaMarker, SAMBA_ENABLE_UNITS, } from "./samba-provision.js";
 import { networkInterfaces, userInfo, cpus } from "node:os";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
@@ -4493,11 +4493,20 @@ WantedBy=default.target
     // VNC_DISPLAY (defined above for the main brand unit) is also stamped into
     // the edge unit so both services agree on the X display. Per-brand display
     // closes the cross-brand cookie leak documented.
+    // Task 2082 — the edge binds 0.0.0.0 only on a host with a private IPv4 and
+    // no public one; anything else binds loopback so a rented server never puts
+    // the admin edge on the internet. Logged with its inputs because a wrong
+    // classification is otherwise invisible until an external probe finds it.
+    // Linux-only by construction: this function returns at the darwin branch
+    // above, and darwin runs no edge process at all.
+    const edgeBind = pickEdgeBindDecision(networkInterfaces());
+    logFile(`  ${formatEdgeBindDecision(edgeBind)}`);
     const edgeTemplatePath = resolve(INSTALL_DIR, "platform/templates/systemd/edge.service.template");
     if (existsSync(edgeTemplatePath)) {
         const edgeServiceContent = readFileSync(edgeTemplatePath, "utf-8")
             .replace(/__INSTALL_DIR__/g, INSTALL_DIR)
             .replace(/__EDGE_PORT__/g, String(PORT))
+            .replace(/__EDGE_HOSTNAME__/g, edgeBind.hostname)
             .replace(/__MAXY_UI_PORT__/g, String(MAXY_UI_INTERNAL_PORT))
             .replace(/__PERSIST_DIR__/g, persistDir)
             .replace(/__VNC_DISPLAY__/g, String(VNC_DISPLAY))
@@ -4505,7 +4514,7 @@ WantedBy=default.target
             .replace(/__CDP_PORT__/g, String(CDP_PORT_BRAND))
             .replace(/__RFB_PORT__/g, String(RFB_PORT));
         writeFileSync(join(serviceDir, edgeUnitName), edgeServiceContent);
-        logFile(`  ${edgeUnitName}: EDGE_PORT=${PORT} MAXY_UI_PORT=${MAXY_UI_INTERNAL_PORT} VNC_DISPLAY=:${VNC_DISPLAY} RFB_PORT=${RFB_PORT} WEBSOCKIFY_PORT=${WEBSOCKIFY_PORT_BRAND} CDP_PORT=${CDP_PORT_BRAND}`);
+        logFile(`  ${edgeUnitName}: EDGE_PORT=${PORT} EDGE_HOSTNAME=${edgeBind.hostname} MAXY_UI_PORT=${MAXY_UI_INTERNAL_PORT} VNC_DISPLAY=:${VNC_DISPLAY} RFB_PORT=${RFB_PORT} WEBSOCKIFY_PORT=${WEBSOCKIFY_PORT_BRAND} CDP_PORT=${CDP_PORT_BRAND}`);
     }
     else {
         console.error(`  WARNING: edge.service.template missing at ${edgeTemplatePath} — VNC transport unavailable`);
@@ -5389,8 +5398,14 @@ try {
     console.log("================================================================");
     console.log("");
     if (isLinux()) {
-        console.log(`  Same network (Pi / LAN):  http://${DEVICE_HOSTNAME}.local:${PORT}`);
-        console.log("");
+        // Only true when the edge binds 0.0.0.0. On a host classified to loopback
+        // (Task 2082) nothing answers on the LAN address, so printing this line
+        // there would be a false instruction; the SSH-forward recipe below is the
+        // whole story for that host class.
+        if (pickEdgeBindDecision(networkInterfaces()).hostname === "0.0.0.0") {
+            console.log(`  Same network (Pi / LAN):  http://${DEVICE_HOSTNAME}.local:${PORT}`);
+            console.log("");
+        }
         console.log(`  Remote access (Hetzner / cloud) — on your local machine run:`);
         console.log(`    ssh -L ${PORT}:localhost:${PORT} -L ${BRAND.websockifyPort}:localhost:${BRAND.websockifyPort} admin@<server-ipv4>`);
         console.log(`  Then open:`);

package/dist/samba-provision.js

@@ -14,6 +14,11 @@
 //      stanza intact (peer-brand isolation is the structural invariant).
 //   5. Report whether any brand stanza remains so the uninstall step can
 //      decide whether to apt-purge samba.
+//
+// Despite the file name, the interface classification here serves two
+// consumers, not one: `isPrivateIPv4` and `pickBindDecision` answer where smbd
+// binds, and `pickEdgeBindDecision` (Task 2082) answers where the edge binds.
+// The two deliberately disagree on a dual-homed host; see that function.
 // ---------------------------------------------------------------------------
 // Brand-scoped Samba stanza
 // ---------------------------------------------------------------------------
@@ -152,6 +157,73 @@ export function pickBindDecision(ifaces) {
     const hasNonLoopbackIPv4 = Object.keys(ifaces).some((name) => name !== "lo" && ipv4Addrs(name).length > 0);
     return hasNonLoopbackIPv4 ? { kind: "loopback-only" } : { kind: "none" };
 }
+/**
+ * Decide how the edge should bind, from the same interface table
+ * `pickBindDecision` reads. The edge binds `0.0.0.0` only when the host has at
+ * least one private IPv4 AND zero public IPv4; every other shape binds
+ * `127.0.0.1`. Task 2082.
+ *
+ * Three properties are deliberate, not oversights:
+ *
+ *   1. This DISAGREES with `pickBindDecision` on a dual-homed host. For SMB, a
+ *      private interface alongside a public one keeps the LAN bind (operator
+ *      confirmation, Task 755 — see the MIXED_PUBLIC_AND_PRIVATE fixture). For
+ *      the edge the operator decided the opposite: a cloud server carrying a
+ *      provider private network (Hetzner Cloud's public `eth0` plus private
+ *      `ens10`) must not silently keep a public bind. Both functions are right
+ *      for their own consumer; this is not a rename of the other.
+ *   2. IPv6 is ignored. `pickBindDecision` already filters to IPv4, and
+ *      `0.0.0.0` binds IPv4 only, so a public IPv6 address cannot be exposed by
+ *      this bind under either outcome.
+ *   3. A cloud host presenting its public address by 1:1 NAT is NOT covered.
+ *      Its guest NIC carries only a private address, so this reads a
+ *      private-only host and binds `0.0.0.0` while the box is publicly
+ *      reachable. The scoped signal is a public IPv4 alongside the private one;
+ *      no host in `.docs/install/` behaves that way, and catching it would need
+ *      an outbound probe rather than the interface table.
+ *
+ * `kind: "none"` binds `127.0.0.1` rather than throwing, unlike the Samba call
+ * site, which hard-fails: a share bound to nothing is useless, whereas a
+ * loopback edge still serves the Cloudflare tunnel, which dials
+ * `http://localhost:<port>`. Cost: a host that gains an interface later stays
+ * loopback-only until the installer is re-run, which the decision line makes
+ * visible in the install log.
+ */
+export function pickEdgeBindDecision(ifaces) {
+    const bind = pickBindDecision(ifaces);
+    const publicAddresses = [];
+    const privateAddresses = [];
+    for (const [name, addrs] of Object.entries(ifaces)) {
+        if (name === "lo" || !addrs)
+            continue;
+        for (const a of addrs) {
+            if (a.family !== "IPv4" || a.internal)
+                continue;
+            if (isPrivateIPv4(a.address))
+                privateAddresses.push(a.address);
+            else
+                publicAddresses.push(a.address);
+        }
+    }
+    return {
+        hostname: privateAddresses.length > 0 && publicAddresses.length === 0 ? "0.0.0.0" : "127.0.0.1",
+        kind: bind.kind,
+        iface: bind.kind === "lan" ? bind.lanInterface : null,
+        publicAddresses,
+        privateAddresses,
+    };
+}
+/**
+ * The install-log line for an edge bind decision. The shape is load-bearing:
+ * the task's diagnostic path greps `bind-decision` and `EDGE_HOSTNAME`, so both
+ * tokens must survive any edit. Empty lists render as the literal `none` so a
+ * host with no addresses is distinguishable from a truncated line.
+ */
+export function formatEdgeBindDecision(d) {
+    const list = (xs) => (xs.length === 0 ? "none" : xs.join(","));
+    return `[edge-bind-decision] kind=${d.kind} iface=${d.iface ?? "none"} ` +
+        `private=${list(d.privateAddresses)} public=${list(d.publicAddresses)} EDGE_HOSTNAME=${d.hostname}`;
+}
 // ---------------------------------------------------------------------------
 // smb.conf merge / remove
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-sitedesk-code",
-  "version": "0.1.518",
+  "version": "0.1.520",
   "description": "Install SiteDesk — automated back office for independent building contractors",
   "bin": {
     "create-sitedesk-code": "./dist/index.js"

package/payload/platform/docs/superpowers/plans/2026-07-28-task-2097-email-signature-set.md

@@ -0,0 +1,65 @@
+# Task 2097 — `email-signature-set` implementation plan
+
+Design: [`2026-07-28-task-2097-email-signature-set-design.md`](../specs/2026-07-28-task-2097-email-signature-set-design.md).
+
+## Registration surfaces — corrected against the tree
+
+The task file names `ADMIN_CORE_TOOLS`. It does not exist: `grep -rn 'ADMIN_CORE_TOOLS' platform/` returns
+nothing outside comments. The live surfaces, each confirmed by reading the file, are four:
+
+| # | Surface | Evidence |
+|---|---|---|
+| 1 | `plugins/email/mcp/src/index.ts` | `eagerTool(server, "email-setup", …)` at line 124 |
+| 2 | `plugins/email/PLUGIN.md` | frontmatter `description:`, `tools:` list, Capabilities, Skills table |
+| 3 | `platform/templates/specialists/agents/personal-assistant.md` | the only template matching `grep -rl email-setup platform/templates/` |
+| 4 | `services/claude-session-manager/src/canonical-tool-names.generated.ts` | header: generated from `PLUGIN.md` `tools:` blocks, `check-canonical-tool-names.mjs` fails the build on drift |
+
+Surface 4 is not in the task file and would have broken the build. It is regenerated, never hand-edited:
+`cd platform && npm run gen:canonical-tools`.
+
+Three further files match `email-draft-send` and are deliberately **not** touched:
+`plugins/admin/hooks/preference-consult-gate.sh`, `scripts/lib/provision-account-dir.sh`, and the
+`plugins/admin/PLUGIN.md` prose describing them. All three are the outbound-send preference gate,
+matching sends that carry attachments. `email-signature-set` sends nothing, so it is not a gate member.
+
+## Steps
+
+1. **`lib/signature.ts`** — add `SIGNATURE_BASENAME`, `signatureDirFor(accountId)`, and
+   `saveSignature(accountDir, parts)`. `loadSignature` / `applySignature` unchanged.
+   `signatureDirFor` is `accountDirFor(accountId) || process.env.ACCOUNT_DIR || undefined`, which is the
+   expression `compose.ts:112` already computes, with an empty-string env normalised to `undefined`
+   (both already load as no-signature, so behaviour is unchanged). No import cycle: `attachment-resolve.ts`
+   imports only `node:fs` and `node:path`.
+2. **`lib/compose.ts`** — replace the inline `sigDir` expression with `signatureDirFor(accountId)` and the
+   literal `"email-signature"` in `assetNote` with `SIGNATURE_BASENAME`. `accountDirFor` stays imported for
+   the attachment path at line 75.
+3. **`tools/email-signature-set.ts`** — refuse an all-absent call and an unresolvable directory before any
+   write, call `saveSignature`, log, return the resolved paths.
+4. **`index.ts`** — import and `eagerTool` register, placed after the `email-setup` block. Guard with
+   `refuseNoAccount`, wrap in try/catch like `email-setup`. The handler's local result variable is named
+   `message`, not `text`, so it cannot shadow the `text` parameter.
+5. **`PLUGIN.md`** — `tools:` entry (`riskClass: write_local`, both allowlists false, matching `email-setup`),
+   a Config clause in the frontmatter `description:`, a Capabilities bullet, a Skills-table row.
+6. **`personal-assistant.md`** — add `mcp__plugin_email_email__email-signature-set` after `email-setup`.
+7. **Regenerate** `canonical-tool-names.generated.ts`.
+8. **`skills/email-signature/SKILL.md`** — new skill.
+9. **`skills/email-composition/SKILL.md`** — one added rule, see below.
+10. **`__tests__/email-signature-set.test.ts`** — committed, not ephemeral: the plugin already carries 34
+    test files and the task file mandates a regression test.
+
+## Addition beyond the task file
+
+The task specifies that the new `email-signature` skill carries the rule "never hand-build a signature
+inside a draft body". That skill activates when the operator asks to set or change a signature. The
+incident happened while **drafting**, when that skill is not loaded. `grep -in signature` over
+`skills/email-composition/SKILL.md` returns zero hits, so the drafting surface currently says nothing
+about signatures.
+
+So the rule is also stated in one sentence in `email-composition`, which is the skill that is loaded while
+drafting. Without it the doctrine lives only in a skill absent at the moment it is needed. Declared in Plan
+Conformity as an addition.
+
+## Verification
+
+`npm run build` and `npx vitest run` in `plugins/email/mcp`, then `npm run gen:canonical-tools` and the
+`check-canonical-tool-names.mjs` gate in `platform/`. No browser surface, no Pi hook surface.

package/payload/platform/docs/superpowers/specs/2026-07-28-task-2097-email-signature-set-design.md

@@ -0,0 +1,155 @@
+# Task 2097 — `email-signature-set` design
+
+Date 2026-07-28. Lane *Platform / email · signature provisioning*.
+Task file: [`.tasks/pending/2097-email-signature-setter-so-the-deterministic-loader-can-be-populated.md`](../../../../.tasks/pending/2097-email-signature-setter-so-the-deterministic-loader-can-be-populated.md).
+
+## Problem
+
+`email-draft` appends an account's signature deterministically, with no model judgement, at
+[`compose.ts:113`](../../../plugins/email/mcp/src/lib/compose.ts). It calls `loadSignature(sigDir)` then
+`applySignature`, where `loadSignature` (Task 1952,
+[`signature.ts:24`](../../../plugins/email/mcp/src/lib/signature.ts)) reads three fixed-convention files at the
+account root: `email-signature.txt`, `email-signature.html`, `email-signature.font`.
+
+Nothing in the platform writes those files. Task 1952 shipped the reader with no writer, so the
+path-and-format convention lives only in code and no account can be provisioned. On the G.L. Smith
+account none of the three exist, `applied` was false, no signature was appended, and a drafting
+subagent with no file-read tool reconstructed the HTML from a memory node and pulled a stale logo
+into a client draft.
+
+The failure is not a model ignoring a rule. The deterministic path works; it had no files to read.
+
+## Outcome
+
+An account's signature is installed into the loader's exact path and format through a sanctioned,
+discoverable tool, and every subsequent draft carries it byte-for-byte with no model-authored
+signature markup.
+
+## Architecture
+
+`lib/signature.ts` becomes the single owner of the signature convention in both directions. Read and
+write cannot drift because one file defines the base path, the three extensions, and the font
+trimming for both.
+
+| Unit | Responsibility | Depends on |
+|---|---|---|
+| `lib/signature.ts` → `signatureDirFor(accountId)` | Resolve the one directory an account's signature lives in | `attachment-resolve.ts` → `accountDirFor`, `process.env.ACCOUNT_DIR` |
+| `lib/signature.ts` → `saveSignature(accountDir, parts)` | Write present parts, remove absent ones, report both | `node:fs` |
+| `lib/signature.ts` → `loadSignature` / `applySignature` | Unchanged (Task 1952) | — |
+| `tools/email-signature-set.ts` | Param refusals, call `saveSignature`, log, format the response | `lib/signature.ts` |
+| `lib/compose.ts` | Swaps its inline dir expression for `signatureDirFor` | `lib/signature.ts` |
+
+### Directory resolution
+
+`compose.ts:113` currently resolves the read directory inline as
+`accountDirFor(accountId) || process.env.ACCOUNT_DIR`. The setter must write to the identical
+directory in every environment, so that expression moves into `signatureDirFor(accountId)` and both
+sides call it. Substituting the identical expression leaves `compose.ts` behaviour unchanged; the
+point is that "which directory" now has one definition rather than two copies that can diverge.
+
+Writing to `accountDirFor(accountId)` alone was rejected: on a spawn where `PLATFORM_ROOT` is absent
+but `ACCOUNT_DIR` is set, the setter would refuse while drafts would have read the file fine.
+
+## Behaviour
+
+Parameters, all optional strings: `text`, `html`, `font`. The account is the caller's `accountId`,
+the same authority `email-draft` uses. There is no `mailbox` parameter — a signature is account-scoped,
+because `loadSignature` reads one account root and knows nothing about mailboxes.
+
+| Input | Effect on `email-signature.<ext>` |
+|---|---|
+| `text` present | `.txt` written byte-for-byte verbatim, no reflow, no re-encoding |
+| `html` present | `.html` written byte-for-byte verbatim |
+| `font` present | `.font` written trimmed, matching `loadSignature`'s trim-on-read |
+| any one absent | that file removed if it exists; absence of the file is not an error |
+| all three absent | refused, nothing on disk is touched |
+| directory unresolvable | refused, nothing on disk is touched |
+
+Absent and empty are different inputs. A parameter is absent only when it is not supplied; a supplied
+empty string is present, so it writes an empty file and counts toward the all-three-absent check. That
+follows from writing verbatim: the tool stores what it was given rather than second-guessing it. The
+consequence is that an empty `.txt` makes the next draft report `applied` true while appending
+nothing visible, which is why an empty string is a deliberate act and omission is the way to remove.
+
+The removal rule is what makes a text-only call clear a stale `.html` rather than leave it to keep
+appending. The all-three-absent refusal is what stops a mis-shaped call silently wiping a working
+signature; removal stays reachable, but only as a side effect of setting something.
+
+The response names the resolved paths written and the resolved paths removed, so the caller sees the
+account root it landed in rather than trusting it.
+
+## Failure handling
+
+Files are written in the fixed order `.txt`, `.html`, `.font`. A filesystem error surfaces verbatim
+naming the offending path and the paths already written, so a half-applied state is reported rather
+than hidden. There is no transactional rollback: the task does not ask for one, and reaching the
+partial state requires a filesystem fault mid-call.
+
+## Observability
+
+`[email-signature-set] op=write accountId=<first-8> files=<written> removed=<removed>` on every
+successful write. The task specifies the line through `files=`; `removed=` is added because the task
+mandates removal as a behaviour and mandates that provisioning be auditable, and an unlogged removal
+is not auditable.
+
+The existing `[email-draft] op=signature applied=<bool> asset=<path>` line stays the per-draft
+signal. An account that has run the setter shows `applied=true` on its next draft. That pair is the
+end-to-end evidence: a write line naming the files, then a draft line reporting them applied.
+
+## Registration
+
+`ADMIN_CORE_TOOLS` is named in the task file but does not exist — `grep -rn 'ADMIN_CORE_TOOLS\s*[:=]'`
+over `platform/` returns nothing, and the name survives only in comments. The live surfaces are:
+
+1. `mcp/src/index.ts` — `eagerTool(server, name, description, zodShape, handler)`.
+2. `PLUGIN.md` — a `tools:` entry (`riskClass: write_local`, `publicAllowlist: false`,
+   `adminAllowlist: false`, matching `email-setup`), a clause in the frontmatter `description:` prose,
+   an operator-docs bullet, and a skills-table row for the new skill.
+3. `platform/templates/specialists/agents/personal-assistant.md` — the `tools:` frontmatter grant, the
+   canonical per-tool permission surface since Task 453.
+
+`riskClass: write_local` is correct because the tool writes account-local files and sends nothing
+outbound, which is the same class `email-setup` carries.
+
+## Skill
+
+`platform/plugins/email/skills/email-signature/SKILL.md`, activated when the operator asks to set or
+change an email signature. It states the loader convention, and three standing rules:
+
+- A signature is installed only through `email-signature-set`. Hand-writing the three files is not a
+  documented path.
+- The agent never hand-builds a signature inside a draft body, because `email-draft` applies the
+  stored one automatically and a hand-built one both duplicates it and drifts from the asset.
+- The signature content is read from the operator's own source of truth and passed through verbatim.
+  Reconstructing markup from memory or from stripped graph text is what put the stale logo in a
+  client draft.
+
+Written as outcomes and constraints, not a step recipe, per `maxy-code/CLAUDE.md`.
+
+## Testing
+
+Added to the plugin's existing vitest surface at `mcp/src/__tests__/`, not substituted for it.
+
+- Round trip: set all three, `loadSignature` returns the exact values, `applySignature` reports
+  `applied` true.
+- Verbatim: text and html land byte-identical, trailing newlines and all; font lands trimmed.
+- Text-only call writes `.txt` and removes a pre-existing `.html` and `.font`, so a later draft
+  carries no stale HTML.
+- All-three-absent call is refused and leaves pre-existing files untouched.
+- Unresolvable directory is refused.
+- A draft composed after a successful set carries body and html exactly equal to `applySignature`
+  output, with no model-authored signature text.
+- `signatureDirFor` prefers `accountDirFor` and falls back to `ACCOUNT_DIR`.
+- A supplied empty string writes an empty file and does not count as absent.
+- Existing `signature.test.ts` stays green.
+
+## Out of scope
+
+- Making `applied=false` a fail-closed refusal on client-facing drafts. Operator scoped this out on
+  2026-07-28 as separate hardening; deliberately not filed.
+- The one-off G.L. Smith provisioning and the stale memory-node deletion. That is a runtime action on
+  the live install, performed through the tool this task ships.
+- Any change to `loadSignature` / `applySignature` behaviour (Task 1952). `signatureDirFor` moves an
+  expression out of `compose.ts`; neither function's behaviour changes.
+- The drafts list/verify capability, which is
+  [Task 2098](../../../../.tasks/pending/2098-email-drafts-list-verify-tool-so-draft-presence-is-confirmable.md).