@rubytech/create-maxy-code 0.1.222 → 0.1.224

package/dist/__tests__/installer-settings-permissions.test.js

@@ -0,0 +1,112 @@
+// Task 583 — Installer must seed permissions.defaultMode=bypassPermissions
+// and permissions.allow=["*"] into the brand-scoped settings.json so
+// claude.ai/code sessions never fall through to the Anthropic remote
+// auto-classifier. Existing top-level keys must be preserved; an
+// already-correct file must be a true no-op (mtime unchanged).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync, statSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { seedBypassPermissionsSettings, assertBypassPermissionsSeed, BYPASS_PERMISSIONS_BLOCK } from "../permissions-seed.js";
+function freshDir() {
+    return mkdtempSync(join(tmpdir(), "t583-"));
+}
+test("empty target: creates settings.json with the permissions block", () => {
+    const dir = freshDir();
+    try {
+        const result = seedBypassPermissionsSettings(dir);
+        assert.equal(result.action, "seeded");
+        assert.equal(result.path, join(dir, "settings.json"));
+        const parsed = JSON.parse(readFileSync(result.path, "utf-8"));
+        assert.deepEqual(parsed, { permissions: { defaultMode: "bypassPermissions", allow: ["*"], deny: [] } });
+        assert.equal(assertBypassPermissionsSeed(dir).status, "ok");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("existing keys preserved verbatim; permissions added", () => {
+    const dir = freshDir();
+    try {
+        const settingsPath = join(dir, "settings.json");
+        const existing = {
+            enabledPlugins: { "memory@claude-plugins-official": true },
+            extraKnownMarketplaces: { "claude-plugins-official": { source: { source: "github", repo: "anthropics/claude-plugins-official" } } },
+            inputNeededNotifEnabled: false,
+            agentPushNotifEnabled: false,
+            model: "opus",
+        };
+        writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
+        const result = seedBypassPermissionsSettings(dir);
+        assert.equal(result.action, "seeded");
+        const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        assert.deepEqual(parsed.enabledPlugins, existing.enabledPlugins);
+        assert.deepEqual(parsed.extraKnownMarketplaces, existing.extraKnownMarketplaces);
+        assert.equal(parsed.inputNeededNotifEnabled, false);
+        assert.equal(parsed.agentPushNotifEnabled, false);
+        assert.equal(parsed.model, "opus");
+        assert.deepEqual(parsed.permissions, { defaultMode: "bypassPermissions", allow: ["*"], deny: [] });
+        assert.equal(assertBypassPermissionsSeed(dir).status, "ok");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("idempotent: already-correct block triggers no write", () => {
+    const dir = freshDir();
+    try {
+        const settingsPath = join(dir, "settings.json");
+        writeFileSync(settingsPath, JSON.stringify({ model: "opus", permissions: { defaultMode: "bypassPermissions", allow: ["*"], deny: [] } }, null, 2));
+        const before = statSync(settingsPath).mtimeMs;
+        // Small busy-wait so a same-millisecond write would be detectable on
+        // filesystems with millisecond mtime granularity.
+        const target = Date.now() + 15;
+        while (Date.now() < target) { /* spin */ }
+        const result = seedBypassPermissionsSettings(dir);
+        assert.equal(result.action, "noop");
+        const after = statSync(settingsPath).mtimeMs;
+        assert.equal(after, before, "mtime must not change on noop");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("malformed JSON: overwrites with the seeded block", () => {
+    const dir = freshDir();
+    try {
+        const settingsPath = join(dir, "settings.json");
+        writeFileSync(settingsPath, "{ not json");
+        const result = seedBypassPermissionsSettings(dir);
+        assert.equal(result.action, "seeded");
+        assert.equal(assertBypassPermissionsSeed(dir).status, "ok");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("assert: missing file reports missing", () => {
+    const dir = freshDir();
+    try {
+        assert.equal(assertBypassPermissionsSeed(dir).status, "missing");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("assert: partial block (no wildcard) reports missing", () => {
+    const dir = freshDir();
+    try {
+        writeFileSync(join(dir, "settings.json"), JSON.stringify({ permissions: { defaultMode: "default", allow: [], deny: [] } }));
+        assert.equal(assertBypassPermissionsSeed(dir).status, "missing");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("BYPASS_PERMISSIONS_BLOCK frozen literal matches expected shape", () => {
+    assert.equal(BYPASS_PERMISSIONS_BLOCK.defaultMode, "bypassPermissions");
+    assert.deepEqual([...BYPASS_PERMISSIONS_BLOCK.allow], ["*"]);
+    assert.deepEqual([...BYPASS_PERMISSIONS_BLOCK.deny], []);
+    assert.ok(Object.isFrozen(BYPASS_PERMISSIONS_BLOCK));
+});

package/dist/index.js

@@ -2,6 +2,7 @@
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, statSync, realpathSync } from "node:fs";
 import { registerSpecialistAgentsAt, SpecialistSymlinkCollision } from "./specialist-registration.js";
+import { seedBypassPermissionsSettings, assertBypassPermissionsSeed } from "./permissions-seed.js";
 import { resolve, join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerUnitFile, buildClaudePtysSliceUnitFile } from "./port-resolution.js";
@@ -18,7 +19,7 @@ import { classifyPortHolder } from "./preflight-port-classifier.js";
 import { parsePluginList, computeInstallActions, computeConfigureActions, parseExternalPlugins, } from "./lib/plugin-install.js";
 import { findPremiumMcpDirs } from "./lib/premium-mcp-discover.js";
 import { pickLanInterface, mergeSmbConf, formatSambaMarker, } from "./samba-provision.js";
-import { networkInterfaces, userInfo, homedir } from "node:os";
+import { networkInterfaces, userInfo } from "node:os";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -953,6 +954,12 @@ function installClaudeCode() {
     // pre-create the per-brand CLAUDE_CONFIG_DIR so the first
     // `claude plugin marketplace add` has a directory to write into.
     mkdirSync(CLAUDE_CONFIG_DIR, { recursive: true });
+    // Task 583 — seed the brand-scoped permissions block so claude.ai/code
+    // sessions short-circuit Stage 1 of the local matcher and never fall
+    // through to the Anthropic remote auto-classifier (which routes Agent
+    // dispatch to `ask` and surfaces a prompt no unattended operator clicks).
+    const permissionsSeed = seedBypassPermissionsSettings(CLAUDE_CONFIG_DIR);
+    logFile(`[install-permissions] action=${permissionsSeed.action} path=${permissionsSeed.path}`);
     const marketplaceList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
     if (marketplaceList.stderr)
         process.stderr.write(marketplaceList.stderr);
@@ -2053,6 +2060,12 @@ function registerLocalAndExternalPlugins() {
         throw new Error(`Plugin registration incomplete: expected marketplaces ${JSON.stringify([...expectedMarketplaces])} but \`claude plugin marketplace list\` returned ${JSON.stringify(actualMarketplaces)}. Missing: ${JSON.stringify(missing)}. Check setup.log for [plugin-marketplace] ERROR lines.`);
     }
     logFile(`[plugin-marketplace] assertion-source=claude-plugin-marketplace-list count=${actualMarketplaces.length} marketplaces=${JSON.stringify(actualMarketplaces)} CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
+    // Task 583 — post-install assertion that the brand-scoped permissions
+    // block survived install. Warn-only: a missing block does not abort the
+    // install (consistent with the marketplace ERROR path that logs and
+    // continues per-entry), but surfaces in setup.log for diagnosis.
+    const permissionsAssert = assertBypassPermissionsSeed(CLAUDE_CONFIG_DIR);
+    logFile(`[install-permissions] brand-settings=${permissionsAssert.status} path=${permissionsAssert.path}`);
 }
 function buildPlatform() {
     log("9", TOTAL, "Installing dependencies and building...");
@@ -3276,51 +3289,6 @@ WantedBy=multi-user.target
     // and fail with EADDRINUSE. Fresh installs: the stop is a no-op.
     const unitName = BRAND.serviceName.replace(".service", "");
     const claudeSessionManagerUnitShort = claudeSessionManagerUnitName.replace(".service", "");
-    // Task 579 — admin-enumeration acceptance gate. Runs against the
-    // freshly-deployed payload before the systemctl restart cluster so a
-    // regression in the admin tool surface fails the install and keeps
-    // the old service running. The harness exit code is the gate; a
-    // non-zero exit logs the JSONL evidence path to install.log and
-    // process.exit(1) before we touch any unit. Set MAXY_SKIP_ENUMERATE_GATE=1
-    // to bypass for cases where the operator is iterating on a different
-    // surface and accepts the regression risk; absence is the default.
-    if (!process.env.MAXY_SKIP_ENUMERATE_GATE) {
-        const harness = join(INSTALL_DIR, "platform/plugins/admin/__tests__/admin-can-enumerate.test.sh");
-        if (existsSync(harness)) {
-            const brandConfigDir = join(homedir(), BRAND.configDir, ".claude");
-            console.log("  Running admin-enumerate acceptance gate...");
-            const gateResult = spawnSync("bash", [harness], {
-                stdio: "inherit",
-                env: {
-                    ...process.env,
-                    CLAUDE_CONFIG_DIR: brandConfigDir,
-                    INSTALL_DIR,
-                },
-            });
-            if (gateResult.status !== 0) {
-                const installLog = join(homedir(), BRAND.configDir, "logs", "install.log");
-                const ts = new Date().toISOString();
-                try {
-                    mkdirSync(dirname(installLog), { recursive: true });
-                    appendFileSync(installLog, `${ts} [admin-enumerate-gate] FAIL exit=${gateResult.status ?? "null"} — admin seat could not locate seeded site within budget. Payload NOT swapped into systemd.\n`);
-                }
-                catch {
-                    // best-effort
-                }
-                console.error(`\n  ❌ admin-enumerate gate failed (exit ${gateResult.status ?? "null"}).\n` +
-                    `  The new payload is on disk at ${INSTALL_DIR} but systemd was NOT restarted.\n` +
-                    `  Old service is still running. See ${installLog} for one-line summary.\n`);
-                process.exit(1);
-            }
-            console.log("  admin-enumerate gate passed.");
-        }
-        else {
-            console.log(`  [admin-enumerate-gate] SKIP reason=harness-not-on-disk path=${harness}`);
-        }
-    }
-    else {
-        console.log("  [admin-enumerate-gate] SKIP reason=MAXY_SKIP_ENUMERATE_GATE=1");
-    }
     spawnSync("systemctl", ["--user", "stop", unitName], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "enable", edgeUnitShort], { stdio: "inherit" });

package/dist/permissions-seed.js

@@ -0,0 +1,76 @@
+// Task 583 — Seed Claude Code's two-stage permission classifier with a
+// wildcard allow so claude.ai/code sessions never fall through to the
+// Anthropic remote auto-classifier. The classifier routes `Agent`/`Task`
+// to `ask`, which surfaces as a permission prompt that an unattended
+// operator never clicks — observed as 4-minute dead-air hangs on
+// realagent-code.
+//
+// This module is the single writer for the brand-scoped settings.json
+// permissions block. Account-scoped settings.json is written by
+// platform/scripts/setup-account.sh in lockstep with the same shape.
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+export const BYPASS_PERMISSIONS_BLOCK = Object.freeze({
+    defaultMode: "bypassPermissions",
+    allow: ["*"],
+    deny: [],
+});
+function isAlreadyCorrect(permissions) {
+    if (!permissions || typeof permissions !== "object")
+        return false;
+    const p = permissions;
+    if (p.defaultMode !== "bypassPermissions")
+        return false;
+    if (!Array.isArray(p.allow) || !p.allow.includes("*"))
+        return false;
+    if (!Array.isArray(p.deny) || p.deny.length !== 0)
+        return false;
+    return true;
+}
+export function seedBypassPermissionsSettings(configDir) {
+    const settingsPath = join(configDir, "settings.json");
+    let existing = {};
+    if (existsSync(settingsPath)) {
+        const text = readFileSync(settingsPath, "utf-8");
+        if (text.trim().length > 0) {
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    existing = parsed;
+                }
+            }
+            catch {
+                // Malformed JSON: treat as empty and overwrite with a well-formed
+                // file containing only the permissions block. Any keys the prior
+                // file carried are unrecoverable from invalid JSON anyway.
+            }
+        }
+    }
+    if (isAlreadyCorrect(existing.permissions)) {
+        return { action: "noop", path: settingsPath };
+    }
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    const merged = { ...existing, permissions: { ...BYPASS_PERMISSIONS_BLOCK, allow: [...BYPASS_PERMISSIONS_BLOCK.allow], deny: [] } };
+    const tmpPath = `${settingsPath}.task583.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(merged, null, 2) + "\n");
+    renameSync(tmpPath, settingsPath);
+    return { action: "seeded", path: settingsPath };
+}
+export function assertBypassPermissionsSeed(configDir) {
+    const settingsPath = join(configDir, "settings.json");
+    if (!existsSync(settingsPath))
+        return { status: "missing", path: settingsPath };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    }
+    catch {
+        return { status: "missing", path: settingsPath };
+    }
+    if (!parsed || typeof parsed !== "object")
+        return { status: "missing", path: settingsPath };
+    const permissions = parsed.permissions;
+    return isAlreadyCorrect(permissions)
+        ? { status: "ok", path: settingsPath }
+        : { status: "missing", path: settingsPath };
+}

package/package.json

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

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:cabadf29cd1f98c47b4f93c23339ee577ce7bb41092d085d01268b947165a1d5
+content-hash: sha256:4b8d8eafde682590492196ad2fd4385193ccf3fd5623f5d0acda78d27bf58526
 brand: maxy-code
 product-name: Maxy
 ---
@@ -300,6 +300,10 @@ All three are tunable via env vars (`CLAUDE_SESSION_MANAGER_SPECIALIST_CAP`, `CL
 
 If you suspect background processes are piling up, run `grep '\[reaper\]' ~/.{brand}/logs/server.log | tail -50` — each tick logs how many rows it scanned and reaped.
 
+## Tool Permissions
+
+Every install seeds a wildcard `permissions.allow:["*"]` plus `defaultMode:"bypassPermissions"` into both the brand-scoped settings file (`~/.{brand}/.claude/settings.json`) and every account-scoped one (`<install>/data/accounts/<id>/.claude/settings.json`). This stops Claude Code from sending tool calls to its remote auto-classifier, which would otherwise surface a permission prompt in the chat that an unattended session never answers. What each subagent is allowed to use is still controlled by the `tools:` line in its agent file, not by a top-level allowlist. To verify after an install: `cat ~/.{brand}/.claude/settings.json | jq '.permissions'`.
+
 ---
 # Plugins Guide
 Source: https://docs.getmaxy.com/plugins-guide.md
@@ -3752,7 +3756,7 @@ If the initial Cloudflare login fails during setup, Maxy will fall back to askin
 Both flows run on the native Claude Code PTY surface in admin chat (Task 287). The retired action-runner / terminal-modal troubleshooting sections that lived here have been removed because those surfaces no longer exist; failures now manifest as plain stderr from the agent-invoked Bash command, visible in chat.
 
 - **Software update.** Re-run `npx -y @rubytech/create-<brand>@latest` from a shell; if the installer fails, its stdout is the diagnostic record. HeaderMenu turns sage when `installed === latest`.
-- **Cloudflare setup.** The agent invokes `cloudflared` directly via Bash, following the cloudflare plugin's `references/manual-setup.md`. Failures surface as cloudflared's literal stderr plus a non-zero exit. Recovery paths live in `references/reset-guide.md` and `references/manual-setup.md`.
+- **Cloudflare setup.** The agent invokes `cloudflared` directly via Bash, following the cloudflare plugin's `plugins/cloudflare/references/manual-setup.md`. Failures surface as cloudflared's literal stderr plus a non-zero exit. Recovery paths live in `plugins/cloudflare/references/reset-guide.md` and `plugins/cloudflare/references/manual-setup.md`.
 
 ## Orphan Account Directory Archived to `.trash/`
 

package/payload/platform/plugins/docs/references/platform.md

@@ -187,3 +187,7 @@ Messages you write yourself (e.g. typing directly in WhatsApp) are not marked
 All three are tunable via env vars (`CLAUDE_SESSION_MANAGER_SPECIALIST_CAP`, `CLAUDE_SESSION_MANAGER_OPERATOR_RESERVE`, `CLAUDE_SESSION_MANAGER_TOTAL_PTY_CAP`, `CLAUDE_SESSION_MANAGER_RECORDER_IDLE_TTL_MS`); developer details in `.docs/platform.md` § "Claude Session Manager — PTY Slot Safeguards".
 
 If you suspect background processes are piling up, run `grep '\[reaper\]' ~/.{brand}/logs/server.log | tail -50` — each tick logs how many rows it scanned and reaped.
+
+## Tool Permissions
+
+Every install seeds a wildcard `permissions.allow:["*"]` plus `defaultMode:"bypassPermissions"` into both the brand-scoped settings file (`~/.{brand}/.claude/settings.json`) and every account-scoped one (`<install>/data/accounts/<id>/.claude/settings.json`). This stops Claude Code from sending tool calls to its remote auto-classifier, which would otherwise surface a permission prompt in the chat that an unattended session never answers. What each subagent is allowed to use is still controlled by the `tools:` line in its agent file, not by a top-level allowlist. To verify after an install: `cat ~/.{brand}/.claude/settings.json | jq '.permissions'`.

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -211,7 +211,7 @@ If the initial Cloudflare login fails during setup, {{productName}} will fall ba
 Both flows run on the native Claude Code PTY surface in admin chat (Task 287). The retired action-runner / terminal-modal troubleshooting sections that lived here have been removed because those surfaces no longer exist; failures now manifest as plain stderr from the agent-invoked Bash command, visible in chat.
 
 - **Software update.** Re-run `npx -y @rubytech/create-<brand>@latest` from a shell; if the installer fails, its stdout is the diagnostic record. HeaderMenu turns sage when `installed === latest`.
-- **Cloudflare setup.** The agent invokes `cloudflared` directly via Bash, following the cloudflare plugin's `references/manual-setup.md`. Failures surface as cloudflared's literal stderr plus a non-zero exit. Recovery paths live in `references/reset-guide.md` and `references/manual-setup.md`.
+- **Cloudflare setup.** The agent invokes `cloudflared` directly via Bash, following the cloudflare plugin's `plugins/cloudflare/references/manual-setup.md`. Failures surface as cloudflared's literal stderr plus a non-zero exit. Recovery paths live in `plugins/cloudflare/references/reset-guide.md` and `plugins/cloudflare/references/manual-setup.md`.
 
 ## Orphan Account Directory Archived to `.trash/`
 

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

@@ -150,4 +150,4 @@ Import `.ics` files uploaded by the user. Use `schedule-import-ics` with the att
 Cron→RRULE mapping for recurring events: daily, weekly-with-days, and monthly-by-date patterns produce standard RRULE properties. Cron patterns that cannot map to RRULE (e.g. `0 8 1,15 * *`) produce individual VEVENTs per occurrence instead.
 
 ## References
-- references/scheduling.md (inherited from business-assistant — booking protocol, geographic clustering, briefings)
+- plugins/business-assistant/references/scheduling.md (booking protocol, geographic clustering, briefings)

package/payload/platform/scripts/check-plugin-references.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// Task 581 — bundle-time existence check for `references/<file>.md` paths
+// cited in PLUGIN.md, SKILL.md, and specialist agent template bodies.
+//
+// Why: the `plugin-read` tool resolves `pluginName + file` against
+// `<platform>/plugins/<pluginName>/<file>`. When a doc body cites
+// `references/foo.md` (or `plugins/<other>/references/foo.md`) and that file
+// does not exist, the agent burns a tool call only to receive
+// "Plugin file not found". This module fails the bundle before such a payload
+// is assembled.
+//
+// Two citation shapes are extracted:
+//   1. Bare `references/<file>.md` — resolves under the citing file's owning
+//      plugin directory (PLUGIN.md and skills/<slug>/SKILL.md only; specialist
+//      templates have no plugin owner, so the bare shape there is itself a
+//      violation).
+//   2. `plugins/<name>/references/<file>.md` (optionally prefixed by
+//      `platform/`) — resolves at `<platformRoot>/plugins/<name>/references/
+//      <file>.md`.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { resolve, relative, join, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Citation shapes captured (all must end in `references/<file>.md`):
+//   references/<file>.md
+//   plugins/<name>/references/<file>.md
+//   plugins/<name>/skills/<slug>/references/<file>.md
+//   skills/<slug>/references/<file>.md
+//   platform/<any of the above starting with plugins/>
+//
+// The lookbehind excludes [a-z0-9_/-] so the capture cannot start mid-path
+// (`foo/references/bar.md` does not match). `/` is in the excluded set —
+// that prevents a mid-path `references/...` from being captured without its
+// leading `skills/<slug>/` or `plugins/<name>/` prefix. Every legitimate
+// citation root we want to recognise is named explicitly in the alternation.
+const REF_PATTERN =
+  /(?:^|[^a-z0-9_/-])((?:platform\/)?(?:plugins\/[a-z0-9][a-z0-9-]*\/)?(?:skills\/[a-z0-9][a-z0-9-]*\/)?references\/[a-z0-9][a-z0-9-]*\.md)/g;
+
+// Walk `dir` recursively, collecting every file whose basename matches `predicate`.
+function walk(dir, predicate, out = []) {
+  if (!existsSync(dir)) return out;
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      walk(full, predicate, out);
+    } else if (predicate(entry, full)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Plugin root for a citing file, or null if there is none (specialist
+// templates). For SKILL.md, walks dirname up past `skills/<slug>/` to the
+// ancestor that contains the `skills` segment as a direct child.
+function owningPluginRoot(filePath) {
+  if (filePath.endsWith("/PLUGIN.md")) {
+    return dirname(filePath);
+  }
+  if (filePath.endsWith("/SKILL.md")) {
+    let cursor = dirname(filePath);
+    while (cursor && cursor !== "/" && cursor !== ".") {
+      const parts = cursor.split("/");
+      if (parts[parts.length - 1] === "skills") {
+        return dirname(cursor);
+      }
+      cursor = dirname(cursor);
+    }
+  }
+  return null;
+}
+
+// Directories to resolve a bare `references/<file>.md` citation against.
+// Returns an array of candidate directories; the citation passes if the file
+// exists under ANY of them. Both candidate paths for SKILL.md are reachable
+// via `plugin-read` — the agent may construct `file=references/foo.md`
+// (plugin-root form) or `file=skills/<slug>/references/foo.md` (skill-local
+// form), depending on how the plugin organises its references.
+//
+//   PLUGIN.md       — plugin-root only.       → [<plugin-root>]
+//   SKILL.md        — skill-local OR plugin-root.
+//                                              → [<skill-dir>, <plugin-root>]
+//   specialist template — no owning context.   → []
+function bareReferenceContextDirs(filePath) {
+  if (filePath.endsWith("/PLUGIN.md")) {
+    return [dirname(filePath)];
+  }
+  if (filePath.endsWith("/SKILL.md")) {
+    const skillDir = dirname(filePath);
+    const pluginRoot = owningPluginRoot(filePath);
+    return pluginRoot ? [skillDir, pluginRoot] : [skillDir];
+  }
+  return [];
+}
+
+// Return every candidate absolute path a citation could resolve to. The
+// citation passes the existence check if ANY candidate exists. Returns an
+// empty array if the citation has no resolvable shape (bare reference cited
+// from a non-plugin file).
+function candidateTargets({ raw, sourcePath, platformRoot }) {
+  // Strip an optional leading `platform/` so `platform/plugins/<name>/...`
+  // and `plugins/<name>/...` resolve identically.
+  const normalised = raw.replace(/^platform\//, "");
+
+  // Cross-plugin (and cross-plugin-sub-skill) references resolve at the
+  // platform root regardless of the citing file's owning plugin.
+  if (normalised.startsWith("plugins/")) {
+    return [resolve(platformRoot, normalised)];
+  }
+
+  // `skills/<slug>/references/<file>.md` resolves under the citing file's
+  // owning plugin directory. Used by PLUGIN.md bodies that index references
+  // owned by sub-skills (e.g. premium-plugins/teaching/PLUGIN.md).
+  if (normalised.startsWith("skills/")) {
+    const pluginRoot = owningPluginRoot(sourcePath);
+    return pluginRoot ? [resolve(pluginRoot, normalised)] : [];
+  }
+
+  // Bare `references/<file>.md`.
+  const ctxDirs = bareReferenceContextDirs(sourcePath);
+  return ctxDirs.map(d => resolve(d, normalised));
+}
+
+function scanFile(filePath, { platformRoot, repoRoot }) {
+  let body;
+  try {
+    body = readFileSync(filePath, "utf-8");
+  } catch {
+    return { violations: [], citations: 0 };
+  }
+  const violations = [];
+  let citations = 0;
+  const lines = body.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    REF_PATTERN.lastIndex = 0;
+    let m;
+    while ((m = REF_PATTERN.exec(line)) !== null) {
+      const raw = m[1];
+      // 1-based column, pointing at the start of the captured citation.
+      const column = (m.index + m[0].indexOf(raw)) + 1;
+      citations++;
+      const candidates = candidateTargets({ raw, sourcePath: filePath, platformRoot });
+      if (candidates.length === 0) {
+        violations.push({
+          source: relative(repoRoot, filePath),
+          line: i + 1,
+          column,
+          target: "<no plugin owner — bare references/ cited from non-plugin file>",
+          raw,
+        });
+        continue;
+      }
+      if (!candidates.some(p => existsSync(p))) {
+        // Report the most informative candidate — for SKILL.md citations the
+        // first candidate is the skill-local path; if both exist as candidates,
+        // listing both makes the fix unambiguous.
+        const targetMsg = candidates.length === 1
+          ? candidates[0]
+          : `none of [${candidates.join(", ")}]`;
+        violations.push({
+          source: relative(repoRoot, filePath),
+          line: i + 1,
+          column,
+          target: targetMsg,
+          raw,
+        });
+      }
+    }
+  }
+  return { violations, citations };
+}
+
+export function runPluginReferenceCheck({ platformRoot, premiumRoot }) {
+  const repoRoot = resolve(platformRoot, "..");
+  const sources = [];
+
+  // platform: every PLUGIN.md and every SKILL.md under plugins/
+  const platformPlugins = resolve(platformRoot, "plugins");
+  walk(
+    platformPlugins,
+    (name) => name === "PLUGIN.md" || name === "SKILL.md",
+    sources,
+  );
+
+  // platform: every specialist template
+  const specialistDir = resolve(platformRoot, "templates", "specialists", "agents");
+  walk(specialistDir, (name) => name.endsWith(".md"), sources);
+
+  // premium: every PLUGIN.md and SKILL.md under any bundle (standalone or sub)
+  if (premiumRoot && existsSync(premiumRoot)) {
+    walk(
+      premiumRoot,
+      (name) => name === "PLUGIN.md" || name === "SKILL.md",
+      sources,
+    );
+  }
+
+  const violations = [];
+  let citations = 0;
+  for (const src of sources) {
+    const r = scanFile(src, { platformRoot, repoRoot });
+    violations.push(...r.violations);
+    citations += r.citations;
+  }
+
+  return {
+    ok: violations.length === 0,
+    violations,
+    scanned: sources.length,
+    citations,
+  };
+}
+
+// CLI entry — `node check-plugin-references.mjs [platformRoot] [premiumRoot]`.
+// Use `pathToFileURL` so the self-detect survives paths with spaces or non-
+// ASCII characters; the string-concat form fails because `process.argv[1]` is
+// raw while `import.meta.url` is percent-encoded. When this module is loaded
+// via `import` (e.g. from `bundle.js`), `process.argv[1]` may still be set
+// to the importing script, in which case the URLs differ and the CLI block
+// is skipped.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const defaultPlatform = resolve(import.meta.dirname, "..");
+  const defaultPremium = resolve(import.meta.dirname, "..", "..", "premium-plugins");
+  const platformRoot = process.argv[2] ? resolve(process.argv[2]) : defaultPlatform;
+  const premiumRoot = process.argv[3] ? resolve(process.argv[3]) : defaultPremium;
+  const r = runPluginReferenceCheck({ platformRoot, premiumRoot });
+  if (!r.ok) {
+    for (const v of r.violations) {
+      console.error(`[bundle-validator] reference not found`);
+      console.error(`  source: ${v.source}:${v.line}:${v.column}`);
+      console.error(`  cites:  ${v.raw}`);
+      console.error(`  target: ${v.target}`);
+    }
+    console.error(
+      `FATAL: ${r.violations.length} broken reference citation(s) across ${r.scanned} scanned file(s) (${r.citations} citations).`,
+    );
+    process.exit(1);
+  }
+  console.log(
+    `[bundle-validator] plugin references ok scanned=${r.scanned} citations=${r.citations}`,
+  );
+}

package/payload/platform/scripts/setup-account.sh

@@ -44,15 +44,22 @@ mkdir -p "$ACCOUNT_DIR/agents/admin" "$ACCOUNT_DIR/agents/public" "$ACCOUNT_DIR/
 [ -d "$ACCOUNT_DIR/.git" ] || git init -q "$ACCOUNT_DIR"
 
 # ------------------------------------------------------------------
-# 2. Write project-level .claude/settings.json (HOOKS ONLY)
+# 2. Write project-level .claude/settings.json (permissions + hooks)
 # ------------------------------------------------------------------
-# Task 453: no `permissions.allow` block. The previous short-prefix
-# allowlist (mcp__memory__*, mcp__contacts__*, …) never matched the
-# plugin-manifest long-prefix tool names Claude Code actually emits
-# (mcp__plugin_memory_memory__…), so every Task-subagent plugin call
-# was denied at use-time. Permission enforcement comes from each agent's
-# frontmatter `tools:` list (native CC permission surface) and from the
-# PreToolUse approval hooks below for review-gated tools.
+# Task 453 removed `permissions.allow` because its short-prefix entries
+# (mcp__memory__*, mcp__contacts__*, …) never matched the plugin-manifest
+# long-prefix tool names Claude Code actually emits (mcp__plugin_memory_memory__…),
+# so every Task-subagent plugin call was denied at use-time.
+#
+# Task 583 reinstates a `permissions` block — but as wildcard
+# `allow: ["*"]` plus `defaultMode: "bypassPermissions"`. The wildcard
+# bypasses the prefix-matching defect Task 453 was avoiding (a list of one
+# entry that matches everything cannot mismatch), and `bypassPermissions`
+# short-circuits Stage 1 of the local matcher so claude.ai/code sessions
+# never fall through to the Anthropic remote auto-classifier (which routes
+# Agent dispatch to `ask` and surfaces a permission prompt no unattended
+# operator clicks). Per-agent frontmatter `tools:` lists remain the
+# permission surface for what each subagent is allowed to invoke.
 #
 # Hook commands use $PLATFORM_ROOT (set by claude-agent.ts at spawn time)
 # to locate scripts relative to the platform installation, not the account dir.
@@ -61,6 +68,11 @@ HOOKS_PATH="\$PLATFORM_ROOT/plugins/admin/hooks"
 WRITER_CRAFT_HOOKS_PATH="\$PLATFORM_ROOT/../premium-plugins/writer-craft/hooks"
 cat > "$ACCOUNT_SETTINGS" << SETTINGS_EOF
 {
+  "permissions": {
+    "defaultMode": "bypassPermissions",
+    "allow": ["*"],
+    "deny": []
+  },
   "hooks": {
     "PreToolUse": [
       {

package/payload/platform/templates/specialists/agents/personal-assistant.md

@@ -23,7 +23,7 @@ These three rules win when anything else in this prompt conflicts with them.
 Each domain has a small set of tools and, where it exists, a skill that drives the multi-step flow. Match the brief to the domain, load the skill if one is named, and run the tools the skill prescribes.
 
 - **WhatsApp setup or config:** **After routing, the first tool call MUST be `Skill connect-whatsapp` (for QR pairing and admin-phone setup) or `Skill manage-whatsapp-config` (for DM/group policies). Any channel tool call before the routed skill's content is loaded into context is a contract violation.** Load `skill-load skillName=connect-whatsapp` for QR pairing and admin-phone setup; load `skill-load skillName=manage-whatsapp-config` for DM/group policies and admin-phone management. The skills carry the per-phase flow.
-- **Cloudflare tunnel:** **After routing, the first tool call MUST be `Skill setup-tunnel`. Any Bash call before the skill content is loaded into context is a contract violation.** Load `skill-load skillName=setup-tunnel`. The skill drives `cloudflared` directly via Bash following `references/manual-setup.md`, `references/reset-guide.md`, and `references/dashboard-guide.md`. There is no shell-script wrapper; PTY stdout is the only surface.
+- **Cloudflare tunnel:** **After routing, the first tool call MUST be `Skill setup-tunnel`. Any Bash call before the skill content is loaded into context is a contract violation.** Load `skill-load skillName=setup-tunnel`. The skill drives `cloudflared` directly via Bash following `plugins/cloudflare/references/manual-setup.md`, `plugins/cloudflare/references/reset-guide.md`, and `plugins/cloudflare/references/dashboard-guide.md`. There is no shell-script wrapper; PTY stdout is the only surface.
 - **Every other domain** (scheduling, Telegram, email, Outlook, contacts, browser, platform admin) runs through the tool descriptions injected into your system prompt. The rules below apply across these domains regardless of which tool is invoked.
 
 ## Cross-domain rules

package/payload/premium-plugins/teaching/PLUGIN.md

@@ -49,10 +49,10 @@ Domain knowledge files loaded on demand by each skill:
 
 | Reference | Used By | Purpose |
 |-----------|---------|---------|
-| `references/assessment.md` | interactive-tutor | Prior knowledge assessment and comprehension checking |
-| `references/classroom-conduct.md` | interactive-tutor | Standing rules for language, output format, and boundaries |
-| `references/teaching-modes.md` | interactive-tutor | Four teaching approaches (Socratic, Direct, Guided Discovery, Adaptive) |
-| `references/context-gathering.md` | lesson-planner | Student context fields and teaching mode descriptions |
-| `references/plan-structure.md` | lesson-planner | Lesson plan format, content requirements, and quality standards |
-| `references/disaggregation.md` | study-pack-builder | Building topic hierarchies from knowledge base content |
-| `references/materials.md` | study-pack-builder | Per-topic revision material generation (summaries, flashcards, assessments) |
+| `skills/interactive-tutor/references/assessment.md` | interactive-tutor | Prior knowledge assessment and comprehension checking |
+| `skills/interactive-tutor/references/classroom-conduct.md` | interactive-tutor | Standing rules for language, output format, and boundaries |
+| `skills/interactive-tutor/references/teaching-modes.md` | interactive-tutor | Four teaching approaches (Socratic, Direct, Guided Discovery, Adaptive) |
+| `skills/lesson-planner/references/context-gathering.md` | lesson-planner | Student context fields and teaching mode descriptions |
+| `skills/lesson-planner/references/plan-structure.md` | lesson-planner | Lesson plan format, content requirements, and quality standards |
+| `skills/study-pack-builder/references/disaggregation.md` | study-pack-builder | Building topic hierarchies from knowledge base content |
+| `skills/study-pack-builder/references/materials.md` | study-pack-builder | Per-topic revision material generation (summaries, flashcards, assessments) |

package/payload/premium-plugins/venture-studio/skills/brand-pack/SKILL.md

@@ -82,7 +82,7 @@ Select a font stack with clear hierarchy:
 - UI/Caption: Small text, labels, captions
 - Accent: Optional — a contrasting typeface for pull quotes or callouts
 
-Read `references/typography-reference.md` for proven pairings, size scales, and font personality guidance before making recommendations.
+Recommend proven font pairings, size scales, and font personalities that match the brand's voice and audience before making recommendations.
 
 **Rules to follow:**
 - Recommend Google Fonts or Adobe Fonts (free/accessible)

package/payload/platform/plugins/admin/__tests__/admin-can-enumerate.test.sh

@@ -1,129 +0,0 @@
-#!/usr/bin/env bash
-# admin-can-enumerate.test.sh
-#
-# Acceptance gate for Task 579. Verifies that a fresh admin session
-# locates a file under <accountDir>/sites/ on the FIRST enumeration
-# attempt — no slug guessing, no `EISDIR`, no false-empty 200s, no
-# "Log directory does not exist" against a path that resolves
-# elsewhere. The gate runs from the installer post-install step against
-# the freshly-deployed payload, before systemd services are restarted
-# into it. A non-zero exit aborts the deploy and the old payload keeps
-# running.
-#
-# Required environment:
-#   CLAUDE_CONFIG_DIR   per-brand .claude directory (e.g. ~/.realagent-code/.claude)
-#   INSTALL_DIR         the brand install root (e.g. ~/realagent-code)
-#
-# Exit codes:
-#   0  pass — admin enumerated and emitted the seeded path within budget
-#   1  fail — one or more assertions tripped (see stderr for the line)
-#   2  setup error — could not seed test account or could not invoke claude
-
-set -euo pipefail
-
-CONFIG_DIR="${CLAUDE_CONFIG_DIR:?CLAUDE_CONFIG_DIR not set}"
-INSTALL_DIR="${INSTALL_DIR:?INSTALL_DIR not set}"
-
-if ! command -v claude >/dev/null 2>&1; then
-  echo "[admin-enumerate-gate] setup-error reason=claude-not-on-path" >&2
-  exit 2
-fi
-if ! command -v jq >/dev/null 2>&1; then
-  echo "[admin-enumerate-gate] setup-error reason=jq-not-on-path" >&2
-  exit 2
-fi
-
-ACCOUNTS_DIR="$INSTALL_DIR/data/accounts"
-TEST_ACCT_ID="enumerate-gate-$$"
-TEST_ACCT_DIR="$ACCOUNTS_DIR/$TEST_ACCT_ID"
-JSONL_OUT=$(mktemp)
-EXIT=0
-
-cleanup() {
-  rm -rf "$TEST_ACCT_DIR"
-  if [ "$EXIT" -eq 0 ]; then
-    rm -f "$JSONL_OUT"
-  else
-    echo "[admin-enumerate-gate] evidence-jsonl=$JSONL_OUT" >&2
-  fi
-}
-trap cleanup EXIT
-
-# Seed: one target site + 5 decoys. Target index.html is the file the
-# agent must locate and emit the absolute path for.
-mkdir -p "$TEST_ACCT_DIR/sites/exp-uk-got-talent"
-echo "<html><body>eXp Has Got Talent</body></html>" > "$TEST_ACCT_DIR/sites/exp-uk-got-talent/index.html"
-for decoy in alpha-corp-careers beta-properties gamma-events delta-news epsilon-portal; do
-  mkdir -p "$TEST_ACCT_DIR/sites/$decoy"
-  echo "<html>decoy</html>" > "$TEST_ACCT_DIR/sites/$decoy/index.html"
-done
-
-TARGET_PATH="$TEST_ACCT_DIR/sites/exp-uk-got-talent/index.html"
-
-PROMPT="find the eXp Has Got Talent site in this account and print the absolute path to its index.html"
-
-# Spawn claude headless against the test account. ACCOUNT_ID + the
-# MAXY_SESSION_ROLE/PLATFORM_ROOT env are what the platform MCPs read
-# to scope themselves; PLATFORM_ROOT resolves the on-disk payload that
-# was just deployed. JSONL goes to a file we parse below.
-ACCOUNT_ID="$TEST_ACCT_ID" \
-MAXY_SESSION_ROLE="admin" \
-PLATFORM_ROOT="$INSTALL_DIR/platform" \
-CLAUDE_CONFIG_DIR="$CONFIG_DIR" \
-  claude -p "$PROMPT" --output-format=stream-json --verbose \
-    > "$JSONL_OUT" 2>&1 \
-  || { echo "[admin-enumerate-gate] setup-error reason=claude-spawn-failed exit=$?" >&2; EXIT=2; exit 2; }
-
-fail() {
-  echo "[admin-enumerate-gate] FAIL $1" >&2
-  EXIT=1
-}
-
-# Assertion 1: the target path appears verbatim in some assistant turn
-# or tool-use input. Either as the agent's final message or as an arg
-# passed to a tool.
-if ! grep -F -q "$TARGET_PATH" "$JSONL_OUT"; then
-  fail "correct-path-not-emitted target=$TARGET_PATH"
-fi
-
-# Assertion 2: zero forbidden error patterns from the surfaces this
-# task fixed.
-FORBIDDEN_HITS=$(grep -E -c "EISDIR|Log directory does not exist|Plugin file not found|page has no readable text content" "$JSONL_OUT" || true)
-if [ "${FORBIDDEN_HITS:-0}" -gt 0 ]; then
-  fail "forbidden-error-patterns=$FORBIDDEN_HITS"
-fi
-
-# Assertion 3: total tool-use calls from the user prompt to the
-# correct-path emission are at most 3. The earlier failing run issued
-# ~15.
-TOOL_USE_COUNT=$(jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use") | .name' < "$JSONL_OUT" 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-if [ "${TOOL_USE_COUNT:-0}" -gt 3 ]; then
-  fail "tool-use-budget-exceeded count=$TOOL_USE_COUNT cap=3"
-fi
-
-# Assertion 4: the FIRST disk-listing tool call returns an enumeration
-# of <accountDir>/sites/. "Disk-listing" means LS, Glob, or Bash with
-# `ls`. We accept any of those as the first relevant call; what we
-# reject is a Read against a directory path.
-FIRST_DIR_TOOL=$(jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use") | {name, input} | @json' < "$JSONL_OUT" 2>/dev/null \
-  | jq -r 'select(.name=="LS" or .name=="Glob" or (.name=="Bash" and (.input.command // "" | test("\\bls\\b")))) | .name' \
-  | head -1)
-if [ -z "$FIRST_DIR_TOOL" ]; then
-  fail "no-disk-listing-tool-call-emitted"
-fi
-
-# Assertion 5: no Read tool call against a path under <accountDir>/sites/
-# that is a directory (would have produced EISDIR pre-fix; should not
-# even be attempted now).
-BAD_READ=$(jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="Read") | .input.file_path // ""' < "$JSONL_OUT" 2>/dev/null \
-  | while read -r p; do
-      [ -n "$p" ] && [ -d "$p" ] && echo "$p"
-    done | head -1)
-if [ -n "$BAD_READ" ]; then
-  fail "read-against-directory path=$BAD_READ"
-fi
-
-if [ "$EXIT" -eq 0 ]; then
-  echo "[admin-enumerate-gate] PASS target=$TARGET_PATH tool-use-count=$TOOL_USE_COUNT first-dir-tool=$FIRST_DIR_TOOL"
-fi
-exit "$EXIT"