@rubytech/create-maxy-code 0.1.111 → 0.1.113

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.111",
+  "version": "0.1.113",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

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/memory/mcp/dist/index.js

@@ -39,6 +39,7 @@ import { graphPruneDenylistRemove } from "./tools/graph-prune-denylist-remove.js
 import { conversationMemoryExpunge } from "./tools/conversation-memory-expunge.js";
 import { conversationArchiveDeriveInsights, } from "./tools/conversation-archive-derive-insights.js";
 import { conversationArchiveEnrichRejection } from "./tools/conversation-archive-enrich-rejection.js";
+import { fetchImageAsContent } from "./tools/image-fetch.js";
 import { getSession, closeDriver } from "./lib/neo4j.js";
 import { embed } from "./lib/embeddings.js";
 import { notTrashed } from "../../../../lib/graph-trash/dist/index.js";
@@ -1882,6 +1883,40 @@ eagerTool(server, "conversation-search", "Search conversation history using sema
         };
     }
 });
+// image-fetch — return a remote image URL as a vision-capable content block.
+// Built for the listing-curator specialist's per-image vision pass; useful to
+// any caller that has an image URL in hand and a model that can see images.
+// Specialist tool, not in ADMIN_CORE_TOOLS — registered via server.tool, not
+// eagerTool (deferred-by-default ToolSearch tax is acceptable because the
+// curator is the only routine caller).
+server.tool("image-fetch", [
+    "Fetch a remote image URL and return its bytes as an inline image content block the model can see.",
+    "Guards: http/https only, content-type must start with image/, 10 MB byte cap, 30 s timeout.",
+    "Returns one text block summarising the fetch plus one image block on success; one text block with isError on failure.",
+].join(" "), {
+    url: z.string().describe("Absolute http(s) URL of the image to fetch."),
+}, async ({ url }) => {
+    const result = await fetchImageAsContent(url);
+    if (!result.ok) {
+        return {
+            content: [{ type: "text", text: `image-fetch failed: ${result.reason}` }],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Fetched ${result.bytes} bytes (${result.mimeType}) from ${url}`,
+            },
+            {
+                type: "image",
+                data: result.base64,
+                mimeType: result.mimeType,
+            },
+        ],
+    };
+});
 // Cleanup on exit
 process.on("SIGINT", async () => {
     liveSchemaRuntime.cache.stop();