@rubytech/create-maxy-code 0.1.112 → 0.1.114

package/dist/__tests__/brew-install.test.js

@@ -73,9 +73,14 @@ test("decideBrewInstallPlan: all pkgs already installed → empty install list,
         ],
     });
     assert.deepEqual(plan.toInstall, []);
+    // Each pkg emits the legacy `[homebrew]` line plus the uniform-prefix
+    // `[create-maxy] brew-formula=… action=…` mirror Task 297 added for the
+    // grep recipe.
     assert.deepEqual(plan.logs, [
         "  [homebrew] node@22 already installed (v22.18.1)",
+        "  [create-maxy] brew-formula=node@22 action=present",
         "  [homebrew] neo4j already installed (v5.20.0)",
+        "  [create-maxy] brew-formula=neo4j action=present",
     ]);
 });
 test("decideBrewInstallPlan: some missing → install list contains only missing formulas, install + already logs interleaved", () => {
@@ -89,8 +94,11 @@ test("decideBrewInstallPlan: some missing → install list contains only missing
     assert.deepEqual(plan.toInstall, ["neo4j", "cloudflared"]);
     assert.deepEqual(plan.logs, [
         "  [homebrew] node@22 already installed (v22.18.1)",
+        "  [create-maxy] brew-formula=node@22 action=present",
         "  [homebrew] installing neo4j …",
+        "  [create-maxy] brew-formula=neo4j action=install",
         "  [homebrew] installing cloudflared …",
+        "  [create-maxy] brew-formula=cloudflared action=install",
     ]);
 });
 test("decideBrewInstallPlan: all missing → install list = every formula, only install logs", () => {
@@ -103,7 +111,9 @@ test("decideBrewInstallPlan: all missing → install list = every formula, only
     assert.deepEqual(plan.toInstall, ["node@22", "neo4j"]);
     assert.deepEqual(plan.logs, [
         "  [homebrew] installing node@22 …",
+        "  [create-maxy] brew-formula=node@22 action=install",
         "  [homebrew] installing neo4j …",
+        "  [create-maxy] brew-formula=neo4j action=install",
     ]);
 });
 // ---------------------------------------------------------------------------

package/dist/__tests__/brew-resolve.test.js

@@ -101,3 +101,38 @@ test("DARWIN_ALIASES contains nodejs → node@22 and is the only entry", () => {
     assert.equal(DARWIN_ALIASES.nodejs, "node@22");
     assert.equal(Object.keys(DARWIN_ALIASES).length, 1);
 });
+// ---------------------------------------------------------------------------
+// DARWIN_BASE_DEPS + neo4j shape lock — every brew dep the darwin install
+// branch feeds into installAllBrewPackages must either (a) be a real Homebrew
+// core formula already, or (b) resolve to one via DARWIN_ALIASES. The list is
+// duplicated here from index.ts:installSystemDeps so a future edit of either
+// surface has to keep them in sync.
+// ---------------------------------------------------------------------------
+// Mirrors `DARWIN_BASE_DEPS` in packages/create-maxy-code/src/index.ts. Every
+// entry must be either a real brew formula (pass-through) or an alias.
+const DARWIN_BASE_DEPS_FIXTURE = ["curl", "git", "unzip", "jq", "poppler", "ffmpeg"];
+// `neo4j` and `cloudflared` are passed to installAllBrewPackages from
+// installNeo4j (index.ts:1265) and installCloudflared (index.ts:1728). Both are
+// concrete brew formula names — no alias hop expected.
+const DARWIN_SOLO_DEPS_FIXTURE = ["neo4j", "cloudflared"];
+test("every DARWIN_BASE_DEPS entry passes through the resolver as the brew formula name", () => {
+    for (const pkg of DARWIN_BASE_DEPS_FIXTURE) {
+        const r = decideBrewResolution({ pkg, brewInstalled: false });
+        assert.equal(r.resolved, pkg, `DARWIN_BASE_DEPS entry '${pkg}' must not be aliased`);
+        assert.equal(r.log, null, `DARWIN_BASE_DEPS entry '${pkg}' must not emit an alias log line`);
+    }
+});
+test("neo4j and cloudflared pass through unchanged — no alias hop", () => {
+    for (const pkg of DARWIN_SOLO_DEPS_FIXTURE) {
+        const r = decideBrewResolution({ pkg, brewInstalled: false });
+        assert.equal(r.resolved, pkg);
+        assert.equal(r.log, null);
+    }
+});
+test("nodejs alias hop resolves to node@22 for darwin install", () => {
+    // The shared-dep call site (index.ts:988 installNodejs) passes "nodejs";
+    // this test pins the brew-formula landing for that single alias.
+    const r = decideBrewResolution({ pkg: "nodejs", brewInstalled: false });
+    assert.equal(r.resolved, "node@22");
+    assert.match(r.log ?? "", /node@22/);
+});

package/dist/__tests__/launchd-plist.test.js

@@ -128,6 +128,52 @@ test("renderPlist escapes `&` once, never double-escapes", () => {
 // child to "" (current dir = launchd's cwd, /), which silently changes
 // behaviour from "stay where invoked" to "/" — a different bug than absence.
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Brand-stamped labels — both shipping brands must render distinct labels so a
+// co-resident install does not collide on a single LaunchAgent file.
+// `launchdLabel()` in index.ts returns `com.rubytech.${BRAND.hostname}`; this
+// test pins the brand-input → label contract end-to-end against the renderer.
+// ---------------------------------------------------------------------------
+test("renderPlist maxy-code brand fields land in the plist verbatim", () => {
+    // BRAND.hostname=maxy-code, configDir=.maxy-code per brands/maxy-code/brand.json.
+    // installServiceDarwin builds ProgramArguments=["/bin/bash", wrapperPath],
+    // WorkingDirectory=`${INSTALL_DIR}/server`, std{out,err}Path=`<logsDir>/server.log`.
+    const xml = renderPlist({
+        label: "com.rubytech.maxy-code",
+        programArguments: ["/bin/bash", "/Users/alice/.maxy-code/launchd-wrapper.sh"],
+        stdoutPath: "/Users/alice/.maxy-code/logs/server.log",
+        stderrPath: "/Users/alice/.maxy-code/logs/server.log",
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: "/Users/alice/maxy-code/server",
+    });
+    assert.match(xml, /<key>Label<\/key>\s*<string>com\.rubytech\.maxy-code<\/string>/);
+    assert.match(xml, /<string>\/bin\/bash<\/string>/);
+    assert.match(xml, /<string>\/Users\/alice\/\.maxy-code\/launchd-wrapper\.sh<\/string>/);
+    assert.match(xml, /<key>WorkingDirectory<\/key>\s*<string>\/Users\/alice\/maxy-code\/server<\/string>/);
+    assert.match(xml, /<key>StandardOutPath<\/key>\s*<string>\/Users\/alice\/\.maxy-code\/logs\/server\.log<\/string>/);
+    assert.match(xml, /<key>KeepAlive<\/key>\s*<true\/>/);
+    assert.match(xml, /<key>RunAtLoad<\/key>\s*<true\/>/);
+});
+test("renderPlist realagent-code brand fields land in the plist verbatim", () => {
+    // BRAND.hostname=realagent-code, configDir=.realagent-code per brands/realagent-code/brand.json.
+    // The label must differ from the maxy-code label so a co-resident install
+    // produces two distinct ~/Library/LaunchAgents/<label>.plist files.
+    const xml = renderPlist({
+        label: "com.rubytech.realagent-code",
+        programArguments: ["/bin/bash", "/Users/alice/.realagent-code/launchd-wrapper.sh"],
+        stdoutPath: "/Users/alice/.realagent-code/logs/server.log",
+        stderrPath: "/Users/alice/.realagent-code/logs/server.log",
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: "/Users/alice/realagent-code/server",
+    });
+    assert.match(xml, /<key>Label<\/key>\s*<string>com\.rubytech\.realagent-code<\/string>/);
+    assert.match(xml, /<string>\/Users\/alice\/\.realagent-code\/launchd-wrapper\.sh<\/string>/);
+    assert.match(xml, /<key>WorkingDirectory<\/key>\s*<string>\/Users\/alice\/realagent-code\/server<\/string>/);
+    // Label collision guard — the maxy-code label must not appear in a realagent plist.
+    assert.ok(!/com\.rubytech\.maxy-code/.test(xml), "realagent plist must not carry maxy-code label");
+});
 test("renderPlist omits WorkingDirectory key when workingDirectory is absent", () => {
     const xml = renderPlist({
         label: "com.rubytech.maxy",

package/dist/__tests__/macos-darwin-branch.test.js

@@ -0,0 +1,85 @@
+// Static-grep contract for the darwin install branches in index.ts.
+//
+// Task 297 audited every `platform === "darwin"` block; this test pins the
+// shape so a future refactor that removes a darwin branch without an explicit
+// reason fails loudly here. The test reads src/index.ts at runtime (the
+// authoritative source) and regex-asserts the per-branch markers — keeping
+// the spec adjacent to the code rather than buried in a doc.
+//
+// Why static-grep, not behaviour: the install branches each spawn (sudo,
+// brew, launchctl), and end-to-end darwin reproduction belongs to the manual
+// smoke path in the task brief. The unit suite's job is to ensure the
+// branch points still exist after a refactor.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+// dist/__tests__/macos-darwin-branch.test.js → ../../src/index.ts
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = resolve(here, "../../src/index.ts");
+const SRC = readFileSync(INDEX_TS, "utf-8");
+test("installSystemDeps has darwin branch that calls setMacosHostnameViaScutil on --hostname and scutil --get LocalHostName without", () => {
+    // The hostname block at index.ts:installSystemDeps must:
+    //   - call setMacosHostnameViaScutil(HOSTNAME_FLAG) when HOSTNAME_FLAG is set
+    //   - call scutil --get LocalHostName when HOSTNAME_FLAG is absent
+    // The two paths are the contract Task 297 locks in.
+    assert.match(SRC, /setMacosHostnameViaScutil\(HOSTNAME_FLAG\)/, "scutil-set path on --hostname must call setMacosHostnameViaScutil");
+    assert.match(SRC, /scutil["']?,\s*\[["']--get["']\s*,\s*["']LocalHostName["']\]/, "scutil --get LocalHostName must be the no-flag default on darwin");
+    assert.match(SRC, /darwin-hostname-mode=scutil-get/, "scutil-get success path must emit observability log");
+    assert.match(SRC, /darwin-hostname-mode=scutil-set/, "scutil-set path must emit observability log");
+    assert.match(SRC, /darwin-hostname-mode=brand-fallback/, "brand-fallback path must emit observability log");
+});
+test("installSystemDeps darwin branch installs DARWIN_BASE_DEPS via brew", () => {
+    // The shared dep set the darwin path feeds to installAllBrewPackages. If
+    // this list shrinks or a name changes, brew-resolve.test.ts (DARWIN_BASE_DEPS_FIXTURE)
+    // must move in lockstep — the comment in brew-resolve.test.ts says so.
+    assert.match(SRC, /DARWIN_BASE_DEPS\s*=\s*\[\s*"curl"\s*,\s*"git"\s*,\s*"unzip"\s*,\s*"jq"\s*,\s*"poppler"\s*,\s*"ffmpeg"\s*\]/);
+    assert.match(SRC, /installAllBrewPackages\(DARWIN_BASE_DEPS,\s*logFile\)/);
+});
+test("installCloudflared darwin branch logs the documented skip and brew-installs cloudflared", () => {
+    // Task 297 doctrine: skip tunnel provisioning entirely on darwin. The brew
+    // install puts the binary on PATH so the operator can opt in to `cloudflared
+    // tunnel login` post-install; the explicit log line is the diagnostic
+    // anchor for investigators grepping the install log.
+    assert.match(SRC, /darwin-cloudflare-skip=true/);
+    assert.match(SRC, /installAllBrewPackages\(\["cloudflared"\],\s*logFile\)/);
+    // No `cloudflared service install` or `cloudflared tunnel route dns`
+    // invocation in the installer surface — those are operator-driven,
+    // post-install steps. Match actual argv shapes (string-literal list to
+    // spawnSync/shell) rather than prose: argv arrays carry the args as
+    // quoted siblings inside `[...]`. Comment text is filtered by requiring
+    // a quote character immediately adjacent.
+    assert.ok(!/\[\s*["']cloudflared["'][^\]]*["']service["'][^\]]*["']install["']/.test(SRC), "installer must not invoke `cloudflared service install`");
+    assert.ok(!/\[\s*["']cloudflared["'][^\]]*["']tunnel["'][^\]]*["']route["'][^\]]*["']dns["']/.test(SRC), "installer must not invoke `cloudflared tunnel route dns`");
+});
+test("installService darwin branch delegates to installServiceDarwin (launchd path, not systemd)", () => {
+    // Two contracts: the platform switch routes darwin to installServiceDarwin,
+    // and installServiceDarwin writes the plist + bootstraps it via launchctl.
+    assert.match(SRC, /platform\s*===\s*"darwin"\s*\)\s*\{\s*installServiceDarwin\(\)/);
+    assert.match(SRC, /launchctl["']?,\s*\[["']bootstrap["']/);
+    assert.match(SRC, /launchd-plist=\$\{path\}\s+loaded=true/, "successful bootstrap must emit launchd-plist=…  loaded=true");
+    assert.match(SRC, /launchd-plist=\$\{path\}\s+loaded=false/, "failed bootstrap must emit launchd-plist=…  loaded=false");
+});
+test("installNodejs darwin branch brew-installs the `nodejs` alias name (resolver hops to node@22)", () => {
+    // The shared call site uses the apt-style `nodejs` name. brew-resolve.ts
+    // hops it to `node@22` via DARWIN_ALIASES — the alias is the deliberate
+    // wedge so a single dep name works across both backends.
+    assert.match(SRC, /platform\s*===\s*"darwin"[\s\S]{0,400}installAllBrewPackages\(\["nodejs"\]/);
+});
+test("installNeo4j darwin branch brew-installs `neo4j` (no alias hop)", () => {
+    // `neo4j` is the concrete brew formula name on darwin, no alias needed.
+    assert.match(SRC, /platform\s*===\s*"darwin"[\s\S]{0,800}installAllBrewPackages\(\["neo4j"\]/);
+});
+test("chromium binary-path file write skips darwin (Playwright-managed)", () => {
+    // writeChromiumBinaryPathFile early-returns on non-linux. The completion URL
+    // and VNC stack on darwin use Playwright/brew-managed Chromium instead of
+    // the linux per-brand chromium-binary.path file.
+    assert.match(SRC, /writeChromiumBinaryPathFile[\s\S]{0,200}process\.platform\s*!==\s*"linux"/);
+});
+test("uninstall darwin path bootsout the LaunchAgent and removes the plist", () => {
+    // The uninstall surface lives in uninstall.ts (separate file); this index.ts
+    // sanity check just confirms the launchdLabel helper still exists and is
+    // brand-keyed — install + uninstall both depend on the same label shape.
+    assert.match(SRC, /function launchdLabel\(\):\s*string\s*\{\s*return\s*`com\.rubytech\.\$\{BRAND\.hostname\}`/);
+});

package/dist/brew-install.js

@@ -71,9 +71,14 @@ export function decideBrewInstallPlan(input) {
         if (p.installed) {
             const head = p.versions[0] ?? "?";
             logs.push(`  [homebrew] ${p.resolvedFormula} already installed (v${head})`);
+            // Uniform-prefix mirror line so the install-log grep recipe in
+            // platform/plugins/docs/references/deployment.md (`grep -E '^\[create-maxy\] …'`)
+            // covers every brew step alongside platform=, darwin-hostname-mode=, etc.
+            logs.push(`  [create-maxy] brew-formula=${p.resolvedFormula} action=present`);
         }
         else {
             logs.push(`  [homebrew] installing ${p.resolvedFormula} …`);
+            logs.push(`  [create-maxy] brew-formula=${p.resolvedFormula} action=install`);
             toInstall.push(p.resolvedFormula);
         }
     }

package/dist/index.js

@@ -614,6 +614,7 @@ function installSystemDeps() {
         // otherwise preserve the existing system hostname.
         if (HOSTNAME_FLAG) {
             console.log(`  Hostname: ${HOSTNAME_FLAG} (from --hostname flag)`);
+            logFile(`  [create-maxy] darwin-hostname-mode=scutil-set value=${HOSTNAME_FLAG}`);
             try {
                 setMacosHostnameViaScutil(HOSTNAME_FLAG);
                 DEVICE_HOSTNAME = HOSTNAME_FLAG;
@@ -623,11 +624,25 @@ function installSystemDeps() {
             }
         }
         else {
-            try {
-                DEVICE_HOSTNAME = execFileSync("hostname", [], { encoding: "utf-8" }).trim();
-                console.log(`  Hostname: ${DEVICE_HOSTNAME} (preserved — no --hostname flag on darwin)`);
+            // No flag — read the live LocalHostName so the printed URL matches mDNS
+            // resolution (`<LocalHostName>.local`). The `hostname` command on darwin
+            // returns the fully-qualified `<name>.local`, which would render the
+            // completion URL with a double `.local` suffix; scutil --get returns the
+            // bare token. No sudo, no system mutation.
+            const scutilGet = spawnSync("scutil", ["--get", "LocalHostName"], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+            const scutilName = ((scutilGet.stdout ?? "").trim());
+            if (scutilGet.status === 0 && scutilName.length > 0) {
+                DEVICE_HOSTNAME = scutilName;
+                console.log(`  Hostname: ${DEVICE_HOSTNAME} (from scutil --get LocalHostName — no --hostname flag)`);
+                logFile(`  [create-maxy] darwin-hostname-mode=scutil-get value=${DEVICE_HOSTNAME}`);
+            }
+            else {
+                // scutil failed or returned empty — fall back to BRAND.hostname so the
+                // completion URL at least matches the brand's documented .local name.
+                DEVICE_HOSTNAME = BRAND.hostname;
+                console.log(`  Hostname: ${DEVICE_HOSTNAME} (brand fallback — scutil --get LocalHostName empty)`);
+                logFile(`  [create-maxy] darwin-hostname-mode=brand-fallback value=${DEVICE_HOSTNAME} scutil-status=${scutilGet.status}`);
             }
-            catch { /* fallback to brand — set at declaration */ }
         }
         // macOS has no apt analogue for the VNC/WiFi-AP stacks
         // (kiosk display + hostapd/dnsmasq are Pi-specific's
@@ -1541,8 +1556,11 @@ function installCloudflared() {
     if (platform === "darwin") {
         // Homebrew's `cloudflared` formula tracks the Cloudflare release stream;
         // tunnel-login flow stays unchanged (`feedback_no_api_token_route.md`).
-        // `cloudflared service install` is invoked by the launchd supervisor in
-        // out of scope here.
+        // `cloudflared service install` and `cloudflared tunnel route dns` are not
+        // invoked by the installer on darwin — public reach is operator-driven
+        // post-install (`cloudflared tunnel login` + follow-up tooling). The brew
+        // install puts the binary on PATH so the operator can opt in later.
+        logFile(`  [create-maxy] darwin-cloudflare-skip=true reason="Mac laptop — no public hostname provisioned at install time"`);
         installAllBrewPackages(["cloudflared"], logFile);
         return;
     }
@@ -2592,11 +2610,13 @@ function installServiceDarwin() {
     if (bootstrap.status === 0) {
         console.log(`  [launchd] bootstrap ${gui()}/${label} ok`);
         logFile(`  [launchd] bootstrap ${gui()}/${label} ok`);
+        logFile(`  [create-maxy] launchd-plist=${path} loaded=true`);
     }
     else {
         const stderr = (bootstrap.stderr ?? "").trim();
         console.error(`  [launchd] bootstrap returned ${bootstrap.status}: ${stderr}`);
         logFile(`  [launchd] bootstrap returned ${bootstrap.status}: ${stderr}`);
+        logFile(`  [create-maxy] launchd-plist=${path} loaded=false exit=${bootstrap.status}`);
         throw new Error(`launchctl bootstrap ${gui()} ${path} failed (exit ${bootstrap.status}): ${stderr}`);
     }
     // Wait for the server to come up.

package/package.json

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

package/payload/platform/neo4j/schema.cypher

@@ -792,8 +792,13 @@ FOR (ag:AccessGrant) ON (ag.status);
 //   displayName       — operator-facing name from config.json
 //   status            — 'active' | 'inactive' | <other> per config.json
 //   model             — Anthropic model id used by the public agent
-//   liveMemory        — bool; whether memory-search runs at message time
-//   knowledgeKeywords — string[] (live-search keyword subscriptions)
+//   liveMemory        — bool; when true, the public PTY spawn includes
+//                       memory-search in --allowed-tools so the agent can
+//                       hit the graph at message time (scoped via
+//                       ALLOWED_SCOPES=public). When false, the agent
+//                       runs with only its baked KNOWLEDGE.md.
+//   knowledgeKeywords — string[] used by update-knowledge to broaden the
+//                       refresh query alongside operator-tagged nodes
 //   role              — always 'agent' (mirrors KnowledgeDocument.role
 //                       discriminator; surfaces in BM25 hits)
 //   createdAt         — ISO 8601, set on first projection

package/payload/platform/plugins/admin/skills/public-agent-manager/SKILL.md

@@ -41,13 +41,13 @@ Each agent lives at `{accountDir}/agents/{slug}/`:
 
 ### liveMemory
 
-When `true`, the platform queries the knowledge graph at runtime per message and appends live results alongside baked KNOWLEDGE.md. When `false` (default), the agent uses only the static KNOWLEDGE.md snapshot.
+Controls whether the public agent gets `memory-search` at message time. When `true`, the per-spawn `--allowed-tools` allowlist includes `memory-search` so the agent can hit the graph during a turn — scoped to `scope: "public"` nodes via `ALLOWED_SCOPES=public` on the spawn env. When `false` (default), the agent runs with only the baked KNOWLEDGE.md and has no graph access mid-conversation.
 
-Present during creation and editing as a yes/no choice. Explain the trade-off: live memory adds a small latency per message (~1-2s) but keeps the agent current with graph changes. For agents with static knowledge (pricing, FAQs), leave off. For agents that need to reflect recent graph updates (dynamic catalogues, changing availability), enable it.
+Present during creation and editing as a yes/no choice. Explain the trade-off: live memory adds a small latency per turn when the agent decides to search but keeps the agent current with graph changes (new listings, fresh availability). For agents whose knowledge is fully covered by KNOWLEDGE.md (pricing, FAQs), leave off. For agents that need to surface graph content created after the agent was deployed (catalogue items, schedule slots), enable it.
 
 ### knowledgeKeywords
 
-Topic keywords the agent subscribes to. When the graph is searched for this agent (at runtime via `liveMemory` or during a `update-knowledge` refresh), nodes matching these keywords are included automatically — even if they are not directly tagged for the agent.
+Topic keywords the agent subscribes to. During an `update-knowledge` refresh, nodes matching these keywords are included automatically — even if they are not directly tagged for the agent.
 
 Maximum 5 keywords. Present during creation as a free-text input. Examples: `["climate science", "sustainability"]`, `["pricing", "services"]`.
 
@@ -113,7 +113,14 @@ SOUL.md answers "what does this agent feel like to talk to?" — tone, warmth, f
 
 ## KNOWLEDGE.md Population
 
-KNOWLEDGE.md is the public agent's only source of factual knowledge. Public agents run via the direct Anthropic API with no runtime access to the graph — no `memory-search`, no filesystem, no MCP tools. Once KNOWLEDGE.md exists, the server skips runtime memory-search entirely. Every gap in KNOWLEDGE.md is a question the public agent cannot answer.
+KNOWLEDGE.md is the public agent's baked, static knowledge surface — the facts the agent should always have on hand without a tool call. It is assembled into the system prompt at invocation time.
+
+Public agents run on the same native Claude Code PTY as the admin, dispatched via `dispatchOnce` with `role: 'public'`. The agent's `liveMemory` config toggle decides whether `memory-search` lands in the per-spawn `--allowed-tools` allowlist:
+
+- **`liveMemory: false`** — KNOWLEDGE.md is the agent's only knowledge source. No graph access mid-conversation. Every gap in KNOWLEDGE.md is a question the agent cannot answer.
+- **`liveMemory: true`** — KNOWLEDGE.md remains the baked, evergreen surface, and `memory-search` is also in the allowlist so the agent can hit the graph at message time. The memory MCP server runs with `ALLOWED_SCOPES=public` so only `scope: "public"` nodes come back; anything not marked public is invisible regardless of how the agent queries.
+
+When `liveMemory: true`, treat KNOWLEDGE.md and `memory-search` as complementary, not alternatives. KNOWLEDGE.md owns the agent's evergreen facts (pricing, services, FAQs, contact info). `memory-search` is for the long-tail, public-scoped lookups the agent reaches for during a conversation (a named listing, a specific person, a current availability slot).
 
 All `memory-search` queries for knowledge population use admin permissions — do not pass `agentSlug`. The `agentSlug` parameter is a runtime enforcement mechanism for the public agent's MCP server, not an admin-time discovery tool. At creation time, the agent may have zero tagged nodes — searching with `agentSlug` would return nothing.
 
@@ -175,7 +182,7 @@ After creation, no template metadata persists in the agent's files. The resultin
 5. Present `IDENTITY.md` via document-editor with `filePath: "agents/{slug}/IDENTITY.md"` (draft from role description). Write on approval.
 6. Present `SOUL.md` via document-editor with `filePath: "agents/{slug}/SOUL.md"` (draft personality from user conversation). Write on approval.
 7. Present agent configuration via a single `form` component with these fields:
-   - `liveMemory` (`checkbox`): label "Live memory", description explaining the trade-off — live memory adds ~1-2s latency per message but keeps the agent current with graph changes; leave off for static knowledge (pricing, FAQs), enable for dynamic content
+   - `liveMemory` (`checkbox`): label "Live memory", description explaining the trade-off — when on, the agent can call `memory-search` mid-turn against public-scoped graph content; leave off if KNOWLEDGE.md fully covers the agent's role
    - `knowledgeKeywords` (`text`): label "Knowledge keywords (max 5, comma-separated)", placeholder with examples relevant to the agent's role
    - `model` (`select`): label "Model", options with descriptions:
      - `claude-haiku-4-5` — "Haiku — Fast, cost-effective. FAQ, routing, high-volume."
@@ -265,9 +272,9 @@ The new default takes effect on the next page load. The previous default agent r
 
 Invoke the agent with `[New session. Greet the visitor.]` and stream the response to the admin chat. The admin sees exactly what a visitor would see on first load.
 
-## Self-Contained Constraint
+## Runtime Surface
 
-Public agents run on the same native Claude Code PTY surface as the admin agent. They have no filesystem access, no MCP write tools, no subagents — every tool is on a read-only or otherwise public-safe allowlist that the manager passes to the spawn as `--allowed-tools`. Everything the agent needs to say must come from its directory files or from the public-safe tool surface. The platform assembles directory files into the system prompt at invocation time.
+Public agents run on the same native Claude Code PTY as the admin, dispatched via `dispatchOnce` with `role: 'public'`. They have no filesystem access, no MCP write tools, no subagents — every tool is on a read-only, public-safe allowlist that the manager passes to the spawn as `--allowed-tools`. The agent's `liveMemory` config flag decides whether `memory-search` is in that allowlist; when present, the memory MCP server runs with `ALLOWED_SCOPES=public` so only `scope: "public"` graph nodes are reachable. Everything the agent needs to say comes from its directory files (assembled into the system prompt at invocation time) or from that public-safe tool surface.
 
 ## URL Routing
 

package/payload/platform/plugins/cloudflare/references/manual-setup.md

@@ -468,6 +468,111 @@ Removes the root-level systemd unit, `/etc/cloudflared/config.yml`, and the dupl
 
 ---
 
+## Multi-ingress: adding hostnames for prototype services
+
+Once the brand tunnel is up (admin + public + optionally SSH/SMB), additional service hostnames can be added without re-running the OAuth/cert/create-tunnel steps. This is the pattern the venture-studio `prototype-host` skill uses to expose hosted landing pages and wedge prototypes as `https://<surface>.<BRAND_HOSTNAME>`.
+
+The flow is: append an ingress rule to `${CFG_DIR}/config.yml` immediately before the final `http_status:404` catch-all, validate the YAML, create the DNS row, restart the brand cloudflared service.
+
+### 1. Append the ingress rule (awk, not sed)
+
+`sed` cannot reliably insert before the last multi-line YAML rule. `awk` matches the literal catch-all line and inserts two lines before each match:
+
+```
+SURFACE="<surface>"            # DNS label, e.g. landing or prototype
+PORT="<port>"                  # local port the dev server / file server binds to
+HOSTNAME="${SURFACE}.${BRAND_HOSTNAME}"
+
+# Idempotency — skip if this hostname is already in config.yml.
+if grep -qE "^[[:space:]]*-[[:space:]]+hostname:[[:space:]]+${HOSTNAME}\b" "${CFG_DIR}/config.yml"; then
+  echo "ingress-row-exists hostname=${HOSTNAME}"
+else
+  awk -v host="${HOSTNAME}" -v port="${PORT}" '
+    /^[[:space:]]*-[[:space:]]+service:[[:space:]]+http_status:404[[:space:]]*$/ {
+      print "  - hostname: " host
+      print "    service: http://localhost:" port
+    }
+    { print }
+  ' "${CFG_DIR}/config.yml" > "${CFG_DIR}/config.yml.new"
+  mv "${CFG_DIR}/config.yml.new" "${CFG_DIR}/config.yml"
+fi
+```
+
+After the edit the file looks like:
+
+```yaml
+tunnel: <TUNNEL_ID>
+credentials-file: <CFG_DIR>/<TUNNEL_ID>.json
+ingress:
+  - hostname: admin.<BRAND_HOSTNAME>
+    service: http://localhost:<PORT>
+  - hostname: public.<BRAND_HOSTNAME>
+    service: http://localhost:<PORT>
+  - hostname: <surface>.<BRAND_HOSTNAME>
+    service: http://localhost:<port>
+  - service: http_status:404
+```
+
+### 2. Validate
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" \
+  --config "${CFG_DIR}/config.yml" \
+  tunnel ingress validate
+```
+
+Non-zero exit aborts the flow; cloudflared's stderr is the literal diagnostic.
+
+### 3. Create the DNS row
+
+```
+TUNNEL_ID=$(jq -r '.id // .tunnelId' "${CFG_DIR}/tunnel.state")
+cloudflared --origincert "${CFG_DIR}/cert.pem" \
+  tunnel route dns --overwrite-dns "${TUNNEL_ID}" "${HOSTNAME}"
+```
+
+`--overwrite-dns` replaces any existing CNAME for the hostname (common after a prior install on the same account). Without it, `tunnel route dns` errors `record already exists`.
+
+### 4. Reload the connector
+
+```
+systemctl --user restart "${BRAND}-cloudflared.service"
+```
+
+Cloudflared does not watch `config.yml` for changes (the brand service unit launches it without `--config-watch`). Restart is the deterministic way to pick up the new rule; the brief ~1s connector blip is the same one every cloudflared upgrade incurs.
+
+### Verification
+
+```
+curl -I https://<surface>.<BRAND_HOSTNAME>
+```
+
+Anything other than `HTTP/2 200` (or the dev server's natural 200/304 response) means either the rule didn't land, the systemd unit serving `<port>` isn't running, or DNS hasn't propagated. Run `cloudflared --origincert "${CFG_DIR}/cert.pem" --config "${CFG_DIR}/config.yml" tunnel ingress validate` and `dig <surface>.<BRAND_HOSTNAME>` to isolate which.
+
+### Removing a prototype hostname
+
+Manual for now (no scripted removal — the `prototype-host` skill does not yet ship a remove companion):
+
+```
+# 1. Stop and disable the service unit.
+systemctl --user disable --now "${BRAND}-prototype-<surface>.service"
+
+# 2. Strip the ingress row from config.yml — match the literal hostname line plus the following service line.
+awk -v host="${SURFACE}.${BRAND_HOSTNAME}" '
+  $0 ~ "^[[:space:]]*-[[:space:]]+hostname:[[:space:]]+" host "[[:space:]]*$" { skip = 2; next }
+  skip > 0 { skip--; next }
+  { print }
+' "${CFG_DIR}/config.yml" > "${CFG_DIR}/config.yml.new" && mv "${CFG_DIR}/config.yml.new" "${CFG_DIR}/config.yml"
+
+# 3. Delete the DNS row (dashboard, since the cloudflared CLI has no "route dns remove").
+#    Cloudflare → DNS → <zone> → delete CNAME for <surface>.<BRAND_HOSTNAME>.
+
+# 4. Restart cloudflared.
+systemctl --user restart "${BRAND}-cloudflared.service"
+```
+
+---
+
 ## Full reset
 
 If everything is in a bad state and you want to start over. Assumes Step 0 has been run so `${BRAND}` and `${CFG_DIR}` are set.

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

@@ -9,15 +9,33 @@
 
 ## macOS install
 
-On macOS the installer uses Homebrew + launchd instead of apt + systemd, but the operator command is the same:
+On macOS the installer uses Homebrew + launchd instead of apt + systemd. No flags are required on a laptop:
 
 ```bash
-npx -y @rubytech/create-maxy
+npx -y @rubytech/create-maxy-code            # default brand
+npx -y @rubytech/create-realagent-code       # realagent brand
 ```
 
-**Prerequisite:** Homebrew. If `brew` is missing, the installer refuses with `Homebrew not found. Install from https://brew.sh and re-run.` Install Homebrew once via the official one-liner, then re-run.
+**Prerequisite:** Homebrew. If `brew` is missing, the installer refuses with `Homebrew not found. Install from https://brew.sh and re-run.` Install Homebrew once via the official one-liner, then re-run. The installer never installs Homebrew itself.
+
+**Hostname / printed URL.** Without `--hostname`, the installer reads `scutil --get LocalHostName` and prints the completion URL as `http://<that-name>.local:<port>`. No sudo, no system change — your Mac's existing local network name is what mDNS will resolve. With `--hostname <h>`, the installer sets `HostName` / `LocalHostName` / `ComputerName` to `<h>` via `sudo scutil` (one password prompt, all-or-nothing rollback within the three-call batch) so the URL becomes `http://<h>.local:<port>`. Grep `~/.<brand>/logs/install-*.log` for `[create-maxy] darwin-hostname-mode=` to confirm which path ran (`scutil-get`, `scutil-set`, or `brand-fallback`).
+
+**LaunchAgent.** The installer registers `{{productName}}` as a launchd LaunchAgent at `~/Library/LaunchAgents/com.rubytech.<brand-hostname>.plist` — for example `com.rubytech.maxy-code.plist`. Survives logout/login and reboot via `KeepAlive=true` and `RunAtLoad=true`. Two brands on the same Mac get two distinct plists (brand-hostname-keyed), so install order is independent. Use `launchctl print gui/$UID/com.rubytech.<brand-hostname>` for service state. The `[create-maxy] launchd-plist=<path> loaded=true` line in the install log confirms `launchctl bootstrap` accepted the plist; `loaded=false exit=<n>` is the failure signal (run `plutil -lint <path>` to diagnose).
+
+**Cloudflare on darwin.** The installer brew-installs the `cloudflared` binary so it is on PATH, but does not invoke `cloudflared service install` or `cloudflared tunnel route dns` — public reach is opt-in. After install, the operator runs `cloudflared tunnel login` (browser-driven) followed by the existing tunnel-setup flow if they want a public address. Grep `[create-maxy] darwin-cloudflare-skip=true` in the install log to confirm the installer took the documented skip path.
+
+**Uninstall.** `npx -y @rubytech/create-maxy-code uninstall` (or the realagent equivalent) bootsout the LaunchAgent, removes the plist, and deletes `~/.<brand>/`. Homebrew-installed dependencies (curl, git, unzip, jq, poppler, ffmpeg, node@22, neo4j, cloudflared) remain — remove them with `brew uninstall` if you want a clean slate.
+
+**Pre-flight.** macOS < 14 is refused at pre-flight via `parseSwVers` (`sw_vers -productVersion` must be `≥ 14`).
+
+**Diagnostic grep recipe.** After a Mac install, the canonical log path is `~/.<brand>/logs/install-*.log`. One pass tells you everything:
+
+```bash
+grep -E '^\[create-maxy\] (platform|darwin-hostname-mode|darwin-cloudflare-skip|launchd-plist|init-logging FAILED)=' \
+  ~/.<brand>/logs/install-*.log
+```
 
-The installer registers {{productName}} as a launchd LaunchAgent at `~/Library/LaunchAgents/com.rubytech.maxy.plist` — survives logout/login and reboot. Use `launchctl print gui/$UID/com.rubytech.maxy` for service state. `--hostname <h>` sets HostName / LocalHostName / ComputerName via `sudo scutil`. macOS < 14 is refused at pre-flight.
+Every successful Mac install contains, in order: `platform=darwin`, `darwin-hostname-mode=…`, `darwin-cloudflare-skip=true`, every brew install/verify line, `launchd-plist=… loaded=true`. Absence of any of these is the failure signal.
 
 ## Initial Setup
 

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

@@ -197,13 +197,7 @@ When `search` is true and `query` is non-null, the rewritten query replaces the
 
 ### Knowledge retrieval gate
 
-The classifier is one input to a broader decision tree that determines whether `memory-search` runs:
-
-| Agent config | Classifier runs? | Search runs? |
-|---|---|---|
-| `liveMemory: true` | No | Always — the admin opted into live knowledge and the classifier cannot know what the graph contains. ~200ms cost is negligible vs. cost of a miss. |
-| `knowledgeBaked: true`, `liveMemory: false` | No | Never — KNOWLEDGE.md is the sole knowledge source. |
-| `knowledgeBaked: false` | Yes | Only if classifier says `search: true` (or classifier fails → fallback to always-search). |
+On the public PTY surface the agent itself decides when to call `memory-search` — there is no server-side classifier interposed between the user message and the agent's first tool call. KNOWLEDGE.md (when present) is assembled into the agent's system prompt at spawn time. Whether `memory-search` is reachable at message time is controlled by the agent's `liveMemory` config flag: when `true`, the per-spawn allowlist includes `memory-search` and reads run with `ALLOWED_SCOPES=public`; when `false`, the agent has no graph access mid-turn.
 
 ### Observability
 
@@ -325,10 +319,7 @@ Results from keyword subscription searches are merged into the same scored map a
 
 ### Lifecycle
 
-| Mode | How keywords are used |
-|---|---|
-| `liveMemory: true` | Keywords are passed as `KNOWLEDGE_KEYWORDS` env var to the memory MCP server at runtime. Every query includes keyword subscription searches alongside the primary search. |
-| `liveMemory: false` | Keywords are used by the `update-knowledge` admin skill when regenerating KNOWLEDGE.md. The regeneration queries the graph with both direct tags and keyword subscriptions. |
+Keywords are consumed by the `update-knowledge` admin skill when regenerating KNOWLEDGE.md — the regeneration query broadens the operator-tagged set with keyword matches so newly-added graph content that shares a subscribed topic lands in the next baked snapshot. There is no runtime keyword-injection path on the public PTY surface.
 
 ---
 
@@ -368,23 +359,12 @@ The final step in the retrieval pipeline is injecting retrieved content into the
 
 ### Public agent paths
 
-The server-side code in `claude-agent.ts` builds the system prompt before making the Anthropic API call. Three paths:
+Public agents run on the same native Claude Code PTY surface as the admin, dispatched through the channel PTY-bridge with `role: 'public'`. The agent's directory files (IDENTITY.md, SOUL.md, KNOWLEDGE.md, KNOWLEDGE-SUMMARY.md when present) are assembled into the system prompt at spawn time. There is no per-turn server-side knowledge injection.
 
-**Path 1 — Baked only** (`knowledgeBaked: true`, `liveMemory: false`):
-- KNOWLEDGE.md content is embedded directly in the system prompt as `<knowledge>...</knowledge>`
-- No runtime search. No classifier. No memory MCP server call.
-- KNOWLEDGE.md quality is the ceiling of the agent's factual knowledge.
+Two paths, selected by the agent's `liveMemory` config flag:
 
-**Path 2 — Baked + live** (`knowledgeBaked: true`, `liveMemory: true`):
-- KNOWLEDGE.md is embedded as `<knowledge>...</knowledge>` (static baseline)
-- Runtime search also runs (always, bypassing classifier)
-- Results appended as `<live-memory>...</live-memory>`
-- Agent sees both: curated knowledge file + fresh graph results
-
-**Path 3 — Memory-search only** (`knowledgeBaked: false`):
-- No KNOWLEDGE.md exists (e.g., on a fresh install before the operator has had any conversations)
-- Classifier decides whether to search (or falls back to always-search)
-- Results injected as `<memory>...</memory>`
+- **`liveMemory: false`** — `memory-search` is excluded from the per-spawn `--allowed-tools` allowlist. The agent has no graph access mid-conversation; KNOWLEDGE.md is the ceiling of factual knowledge.
+- **`liveMemory: true`** — `memory-search` is in the allowlist. The agent decides at message time whether to call it; reads run against the graph with `ALLOWED_SCOPES=public` so only public-scoped nodes return. KNOWLEDGE.md and the live `memory-search` surface are complementary — the baked file covers evergreen facts; the live tool covers the long-tail public-scoped lookups.
 
 ### KNOWLEDGE.md staleness guard
 
@@ -496,6 +476,10 @@ A second boot gate walks every specialist `.md` under `platform/templates/specia
 
 This gate was Task 173. The `brand-excluded` branch closes the recurring crash-restart loop on brands that ship without a plugin the shared `personal-assistant.md` template references (e.g. `realagent-code` excludes `telegram` while the template hard-codes `mcp__telegram__*`). The brand-agnostic template stays a single file; the brand-aware filter expresses what the specialist *may* do on this install while the template expresses what it *can* do across brands. Tool typos and renamed plugins still refuse to boot — only namespaces explicitly named in `plugins.excluded` are demoted to strip-and-warn.
 
+**Brand-foreign premium bundles (Task 343).** The same drift gate walks `premium-plugins/<bundle>/agents/` for every bundle present on disk. On brands whose installer ships every premium bundle but only intends to surface a subset, a foreign-bundle specialist file (e.g. `real-agent/listing-curator.md` on a `maxy-code` install) used to reach the drift assertion and refuse boot the moment any of its declared tools missed the active brand's tool surface — the `image-fetch` tool that registered at runtime but was undeclared in `memory/PLUGIN.md` produced exactly this loop. The manager resolves `brand.json#shipsPremiumBundles` into the same three modes `paths.ts` already enforces for the UI: `true` ships every premium bundle, a `string[]` ships only the named bundle directories, `false`/missing ships none (fail-closed). Premium bundles outside the resolved mode are dropped before drift, with one `agents-dir-skipped path=<p> reason=brand-foreign-bundle bundle=<n>` line per drop. When the premium root exists and the mode resolves to `none` (so every premium dir filters), one additional `brand-foreign-skip-all path=<premiumPluginsRoot> reason=shipsPremiumBundles-missing-or-empty premium-dirs-skipped=<N>` line surfaces the misconfig. `platform/plugins/` candidates are never filtered — brand-foreign is a premium-tree concept only.
+
+**Structured journald mirror for boot-failed (Task 343).** Every `boot-failed reason=specialist-tool-drift …` line is mirrored to journald via `systemd-cat -t maxy-csm -p err` with the fields `specialist=`, `tool=`, `drift_reason=`, `agent_path=` so `journalctl --user -u <brand>-claude-session-manager.service -t maxy-csm` can filter by any of them without grep on `server.log`. The stdout line stays unchanged so the existing diagnostic one-liners keep working. `systemd-cat` absence (e.g. macOS dev box) is swallowed — the stdout line is the primary surface; the structured emit is auxiliary.
+
 **Per-spawn signals (server.log).** Every spawn emits `pty-spawn-mcp-config servers=<N> tools=<M> bytes=<B> path=<…>` once, plus one `pty-spawn-agents-dir role=<admin|public> path=<…>` per added directory. Specialist spawns additionally emit `pty-spawn-allowlist specialist=<name> count=<N> stripped=<S> sourced-from=agent-frontmatter` where `stripped` is the count of brand-excluded tool names removed before argv emission. The diagnostic one-liner is `grep -E 'pty-spawn-mcp-config|pty-spawn-agents-dir|pty-spawn-allowlist|mcp-config-allowlist-coverage|specialist-tool-strip|boot-failed reason=' ~/.<brand>/logs/server.log | tail -50`.
 
 **Brand-process start counter (Task 173).** `platform/ui/server-init.cjs` increments a persistent counter at `/tmp/server-init-<accountId>-restart.count` on every fresh start and emits `[server-init] start count=<N> account=<accountId> counter-path=<…>` to `server.log`. /tmp clears on reboot, so a clean reboot starts the count fresh; any value `>1` between operator-observed reboots means the brand process (driven by its `Requires=<brand>-claude-session-manager.service` clause) is restarting. The diagnostic one-liner is `grep '\[server-init\] start' ~/.<brand>/logs/server.log | tail -5` — the trailing `count=` value is the loop depth without counting SIGTERMs.