@rubytech/create-maxy-code 0.1.223 → 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";
@@ -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...");

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.223",
+  "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)