@rubytech/create-realagent 1.0.628 → 1.0.630

package/dist/index.js

@@ -813,6 +813,39 @@ function installOllama(embedModel) {
     logFile(`  Pulling embedding model: ${embedModel}`);
     shellRetry("ollama", ["pull", embedModel], { timeout: 600_000 }, 3, 15);
 }
+// Task 557 — uv/uvx bootstrap. Required by the `graph` MCP server which
+// spawns `uvx mcp-neo4j-cypher@0.6.0 --transport stdio`. Idempotent: when
+// uvx is already on PATH (or under $HOME/.local/bin) we skip. Non-fatal on
+// failure — the installer continues; the graph server will loudly fail
+// at session start with a clear "uvx not found" error, which is retriable
+// via a second installer run with network access.
+function installUv() {
+    if (commandExists("uvx")) {
+        logFile("  uv: already installed");
+        console.log("  uv/uvx already installed.");
+        return;
+    }
+    console.log("  Installing uv (Python tool runner — required by Neo4j MCP server)...");
+    logFile("  uv: installing via astral.sh installer");
+    const result = spawnSync("bash", ["-c", "curl -LsSf https://astral.sh/uv/install.sh | sh -s -- -y"], { stdio: "inherit" });
+    if (result.status !== 0) {
+        console.error(`  WARNING: uv install exited ${result.status} — graph MCP server will fail at session start until this is retried`);
+        logFile(`  WARNING: uv install failed with status ${result.status}`);
+        return;
+    }
+    // The installer writes uvx to $HOME/.local/bin — add it to PATH for the
+    // remainder of this install so commandExists("uvx") works downstream.
+    const localBin = `${process.env.HOME}/.local/bin`;
+    if (process.env.PATH && !process.env.PATH.includes(localBin)) {
+        process.env.PATH = `${localBin}:${process.env.PATH}`;
+    }
+    if (commandExists("uvx")) {
+        logFile("  uv: install succeeded; uvx on PATH");
+    }
+    else {
+        console.error("  WARNING: uv installed but uvx not on PATH — check $HOME/.local/bin");
+    }
+}
 function installCloudflared() {
     if (commandExists("cloudflared")) {
         log("6", TOTAL, "Cloudflared already installed.");
@@ -1937,6 +1970,7 @@ try {
     installNeo4j();
     setupDedicatedNeo4j();
     installOllama(EMBED_MODEL);
+    installUv();
     installCloudflared();
     installWhisperCpp();
     deployPayload(); // Must happen before ensureNeo4jPassword — restores config backup

package/package.json

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

package/payload/platform/lib/graph-mcp/dist/index.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Graph MCP shim — adopts upstream `mcp-neo4j-cypher` per brand.
+ *
+ * Task 557. Claude Code spawns this file as the `graph` MCP server; it
+ * starts the upstream Python server under `uvx` and proxies the JSON-RPC
+ * stdio stream byte-for-byte. While proxying, it:
+ *   1. Resolves `NEO4J_URI/USERNAME/PASSWORD` from the brand's own env
+ *      (falls back to `${PLATFORM_ROOT}/config/.neo4j-password`, matching
+ *      plugins/memory/mcp/src/lib/neo4j.ts:10-21).
+ *   2. Installs the Maxy stderr tee so upstream stderr lands in the
+ *      per-conversation stream log alongside every other plugin.
+ *   3. Locks the upstream server into read-only mode (`NEO4J_READ_ONLY=true`)
+ *      and a stable Maxy namespace (`NEO4J_NAMESPACE=maxy-graph`).
+ *   4. Parses JSON-RPC lines on the request path to record the cypher and
+ *      start time per `id`, and on the response path to emit one
+ *      `[graph-query] op=... brand=... port=... cypher="..." rows=... ms=...`
+ *      line per tool call. Forwarding is byte-accurate — the parser
+ *      observes, never mutates.
+ *
+ * Isolation model per MAXY-PRD.md:627 and create-maxy src/index.ts:504-824:
+ * each brand already owns its own Neo4j instance on its own port with its
+ * own password. This shim trusts that — no query-layer tenant filtering.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/graph-mcp/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/payload/platform/lib/graph-mcp/dist/index.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Graph MCP shim — adopts upstream `mcp-neo4j-cypher` per brand.
+ *
+ * Task 557. Claude Code spawns this file as the `graph` MCP server; it
+ * starts the upstream Python server under `uvx` and proxies the JSON-RPC
+ * stdio stream byte-for-byte. While proxying, it:
+ *   1. Resolves `NEO4J_URI/USERNAME/PASSWORD` from the brand's own env
+ *      (falls back to `${PLATFORM_ROOT}/config/.neo4j-password`, matching
+ *      plugins/memory/mcp/src/lib/neo4j.ts:10-21).
+ *   2. Installs the Maxy stderr tee so upstream stderr lands in the
+ *      per-conversation stream log alongside every other plugin.
+ *   3. Locks the upstream server into read-only mode (`NEO4J_READ_ONLY=true`)
+ *      and a stable Maxy namespace (`NEO4J_NAMESPACE=maxy-graph`).
+ *   4. Parses JSON-RPC lines on the request path to record the cypher and
+ *      start time per `id`, and on the response path to emit one
+ *      `[graph-query] op=... brand=... port=... cypher="..." rows=... ms=...`
+ *      line per tool call. Forwarding is byte-accurate — the parser
+ *      observes, never mutates.
+ *
+ * Isolation model per MAXY-PRD.md:627 and create-maxy src/index.ts:504-824:
+ * each brand already owns its own Neo4j instance on its own port with its
+ * own password. This shim trusts that — no query-layer tenant filtering.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_string_decoder_1 = require("node:string_decoder");
+const index_js_1 = require("../../mcp-stderr-tee/dist/index.js");
+const SERVER_NAME = "graph";
+const UPSTREAM_PACKAGE = "mcp-neo4j-cypher@0.6.0";
+(0, index_js_1.initStderrTee)(SERVER_NAME);
+function resolvePassword() {
+    if (process.env.NEO4J_PASSWORD)
+        return process.env.NEO4J_PASSWORD;
+    // __dirname points at `lib/graph-mcp/dist` after compilation; the platform
+    // root is three levels up (lib/graph-mcp/dist -> lib/graph-mcp -> lib -> platform).
+    const root = process.env.PLATFORM_ROOT ?? (0, node_path_1.resolve)(__dirname, "../../..");
+    const file = (0, node_path_1.resolve)(root, "config/.neo4j-password");
+    try {
+        return (0, node_fs_1.readFileSync)(file, "utf-8").trim();
+    }
+    catch {
+        console.error(`[graph-mcp] password unavailable — file=${file} env=NEO4J_PASSWORD (neither set)`);
+        process.exit(1);
+    }
+}
+const brand = process.env.BRAND ?? "maxy";
+const neo4jUri = process.env.NEO4J_URI ?? "bolt://localhost:7687";
+const neo4jUser = process.env.NEO4J_USERNAME ?? process.env.NEO4J_USER ?? "neo4j";
+const neo4jPassword = resolvePassword();
+const portMatch = /:(\d+)$/.exec(neo4jUri);
+const neo4jPort = portMatch ? portMatch[1] : "?";
+const namespace = process.env.NEO4J_NAMESPACE ?? "maxy-graph";
+const readOnly = process.env.NEO4J_READ_ONLY ?? "true";
+const responseTokenLimit = process.env.NEO4J_RESPONSE_TOKEN_LIMIT ?? "20000";
+const childEnv = {
+    ...process.env,
+    NEO4J_URI: neo4jUri,
+    NEO4J_URL: neo4jUri,
+    NEO4J_USERNAME: neo4jUser,
+    NEO4J_PASSWORD: neo4jPassword,
+    NEO4J_READ_ONLY: readOnly,
+    NEO4J_NAMESPACE: namespace,
+    NEO4J_RESPONSE_TOKEN_LIMIT: responseTokenLimit,
+};
+console.error(`[graph-mcp] boot brand=${brand} uri=${neo4jUri} user=${neo4jUser} ` +
+    `namespace=${namespace} readOnly=${readOnly} tokenLimit=${responseTokenLimit}`);
+const child = (0, node_child_process_1.spawn)("uvx", [UPSTREAM_PACKAGE, "--transport", "stdio"], {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: childEnv,
+});
+child.on("spawn", () => {
+    console.error(`[graph-mcp] spawned ${UPSTREAM_PACKAGE} pid=${child.pid}`);
+});
+child.on("error", (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[graph-mcp] spawn error: ${msg}`);
+    if (err.code === "ENOENT") {
+        console.error("[graph-mcp] uvx not found on PATH — install uv: " +
+            "curl -LsSf https://astral.sh/uv/install.sh | sh -s -- -y");
+    }
+    process.exit(127);
+});
+child.on("exit", (code, signal) => {
+    console.error(`[graph-mcp] uvx exited code=${code ?? "null"} signal=${signal ?? "null"}`);
+    process.exit(code ?? (signal ? 1 : 0));
+});
+// Forward child stderr to our own stderr so the stderr tee picks it up.
+child.stderr.on("data", (chunk) => {
+    process.stderr.write(chunk);
+});
+const pending = new Map();
+function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n)}...`;
+}
+function stripNamespace(toolName) {
+    if (!toolName)
+        return "(unknown)";
+    const prefix = `${namespace}_`;
+    return toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName;
+}
+function extractCypher(args) {
+    if (!args)
+        return null;
+    const q = args["query"] ?? args["cypher"];
+    return typeof q === "string" ? truncate(q.replace(/\s+/g, " ").trim(), 80) : null;
+}
+function countRows(result) {
+    if (!result?.content || !Array.isArray(result.content))
+        return "?";
+    const text = result.content[0]?.text ?? "";
+    const rowsMatch = /(\d+)\s+(?:rows?|records?)/i.exec(text);
+    if (rowsMatch)
+        return rowsMatch[1];
+    return String(result.content.length);
+}
+function onRequestLine(line) {
+    try {
+        const msg = JSON.parse(line);
+        if (msg.method === "tools/call" && msg.id !== undefined) {
+            pending.set(msg.id, {
+                method: stripNamespace(msg.params?.name),
+                cypherPrefix: extractCypher(msg.params?.arguments),
+                startMs: Date.now(),
+            });
+        }
+    }
+    catch {
+        // Non-JSON / partial line — forward untouched, don't log.
+    }
+}
+function onResponseLine(line) {
+    try {
+        const msg = JSON.parse(line);
+        if (msg.id === undefined || !pending.has(msg.id))
+            return;
+        const p = pending.get(msg.id);
+        pending.delete(msg.id);
+        const elapsed = Date.now() - p.startMs;
+        const cypherField = p.cypherPrefix ? `cypher="${p.cypherPrefix.replace(/"/g, "'")}"` : "";
+        if (msg.error) {
+            const errText = (msg.error.message ?? JSON.stringify(msg.error)).replace(/"/g, "'");
+            console.error(`[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} error="${errText}" ms=${elapsed}`);
+        }
+        else {
+            const rows = countRows(msg.result);
+            console.error(`[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} rows=${rows} ms=${elapsed}`);
+        }
+    }
+    catch {
+        // Non-JSON — forward untouched.
+    }
+}
+function makeLineSplitter(onLine) {
+    const decoder = new node_string_decoder_1.StringDecoder("utf8");
+    let buf = "";
+    return (chunk) => {
+        buf += decoder.write(chunk);
+        let idx;
+        while ((idx = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, idx);
+            buf = buf.slice(idx + 1);
+            if (line.length > 0)
+                onLine(line);
+        }
+    };
+}
+const splitRequest = makeLineSplitter(onRequestLine);
+process.stdin.on("data", (chunk) => {
+    splitRequest(chunk);
+    child.stdin.write(chunk);
+});
+process.stdin.on("end", () => {
+    child.stdin.end();
+});
+const splitResponse = makeLineSplitter(onResponseLine);
+child.stdout.on("data", (chunk) => {
+    splitResponse(chunk);
+    process.stdout.write(chunk);
+});
+child.stdout.on("end", () => {
+    process.stdout.end();
+});
+for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.on(sig, () => {
+        console.error(`[graph-mcp] ${sig} received — forwarding to child`);
+        child.kill(sig);
+    });
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/graph-mcp/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/payload/platform/lib/graph-mcp/src/index.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * Graph MCP shim — adopts upstream `mcp-neo4j-cypher` per brand.
+ *
+ * Task 557. Claude Code spawns this file as the `graph` MCP server; it
+ * starts the upstream Python server under `uvx` and proxies the JSON-RPC
+ * stdio stream byte-for-byte. While proxying, it:
+ *   1. Resolves `NEO4J_URI/USERNAME/PASSWORD` from the brand's own env
+ *      (falls back to `${PLATFORM_ROOT}/config/.neo4j-password`, matching
+ *      plugins/memory/mcp/src/lib/neo4j.ts:10-21).
+ *   2. Installs the Maxy stderr tee so upstream stderr lands in the
+ *      per-conversation stream log alongside every other plugin.
+ *   3. Locks the upstream server into read-only mode (`NEO4J_READ_ONLY=true`)
+ *      and a stable Maxy namespace (`NEO4J_NAMESPACE=maxy-graph`).
+ *   4. Parses JSON-RPC lines on the request path to record the cypher and
+ *      start time per `id`, and on the response path to emit one
+ *      `[graph-query] op=... brand=... port=... cypher="..." rows=... ms=...`
+ *      line per tool call. Forwarding is byte-accurate — the parser
+ *      observes, never mutates.
+ *
+ * Isolation model per MAXY-PRD.md:627 and create-maxy src/index.ts:504-824:
+ * each brand already owns its own Neo4j instance on its own port with its
+ * own password. This shim trusts that — no query-layer tenant filtering.
+ */
+
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { initStderrTee } from "../../mcp-stderr-tee/dist/index.js";
+
+const SERVER_NAME = "graph";
+const UPSTREAM_PACKAGE = "mcp-neo4j-cypher@0.6.0";
+
+initStderrTee(SERVER_NAME);
+
+function resolvePassword(): string {
+  if (process.env.NEO4J_PASSWORD) return process.env.NEO4J_PASSWORD;
+  // __dirname points at `lib/graph-mcp/dist` after compilation; the platform
+  // root is three levels up (lib/graph-mcp/dist -> lib/graph-mcp -> lib -> platform).
+  const root = process.env.PLATFORM_ROOT ?? resolve(__dirname, "../../..");
+  const file = resolve(root, "config/.neo4j-password");
+  try {
+    return readFileSync(file, "utf-8").trim();
+  } catch {
+    console.error(`[graph-mcp] password unavailable — file=${file} env=NEO4J_PASSWORD (neither set)`);
+    process.exit(1);
+  }
+}
+
+const brand = process.env.BRAND ?? "maxy";
+const neo4jUri = process.env.NEO4J_URI ?? "bolt://localhost:7687";
+const neo4jUser = process.env.NEO4J_USERNAME ?? process.env.NEO4J_USER ?? "neo4j";
+const neo4jPassword = resolvePassword();
+const portMatch = /:(\d+)$/.exec(neo4jUri);
+const neo4jPort = portMatch ? portMatch[1] : "?";
+const namespace = process.env.NEO4J_NAMESPACE ?? "maxy-graph";
+const readOnly = process.env.NEO4J_READ_ONLY ?? "true";
+const responseTokenLimit = process.env.NEO4J_RESPONSE_TOKEN_LIMIT ?? "20000";
+
+const childEnv: NodeJS.ProcessEnv = {
+  ...process.env,
+  NEO4J_URI: neo4jUri,
+  NEO4J_URL: neo4jUri,
+  NEO4J_USERNAME: neo4jUser,
+  NEO4J_PASSWORD: neo4jPassword,
+  NEO4J_READ_ONLY: readOnly,
+  NEO4J_NAMESPACE: namespace,
+  NEO4J_RESPONSE_TOKEN_LIMIT: responseTokenLimit,
+};
+
+console.error(
+  `[graph-mcp] boot brand=${brand} uri=${neo4jUri} user=${neo4jUser} ` +
+    `namespace=${namespace} readOnly=${readOnly} tokenLimit=${responseTokenLimit}`,
+);
+
+const child = spawn("uvx", [UPSTREAM_PACKAGE, "--transport", "stdio"], {
+  stdio: ["pipe", "pipe", "pipe"],
+  env: childEnv,
+});
+
+child.on("spawn", () => {
+  console.error(`[graph-mcp] spawned ${UPSTREAM_PACKAGE} pid=${child.pid}`);
+});
+
+child.on("error", (err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`[graph-mcp] spawn error: ${msg}`);
+  if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+    console.error(
+      "[graph-mcp] uvx not found on PATH — install uv: " +
+        "curl -LsSf https://astral.sh/uv/install.sh | sh -s -- -y",
+    );
+  }
+  process.exit(127);
+});
+
+child.on("exit", (code, signal) => {
+  console.error(`[graph-mcp] uvx exited code=${code ?? "null"} signal=${signal ?? "null"}`);
+  process.exit(code ?? (signal ? 1 : 0));
+});
+
+// Forward child stderr to our own stderr so the stderr tee picks it up.
+child.stderr.on("data", (chunk: Buffer) => {
+  process.stderr.write(chunk);
+});
+
+// --- JSON-RPC call correlation ---
+// tools/call is the only method we time; initialize and tools/list are noise.
+interface PendingCall {
+  method: string;
+  cypherPrefix: string | null;
+  startMs: number;
+}
+const pending = new Map<string | number, PendingCall>();
+
+function truncate(s: string, n: number): string {
+  return s.length <= n ? s : `${s.slice(0, n)}...`;
+}
+
+function stripNamespace(toolName: string | undefined): string {
+  if (!toolName) return "(unknown)";
+  const prefix = `${namespace}_`;
+  return toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName;
+}
+
+type JsonRpcMessage = {
+  id?: string | number;
+  method?: string;
+  params?: { name?: string; arguments?: Record<string, unknown> };
+  result?: { content?: Array<{ text?: string; type?: string }> };
+  error?: { message?: string; code?: number };
+};
+
+function extractCypher(args: Record<string, unknown> | undefined): string | null {
+  if (!args) return null;
+  const q = args["query"] ?? args["cypher"];
+  return typeof q === "string" ? truncate(q.replace(/\s+/g, " ").trim(), 80) : null;
+}
+
+function countRows(result: JsonRpcMessage["result"]): string {
+  if (!result?.content || !Array.isArray(result.content)) return "?";
+  const text = result.content[0]?.text ?? "";
+  const rowsMatch = /(\d+)\s+(?:rows?|records?)/i.exec(text);
+  if (rowsMatch) return rowsMatch[1];
+  return String(result.content.length);
+}
+
+function onRequestLine(line: string): void {
+  try {
+    const msg = JSON.parse(line) as JsonRpcMessage;
+    if (msg.method === "tools/call" && msg.id !== undefined) {
+      pending.set(msg.id, {
+        method: stripNamespace(msg.params?.name),
+        cypherPrefix: extractCypher(msg.params?.arguments),
+        startMs: Date.now(),
+      });
+    }
+  } catch {
+    // Non-JSON / partial line — forward untouched, don't log.
+  }
+}
+
+function onResponseLine(line: string): void {
+  try {
+    const msg = JSON.parse(line) as JsonRpcMessage;
+    if (msg.id === undefined || !pending.has(msg.id)) return;
+    const p = pending.get(msg.id)!;
+    pending.delete(msg.id);
+    const elapsed = Date.now() - p.startMs;
+    const cypherField = p.cypherPrefix ? `cypher="${p.cypherPrefix.replace(/"/g, "'")}"` : "";
+    if (msg.error) {
+      const errText = (msg.error.message ?? JSON.stringify(msg.error)).replace(/"/g, "'");
+      console.error(
+        `[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} error="${errText}" ms=${elapsed}`,
+      );
+    } else {
+      const rows = countRows(msg.result);
+      console.error(
+        `[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} rows=${rows} ms=${elapsed}`,
+      );
+    }
+  } catch {
+    // Non-JSON — forward untouched.
+  }
+}
+
+function makeLineSplitter(onLine: (line: string) => void): (chunk: Buffer) => void {
+  const decoder = new StringDecoder("utf8");
+  let buf = "";
+  return (chunk: Buffer) => {
+    buf += decoder.write(chunk);
+    let idx: number;
+    while ((idx = buf.indexOf("\n")) !== -1) {
+      const line = buf.slice(0, idx);
+      buf = buf.slice(idx + 1);
+      if (line.length > 0) onLine(line);
+    }
+  };
+}
+
+const splitRequest = makeLineSplitter(onRequestLine);
+process.stdin.on("data", (chunk: Buffer) => {
+  splitRequest(chunk);
+  child.stdin.write(chunk);
+});
+process.stdin.on("end", () => {
+  child.stdin.end();
+});
+
+const splitResponse = makeLineSplitter(onResponseLine);
+child.stdout.on("data", (chunk: Buffer) => {
+  splitResponse(chunk);
+  process.stdout.write(chunk);
+});
+child.stdout.on("end", () => {
+  process.stdout.end();
+});
+
+for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"] as const) {
+  process.on(sig, () => {
+    console.error(`[graph-mcp] ${sig} received — forwarding to child`);
+    child.kill(sig);
+  });
+}

package/payload/platform/lib/graph-mcp/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/package.json

@@ -6,8 +6,8 @@
     "plugins/*/mcp"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
     "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",

package/payload/platform/plugins/cloudflare/scripts/reset-tunnel.sh

@@ -27,7 +27,10 @@ set -euo pipefail
 # --------------------------------------------------------------------------
 
 # shellcheck source=_stream-log.sh
-source "$(dirname "${BASH_SOURCE[0]}")/_stream-log.sh"
+# Resolve symlinks before dirname — ~/reset-tunnel.sh is installed as a symlink
+# (see packages/create-maxy/src/index.ts:installTunnelScripts), so the raw
+# BASH_SOURCE[0] points at $HOME, not the scripts directory where _stream-log.sh lives.
+source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
 require_stream_log_path reset-tunnel
 
 if [ "$#" -lt 1 ]; then

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -29,7 +29,10 @@ set -euo pipefail
 # --------------------------------------------------------------------------
 
 # shellcheck source=_stream-log.sh
-source "$(dirname "${BASH_SOURCE[0]}")/_stream-log.sh"
+# Resolve symlinks before dirname — ~/setup-tunnel.sh is installed as a symlink
+# (see packages/create-maxy/src/index.ts:installTunnelScripts), so the raw
+# BASH_SOURCE[0] points at $HOME, not the scripts directory where _stream-log.sh lives.
+source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
 require_stream_log_path setup-tunnel
 
 # --------------------------------------------------------------------------

package/payload/platform/plugins/docs/references/memory-guide.md

@@ -80,6 +80,14 @@ Ask naturally:
 - "What did I last discuss about the Acme proposal?"
 - "Who have I met from the fintech conference?"
 
+## Listing and counting (Task 557)
+
+Maxy answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
+
+You can also open the Neo4j Browser at any time from the burger menu → **Graph**. Sign in with your Neo4j username (`neo4j`) and password (stored in `config/.neo4j-password` on the device). Run `MATCH (n) RETURN n LIMIT 25` for a visual overview of your graph, or write your own Cypher for ad-hoc exploration.
+
+The browser reaches only your own brand's Neo4j — a Maxy device and a Real Agent device share no graph state even when on the same laptop.
+
 ## Privacy
 
 All memory is stored on your local Raspberry Pi. The Neo4j database never leaves your network. Maxy does not sync memory to any cloud service or third party.