@rubytech/create-realagent-code 0.1.22 → 0.1.24

package/dist/samba-provision.js

@@ -0,0 +1,215 @@
+// Task 034 — Samba provisioning for the brand Pi filesystem.
+//
+// Same shape as apt-resolve.ts: pure decision functions in this file, no I/O;
+// the installer wraps them with the side-effecting spawnSync + log lines. The
+// pure layer is fully unit-tested; the wrapper is exercised end-to-end on a
+// real Pi during install/uninstall verification.
+//
+// What this module owns:
+//   1. Pick the LAN interface to bind smbd to (loopback excluded).
+//   2. Render the brand-scoped Samba stanza per the spec in the task brief.
+//   3. Merge that stanza into an existing /etc/samba/smb.conf idempotently —
+//      replace if a stanza for this brand already exists, otherwise append.
+//   4. Remove this brand's stanza on uninstall while leaving every peer brand's
+//      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.
+// ---------------------------------------------------------------------------
+// Brand-scoped Samba stanza
+// ---------------------------------------------------------------------------
+/**
+ * Render the `[<brand>]` share stanza. Exact directives are the task's spec
+ * verbatim: share rooted at `sharePath`, writable by `admin` only, force-uid
+ * to admin so files created via SMB are owned by the same uid as files
+ * created over SSH, and standard create/dir masks for an ext4 home directory.
+ */
+export function renderBrandStanza(input) {
+    return [
+        `[${input.brand}]`,
+        `   path = ${input.sharePath}`,
+        `   read only = no`,
+        `   valid users = admin`,
+        `   force user = admin`,
+        `   browseable = yes`,
+        `   create mask = 0664`,
+        `   directory mask = 0775`,
+        ``,
+    ].join("\n");
+}
+/**
+ * Render the `[global]` section. `interfaces = lo <lan>` plus `bind interfaces
+ * only = yes` is the LAN-only posture: smbd accepts connections on the LAN
+ * interface and loopback, nothing else. Cloudflare tunnels carry HTTPS only,
+ * so this is the structural guarantee that SMB never leaves the LAN even if
+ * the firewall is misconfigured upstream.
+ */
+export function renderGlobalSection(input) {
+    return [
+        `[global]`,
+        `   workgroup = WORKGROUP`,
+        `   server string = %h Samba`,
+        `   server role = standalone server`,
+        `   interfaces = lo ${input.lanInterface}`,
+        `   bind interfaces only = yes`,
+        `   log file = /var/log/samba/log.%m`,
+        `   max log size = 1000`,
+        `   panic action = /usr/share/samba/panic-action %d`,
+        `   passdb backend = tdbsam`,
+        `   unix password sync = no`,
+        `   map to guest = bad user`,
+        `   usershare allow guests = no`,
+        ``,
+    ].join("\n");
+}
+/**
+ * Build a complete smb.conf from scratch — globals + one brand stanza. Used
+ * only when no existing config is present (fresh apt install always writes
+ * one, so this branch fires on weird edge cases like operator-deleted conf
+ * files). Normal path is `mergeSmbConf` against the apt-shipped default.
+ */
+export function renderFullSmbConf(input) {
+    return renderGlobalSection({ lanInterface: input.lanInterface }) +
+        renderBrandStanza({ brand: input.brand, sharePath: input.sharePath });
+}
+// ---------------------------------------------------------------------------
+// LAN interface detection
+// ---------------------------------------------------------------------------
+/**
+ * Pick the LAN interface to bind smbd to. Preference order: wlan0, eth0, then
+ * the first non-loopback interface with a non-internal IPv4 address. Returns
+ * null when no such interface exists — the caller treats that as a hard
+ * failure (the Pi has no LAN connectivity; SMB has nothing to bind to).
+ *
+ * Input is the shape returned by `os.networkInterfaces()` so the test can pass
+ * realistic fixtures without spinning up real interfaces.
+ */
+export function pickLanInterface(ifaces) {
+    const hasIPv4 = (name) => {
+        const addrs = ifaces[name];
+        if (!addrs)
+            return false;
+        return addrs.some((a) => a.family === "IPv4" && !a.internal);
+    };
+    if (hasIPv4("wlan0"))
+        return "wlan0";
+    if (hasIPv4("eth0"))
+        return "eth0";
+    for (const name of Object.keys(ifaces)) {
+        if (name === "lo")
+            continue;
+        if (hasIPv4(name))
+            return name;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// smb.conf merge / remove
+// ---------------------------------------------------------------------------
+/**
+ * Find the start and end byte offsets of a `[<section>]` block in an smb.conf.
+ * End is the index just before the next `[…]` header or EOF, whichever comes
+ * first. Returns null when no such section exists.
+ *
+ * Section names are matched case-sensitively because Samba itself is
+ * case-sensitive for share names on Linux filesystems.
+ */
+function findSectionRange(conf, section) {
+    const lines = conf.split("\n");
+    const header = `[${section}]`;
+    let startLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === header) {
+            startLine = i;
+            break;
+        }
+    }
+    if (startLine === -1)
+        return null;
+    let endLine = lines.length;
+    for (let i = startLine + 1; i < lines.length; i++) {
+        if (/^\[[^\]]+\]\s*$/.test(lines[i].trim())) {
+            endLine = i;
+            break;
+        }
+    }
+    const start = lines.slice(0, startLine).reduce((n, l) => n + l.length + 1, 0);
+    const sectionText = lines.slice(startLine, endLine).join("\n") + (endLine < lines.length ? "\n" : "");
+    return { start, end: start + sectionText.length };
+}
+/**
+ * Merge globals + brand stanza into an existing smb.conf. Idempotent: a
+ * second call with the same inputs produces byte-identical output.
+ *
+ *   - `[global]`: replace verbatim with our rendered globals. The apt-shipped
+ *     `[global]` is a good starting point but doesn't carry our LAN-only
+ *     directives; replacing it is the only way to guarantee `bind interfaces
+ *     only = yes` is in effect.
+ *   - `[<brand>]`: replace if present, append at end of file otherwise. Peer
+ *     brand stanzas (other `[…]` blocks) are preserved verbatim.
+ */
+export function mergeSmbConf(input) {
+    const { existing, brand, sharePath, lanInterface } = input;
+    const newGlobals = renderGlobalSection({ lanInterface });
+    const newBrand = renderBrandStanza({ brand, sharePath });
+    let conf = existing;
+    // Replace or insert the global section.
+    const globalRange = findSectionRange(conf, "global");
+    if (globalRange) {
+        conf = conf.slice(0, globalRange.start) + newGlobals + conf.slice(globalRange.end);
+    }
+    else {
+        conf = newGlobals + (conf.startsWith("\n") ? conf : conf);
+    }
+    // Replace or insert the brand stanza.
+    const brandRange = findSectionRange(conf, brand);
+    if (brandRange) {
+        conf = conf.slice(0, brandRange.start) + newBrand + conf.slice(brandRange.end);
+    }
+    else {
+        // Append with a single trailing newline guarantee.
+        if (!conf.endsWith("\n"))
+            conf += "\n";
+        conf += newBrand;
+    }
+    return conf;
+}
+/**
+ * Remove `[<brand>]` from an smb.conf. Returns the input unchanged when no
+ * such stanza exists. Other sections (global, other brands) are preserved
+ * byte-for-byte. Used by the uninstall path.
+ */
+export function removeBrandStanza(input) {
+    const { existing, brand } = input;
+    const range = findSectionRange(existing, brand);
+    if (!range)
+        return existing;
+    return existing.slice(0, range.start) + existing.slice(range.end);
+}
+/**
+ * True when at least one non-global stanza remains in the smb.conf. Used by
+ * uninstall to decide whether to apt-purge samba: only purge when no brand
+ * stanza is left.
+ */
+export function hasAnyBrandStanza(conf) {
+    const lines = conf.split("\n");
+    for (const line of lines) {
+        const m = line.trim().match(/^\[([^\]]+)\]$/);
+        if (m && m[1].toLowerCase() !== "global")
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Step-marker contract
+// ---------------------------------------------------------------------------
+/**
+ * The four install-invariant markers the installer (and uninstall, set-pin)
+ * emit. Locked here so a typo at a call site cannot silently drift from the
+ * spec. The state vocabulary is also locked: `ok` (step succeeded), `fail:
+ * <stderr>` (step threw — installer aborts), `deferred reason=<…>` (step
+ * intentionally skipped because a precondition wasn't met).
+ */
+export const SAMBA_STEPS = ["apt", "conf", "user", "units"];
+export function formatSambaMarker(step, state) {
+    return `[install-invariant] samba-provision-${step} ${state}`;
+}

package/dist/uninstall.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, appendFileSyn
 import { resolve, join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
+import { removeBrandStanza, hasAnyBrandStanza } from "./samba-provision.js";
 const HOME = homedir();
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive brand-specific installation paths.
@@ -23,7 +24,7 @@ catch (err) {
 const INSTALL_DIR = resolve(HOME, BRAND.installDir);
 const CONFIG_DIR = resolve(HOME, BRAND.configDir);
 const LOG_FILE = join("/tmp", `${BRAND.productName.toLowerCase().replace(/\s+/g, "-")}-uninstall-${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
-const TOTAL = "10";
+const TOTAL = "11";
 // ---------------------------------------------------------------------------
 // Logging — timestamped to console AND persistent log file in /tmp
 // (Log lives in /tmp because the uninstall deletes the config directory)
@@ -233,6 +234,80 @@ function stopServices() {
     console.log("  Stopped Ollama");
 }
 // ---------------------------------------------------------------------------
+// Step 1b: Strip the legacy installer-registered cron block
+//
+// Task 039 retired `installCrons()` in src/index.ts. Older installs (every
+// brand prior to the Task 039 release) wrote three minute-cadence entries
+// between `# BEGIN <BRAND> CRONS` and `# END <BRAND> CRONS`. This step
+// removes that block on uninstall so an upgraded device is fully torn down
+// and a subsequent reinstall does not get re-seeded by cron recreating
+// `data/accounts/<accountId>/logs/` every 60s (which tripped seed-neo4j.sh's
+// stub-account-dirs guard — see Task 039 problem statement). Idempotent:
+// no-op when the block is absent. Gated on Linux to mirror the installer's
+// `installCrons` which early-returned on every other platform.
+// ---------------------------------------------------------------------------
+function removeLegacyCronBlock() {
+    log("1b", "Removing legacy cron block...");
+    if (!isLinux()) {
+        console.log("  Skipped — non-Linux platform.");
+        return;
+    }
+    if (!commandExists("crontab")) {
+        console.log("  crontab not available — nothing to strip.");
+        return;
+    }
+    const current = spawnSync("crontab", ["-l"], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    // Non-zero status (or empty stdout) on `crontab -l` means the user has no
+    // crontab at all — nothing to strip, and writing back would create one.
+    if (current.status !== 0 || !current.stdout) {
+        console.log("  Cron block: none present");
+        return;
+    }
+    const beginMarker = `# BEGIN ${BRAND.productName.toUpperCase()} CRONS`;
+    const endMarker = `# END ${BRAND.productName.toUpperCase()} CRONS`;
+    const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const blockPattern = new RegExp(`${escapeRegex(beginMarker)}[\\s\\S]*?${escapeRegex(endMarker)}\\n?`, "g");
+    // Count entry lines (non-comment, non-blank) between markers for the
+    // operator-visible log. matchAll returns all block bodies in one pass.
+    const extractPattern = new RegExp(`${escapeRegex(beginMarker)}([\\s\\S]*?)${escapeRegex(endMarker)}`, "g");
+    let entryCount = 0;
+    for (const match of current.stdout.matchAll(extractPattern)) {
+        entryCount += match[1]
+            .split("\n")
+            .filter((l) => l.trim().length > 0 && !l.trim().startsWith("#"))
+            .length;
+    }
+    if (entryCount === 0 && !blockPattern.test(current.stdout)) {
+        console.log("  Cron block: none present");
+        return;
+    }
+    const stripped = current.stdout.replace(blockPattern, "").trimEnd();
+    if (stripped.length === 0) {
+        // Block was the only content — remove the crontab outright so `crontab -l`
+        // reports "no crontab for admin" (Task 039 success criterion). Writing an
+        // empty buffer via `crontab -` leaves a zero-byte crontab on Debian.
+        const removed = spawnSync("crontab", ["-r"], { stdio: "pipe" });
+        if (removed.status !== 0) {
+            console.log(`  Cron block: stripped ${entryCount} entries but crontab -r failed — ${(removed.stderr ?? "").toString().trim()}`);
+            logFile(`  crontab -r failed: ${removed.stderr}`);
+            return;
+        }
+    }
+    else {
+        const write = spawnSync("crontab", ["-"], {
+            input: stripped + "\n",
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (write.status !== 0) {
+            console.log(`  Cron block: write failed — ${(write.stderr ?? "").trim()}`);
+            logFile(`  crontab write failed: ${write.stderr}`);
+            return;
+        }
+    }
+    console.log(`  Cron block: removed ${entryCount} entries`);
+}
+// ---------------------------------------------------------------------------
 // Step 2: Delete Cloudflare tunnel
 // ---------------------------------------------------------------------------
 function deleteCloudflareTunnel() {
@@ -709,10 +784,90 @@ function removeOllama() {
     // Models directory (~/.ollama/) is removed in step 4 (removeAppDirs)
 }
 // ---------------------------------------------------------------------------
-// Step 10: Restore hostname
+// Task 034 — Samba teardown. Symmetric to provisionSamba in index.ts.
+//
+// Peer-brand discipline: smb.conf, the smbpasswd entry, and the samba apt
+// package are device-wide singletons shared by every brand that ships an
+// SMB share. Drop only this brand's stanza on every uninstall; stop+disable
+// units / smbpasswd -x admin / apt-purge samba run only when no brand stanza
+// remains in smb.conf AND no peer brand is detected. This mirrors the
+// Neo4j / cloudflared / Ollama treatment in steps 5–9 above.
+// ---------------------------------------------------------------------------
+function removeSamba() {
+    log("10", "Removing Samba share...");
+    if (!isLinux()) {
+        console.log("  Not Linux — skipping.");
+        return;
+    }
+    const SMB_CONF = "/etc/samba/smb.conf";
+    if (!existsSync(SMB_CONF)) {
+        console.log("  /etc/samba/smb.conf not present — nothing to remove.");
+        return;
+    }
+    let existing = "";
+    try {
+        const cat = spawnSync("sudo", ["cat", SMB_CONF], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+        if (cat.status === 0)
+            existing = cat.stdout ?? "";
+    }
+    catch {
+        console.log("  Could not read smb.conf — skipping stanza removal.");
+        return;
+    }
+    const stripped = removeBrandStanza({ existing, brand: BRAND.hostname });
+    if (stripped !== existing) {
+        const tee = spawnSync("sudo", ["tee", SMB_CONF], { input: stripped, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 10_000 });
+        if (tee.status === 0) {
+            console.log(`  Removed [${BRAND.hostname}] stanza from ${SMB_CONF}`);
+        }
+        else {
+            console.log(`  Failed to write stripped smb.conf: ${(tee.stderr ?? "").trim()}`);
+        }
+    }
+    else {
+        console.log(`  No [${BRAND.hostname}] stanza found in ${SMB_CONF}`);
+    }
+    // Reload smbd so the brand share disappears from the running config without
+    // dropping connections to peer brand shares. `reload` is best-effort: the
+    // operator has already torn down the brand; failing to reload would leave a
+    // dangling share name but nothing routable to its (now-deleted) sharePath.
+    spawnSync("sudo", ["systemctl", "reload", "smbd"], { stdio: "pipe", timeout: 10_000 });
+    // Per-brand cleanup stops here when a peer brand stanza still references the
+    // share — disabling smbd or purging samba would take the peer's share down.
+    const peer = peerBrandPresent();
+    if (hasAnyBrandStanza(stripped) || peer) {
+        const reason = peer ? `peer brand present (${peer})` : "other brand stanza remains";
+        console.log(`  Leaving smbd/nmbd + samba package in place — ${reason}`);
+        return;
+    }
+    // No brand stanza, no peer brand — full device-wide teardown.
+    try {
+        spawnSync("sudo", ["systemctl", "disable", "--now", "smbd", "nmbd"], { stdio: "pipe", timeout: 30_000 });
+        console.log("  Stopped + disabled smbd, nmbd");
+    }
+    catch (err) {
+        console.log(`  Failed to disable smbd/nmbd: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Drop the admin smbpasswd entry. `smbpasswd -x` exits 0 on success, non-zero
+    // if the user isn't in the passdb — both are acceptable end-states.
+    spawnSync("sudo", ["smbpasswd", "-x", "admin"], { stdio: "pipe", timeout: 10_000 });
+    try {
+        shell("apt-get", ["remove", "--purge", "-y", "samba", "samba-common-bin"], { sudo: true, timeout: 120_000 });
+        console.log("  Purged samba package.");
+    }
+    catch (err) {
+        console.log(`  apt-get purge samba failed: ${err instanceof Error ? err.message : String(err)}`);
+        console.log("  Run manually: sudo apt-get remove --purge -y samba samba-common-bin");
+    }
+    // Drop the smbpasswd sudoers grant once no brand stanza references it.
+    spawnSync("sudo", ["rm", "-f", "/etc/sudoers.d/maxy-samba"], { stdio: "pipe", timeout: 5_000 });
+    console.log("  Removed /etc/sudoers.d/maxy-samba");
+}
+// ---------------------------------------------------------------------------
+// Step 11: Restore hostname
 // ---------------------------------------------------------------------------
 function restoreHostname() {
-    log("10", "Restoring hostname...");
+    log("11", "Restoring hostname...");
     if (!isLinux()) {
         console.log("  Not Linux — skipping.");
         return;
@@ -810,6 +965,7 @@ export async function runUninstall(options) {
     const failures = [];
     const steps = [
         { name: "Stop services", fn: stopServices },
+        { name: "Remove legacy cron block", fn: removeLegacyCronBlock },
         { name: "Delete Cloudflare tunnel", fn: deleteCloudflareTunnel },
         ...(options.exportPath
             ? [{ name: "Export data", fn: () => exportData(options.exportPath) }]
@@ -821,6 +977,7 @@ export async function runUninstall(options) {
         { name: "Remove system configuration", fn: removeSystemConfig },
         { name: "Remove systemd service", fn: removeSystemdService },
         { name: "Remove Ollama", fn: removeOllama },
+        { name: "Remove Samba share", fn: removeSamba },
         { name: "Restore hostname", fn: restoreHostname },
     ];
     for (const step of steps) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

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

@@ -69,6 +69,10 @@ Tools are available via the `admin` MCP server.
 | Manage specialists | User asks to install or remove a specialist subagent, or activate/deactivate premium plugin agents | `skills/specialist-management/SKILL.md` |
 | Generate print-quality PDF | User asks to create a PDF document, one-pager, brochure, or any HTML intended for print/download | `skills/a4-print-documents/SKILL.md` |
 | Plain-English explanation | User asks to explain, define, or pre-empts ("explain in plain English", "what does X mean", "define X", "I don't understand", "what is this"), or admin is about to return a reply containing a term not in the operator's prior turn | `skills/plainly/SKILL.md` |
+| Manage admin users | User asks to add, remove, or list admins on this account, or change an admin PIN | `skills/admin-user-management/SKILL.md` |
+| Session reset / continue / resume | User asks to clear the session, start fresh, continue the last session, or pick up where they left off | `skills/session-management/SKILL.md` |
+| Commitment follow-through | A `<commitment-detected>` block appears in the prompt; the owner has just made a commitment that needs a backing mechanism | `skills/commitment-followthrough/SKILL.md` |
+| Show or download a file | User asks to view, attach, or download a file or document, or the current turn produces a document the owner needs to review | `skills/file-presentation/SKILL.md` |
 
 ## Hooks
 

package/payload/platform/plugins/admin/skills/admin-user-management/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: admin-user-management
+description: "Add, remove, list admins on this account, and update an admin PIN. Triggers when the owner asks to invite another admin, remove an admin, see who has admin access, or change a PIN."
+---
+
+# Admin user management
+
+This skill manages who has admin access to this account. It wraps four MCP tools and carries the discipline that keeps the three identity stores in lockstep. The owner (or any current admin) can manage admins; roles are labels only, with no capability differences enforced.
+
+## The four tools
+
+| Tool | Purpose |
+|---|---|
+| `admin-add` | Add a new admin. Requires a name. PIN is optional: omit it and a unique 4-digit PIN is generated. PIN must be at least 4 digits and unique across all users on the device. |
+| `admin-remove` | Remove an admin by `userId` (find IDs via `admin-list`). The last admin on the account cannot be removed. The user's device-level entry is retained so they can still administer other accounts. |
+| `admin-list` | List all admins on this account with names and roles. |
+| `admin-update-pin` | Update an admin's PIN. Defaults to the calling admin if no `userId` is given. PIN must be at least 4 digits and unique across all users on the device. |
+
+## The three-store invariant
+
+Admin identity lives in three places that must stay in lockstep:
+
+1. `account.json` `admins[]`: account-level role record.
+2. `users.json`: device-level PIN authentication. This is the source of truth at login.
+3. The Neo4j graph: `:AdminUser` + `:Person` + `OWNS` + `ADMIN_OF` edges. Display and graph identity.
+
+`admin-add` writes all three. `admin-update-pin` writes `users.json` only (the other stores carry no PIN). If any leg fails, the tool returns `is_error: true` and `server.log` carries a `[admin-auth-store] action=… userId=… result=fail store=…` line naming which leg failed and what was already written. When you see that line, tell the owner the record is half-written and may need manual reconciliation.
+
+## Never write `account.json` directly
+
+All account-level mutations (`tier`, `outputStyle`, `thinkingView`, `effort`, `enabledPlugins`, `admins[]`, agent settings) go through the dedicated MCP tools: `account-update`, `plugin-toggle-enabled`, `admin-add`, `admin-remove`. The pre-tool-use hook denies direct `Edit` or `Write` on `account.json` server-side; this rule is the explanation for the denial. `tier` and `purchasedPlugins` derive from a Rubytech-signed entitlement payload on commercial installs, so a hand-edit is silently void.
+
+## `admin-add` retries: re-pass any user-stated PIN
+
+If `admin-add` returns an error (tier cap reached, PIN collision) and the owner resolves the blocker (upgrade tier, remove an existing admin), the retried `admin-add` MUST re-pass the PIN the owner originally stated as the `pin` parameter. Omitting `pin` on the retry auto-generates a different 4-digit PIN, silently substituting what the owner asked for. The resulting `admin-update-pin` correction loop is exactly the failure mode this rule exists to prevent.
+
+## Standard flow
+
+1. Read the request. Identify which of the four operations applies.
+2. For `admin-add`, gather the name. The PIN is optional; if the owner stated one, use it; otherwise let the tool generate one. For `admin-remove`, call `admin-list` first if the owner did not give a `userId`.
+3. Call the tool.
+4. If the tool succeeds, confirm the result in plain English. Include the PIN in the reply for `admin-add` so the owner can share it with the new admin.
+5. If the tool returns an error, surface the failure and the `[admin-auth-store]` line from `server.log` if present. Do not retry the same call; resolve the underlying blocker first.
+
+## What this skill does not do
+
+It does not manage tier upgrades. It does not change account-level settings. It does not manage public agents or plugins. Each of those has its own skill.

package/payload/platform/plugins/admin/skills/commitment-followthrough/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: commitment-followthrough
+description: "Handles the platform-detected commitment signal: offers to track or automate the commitment, waits for owner confirmation, then picks the right backing mechanism (scheduled event, task, or workflow). Loads when the system prompt contains a `<commitment-detected>` block."
+---
+
+# Commitment follow-through
+
+This skill activates when the platform identifies that the owner has just made a commitment: something they said they would do. The skill's job is to offer the right backing mechanism, wait for the owner's confirmation, then create it. Without a backing mechanism, a commitment is a broken promise; with one, the agent can hold the owner to their word.
+
+## The trigger
+
+A `<commitment-detected>` block appears in the system prompt. The block names what the platform classifier extracted: the commitment text, the suggested mechanism (scheduled event, task, or workflow), and any time, recipient, or topic the classifier inferred.
+
+## How to offer
+
+Surface a brief, conversational offer. Name the commitment, name the suggested mechanism, and ask the owner to confirm, modify, or dismiss. One or two sentences. Not a form. Not a list of options. Examples:
+
+- "I'll set a reminder for Tuesday morning to chase the Acme invoice. Confirm?"
+- "Want me to create a task for the photo brief so it doesn't slip?"
+- "Shall I schedule the weekly check-in with Daniel on Mondays at 9?"
+
+## Never act without confirmation
+
+The owner must say "yes" or give specifics before any tool call. If they dismiss ("no thanks", "I'll handle it"), acknowledge briefly and continue with whatever they were discussing. Do not re-offer for the same commitment.
+
+If they modify ("make it next Monday instead"), incorporate the changes and confirm before creating.
+
+## The two-rule discipline
+
+This skill is the operator's side of the two-rule contract on commitments.
+
+1. **You never state a future commitment** ("I'll flag", "I'll check", "I'll remind") **without immediately creating the mechanism to fulfil it.** A commitment without a backing mechanism is a broken promise.
+2. **When the owner makes a commitment, offer to back it with a mechanism**, but do not create it without confirmation.
+
+Rule 1 is yours; rule 2 is this skill's job.
+
+## Picking the mechanism
+
+Use the most appropriate tool:
+
+- `schedule-event` for time-bound reminders (every Monday, on Tuesday, by Friday).
+- `task-create` for open-ended obligations (chase X, finish Y, prepare Z).
+- `workflow-create` for multi-step processes that recur (monthly close-out, new-instruction onboarding).
+
+## Verify executor capabilities before promising a workflow
+
+Before committing to build a workflow, check that every step maps to a capability the executor actually has. Tool steps need the named plugin and tool to exist. Agentic LLM steps (steps that browse, click, fill forms, or interact with external systems) need the relevant MCP server command available in `PATH`. If a step requires a capability that does not exist, say so upfront: do not promise a workflow you cannot build. The owner can either narrow the scope or wait for the capability to ship.
+
+## After creation
+
+Tell the owner what was created (task ID, scheduled event time, workflow name) so they have something they can reference, modify, or cancel later. Then resume the conversation.
+
+## Failure modes
+
+- **`<commitment-detected>` block names a mechanism that does not exist** (e.g. `workflow-create` while workflows are not enabled on this account). Surface the gap and offer the next-best mechanism.
+- **Owner approves but the create tool fails.** Surface the error literally. Do not silently substitute a different mechanism.
+
+## What this skill does not do
+
+It does not detect commitments itself; the platform does that and injects the block. It does not act on the owner's behalf without explicit confirmation. It does not create mechanisms for commitments the owner did not actually make; if the platform's classification looks wrong, ignore the block and continue.

package/payload/platform/plugins/admin/skills/file-presentation/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: file-presentation
+description: "Render a file or document inline for the owner to view, edit, and download. Triggers when the owner asks to see, attach, or download a file, when content is generated that the owner needs to review (summary, report, draft), or when a downloadable artefact is the right output."
+---
+
+# File presentation
+
+This skill makes a file visible and downloadable inside the chat. It is the only sanctioned path for delivering file content to the owner. Synthesised content (a summary, a report, a draft) follows the same path: render via `document-editor` so the owner can review and download.
+
+## The trigger
+
+The owner asks to view, review, attach, or download a file or a document, or the current turn produces a document that the owner needs to see. Example phrasings:
+
+- "show me the file"
+- "attach the report"
+- "let me download that"
+- "preview the document"
+- "send me the brochure"
+- "save that as a markdown file"
+
+## How to render
+
+Call `render-component` with:
+
+```
+name: "document-editor"
+data: {
+  title: "<owner-facing title>",
+  content: "<the file content as markdown>"
+}
+```
+
+The component gives the owner a render-review-edit-download flow: they see the content inline, can edit it in place, and can download it as a `.md` file directly from the component. Do not use `memory-write`, `memory-ingest`, or other tools to deliver file content to the owner; those tools have different purposes and skipping the render-review-download flow takes control away from the owner.
+
+## Character sanitisation: the silent-failure rule
+
+The document-editor's markdown parser fails silently on these typographical characters:
+
+| Character | Unicode | Replace with |
+|---|---|---|
+| em-dash | U+2014 | hyphen with spaces |
+| en-dash | U+2013 | hyphen with spaces |
+| left curly double quote | U+201C | straight double quote |
+| right curly double quote | U+201D | straight double quote |
+| left curly single quote | U+2018 | straight single quote |
+| right curly single quote | U+2019 | straight single quote |
+| horizontal ellipsis | U+2026 | three periods |
+
+Strip and replace these characters in the `content` field before the `render-component` call. The owner does not see a partial render or a warning; the content just silently breaks at the offending character. Currency symbols (£, €), accented characters, and other Unicode are unaffected: use them normally.
+
+## When the file is a binary
+
+For PDF, image, audio, or any binary deliverable, use `file-attach` plus `render-component` with `name: file-attachment` and pass the returned path. The document-editor component is for editable markdown text only.
+
+## For static-site delivery
+
+When the owner has uploaded a `.zip` containing HTML and assets and wants it hosted, this skill is not the right path. Delegate to `content-producer` on turn one; the specialist owns the `unzip-attachment` then `publish-site` chain.
+
+## Failure modes
+
+- **Content is too large for the component** (typically over 50,000 characters of markdown). Surface the size and offer to split into sections, save as an attachment, or render only the first section with a follow-up for the rest.
+- **`render-component` returns an error.** Surface the error literally. Do not paste the content into chat as a fallback; the owner asked for the render-review-download flow, not a wall of text.
+- **The content contains characters the parser rejects after the sanitisation pass** (rare; usually a non-printable control character). Strip the offending characters and surface a one-line warning naming the position.
+
+## What this skill does not do
+
+It does not write the content to the graph. It does not save the content to disk. The component handles the download path; the owner downloads what they edited in the component.