@rubytech/create-maxy 1.0.792 → 1.0.794

package/dist/launchd-plist.js

@@ -0,0 +1,68 @@
+// Task 838 — pure plist XML rendering for the macOS LaunchAgent supervisor.
+// Mirrors the apt-resolve.ts / port-resolution.ts pattern: inputs in, decision
+// out, no I/O. The installer wraps this with writeFileSync + spawnSync(
+// "launchctl", ["bootstrap", `gui/${uid}`, plistPath]) — all spawn/fs lives in
+// index.ts so this module can be unit-tested with concrete fixtures and no
+// side effects.
+//
+// The Linux supervisor (systemd-user persistent unit at
+// `~/.config/systemd/user/<service>.service`) has no analogue here: launchd's
+// LaunchAgent format is a property-list XML document at
+// `~/Library/LaunchAgents/<label>.plist`, and the bootstrap-into-domain flow
+// uses launchctl(1) instead of systemctl. Both supervisors achieve the same
+// success-criteria set: process registered with the user's session manager,
+// auto-restart on crash, restart on logout/login, RunAtLoad on reboot.
+/**
+ * Escape the five XML predefined entities, in order. Order matters: replace
+ * `&` first so an input of `<` doesn't double-escape via the `&` produced by
+ * the `<` rule. The output is safe to embed inside an XML <string> element.
+ */
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Render a launchd LaunchAgent plist as XML. Pure: same input → same output
+ * forever. The caller writes this to `~/Library/LaunchAgents/<label>.plist`
+ * with mode 0644 and then runs `launchctl bootstrap gui/$UID <path>`.
+ *
+ * The output is the canonical plist 1.0 form launchd accepts — XML preamble,
+ * PLIST PUBLIC DOCTYPE, <plist version="1.0"> wrapping a single <dict>. Key
+ * order inside the dict mirrors Apple's LaunchAgent examples for grep-ability:
+ * Label, ProgramArguments, StandardOutPath, StandardErrorPath, [WorkingDirectory,]
+ * KeepAlive, RunAtLoad.
+ */
+export function renderPlist(spec) {
+    const lines = [];
+    lines.push(`<?xml version="1.0" encoding="UTF-8"?>`);
+    lines.push(`<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">`);
+    lines.push(`<plist version="1.0">`);
+    lines.push(`<dict>`);
+    lines.push(`  <key>Label</key>`);
+    lines.push(`  <string>${xmlEscape(spec.label)}</string>`);
+    lines.push(`  <key>ProgramArguments</key>`);
+    lines.push(`  <array>`);
+    for (const arg of spec.programArguments) {
+        lines.push(`    <string>${xmlEscape(arg)}</string>`);
+    }
+    lines.push(`  </array>`);
+    lines.push(`  <key>StandardOutPath</key>`);
+    lines.push(`  <string>${xmlEscape(spec.stdoutPath)}</string>`);
+    lines.push(`  <key>StandardErrorPath</key>`);
+    lines.push(`  <string>${xmlEscape(spec.stderrPath)}</string>`);
+    if (spec.workingDirectory !== undefined) {
+        lines.push(`  <key>WorkingDirectory</key>`);
+        lines.push(`  <string>${xmlEscape(spec.workingDirectory)}</string>`);
+    }
+    lines.push(`  <key>KeepAlive</key>`);
+    lines.push(`  ${spec.keepAlive ? "<true/>" : "<false/>"}`);
+    lines.push(`  <key>RunAtLoad</key>`);
+    lines.push(`  ${spec.runAtLoad ? "<true/>" : "<false/>"}`);
+    lines.push(`</dict>`);
+    lines.push(`</plist>`);
+    return lines.join("\n") + "\n";
+}

package/dist/macos-version.js

@@ -0,0 +1,53 @@
+// Task 840 — pure macOS-version classification for the installer.
+//
+// The installer needs two darwin facts at pre-flight: the macOS version (from
+// `sw_vers`) and whether that version meets the floor required by Tasks 838
+// (modern `launchctl bootstrap gui/$UID …`) and 839 (Apple-Silicon Homebrew).
+// Older macOS partially succeeds, then breaks at the supervisor or brew-cellar
+// layer with cryptic errors — refusing loudly at pre-flight is the contract.
+//
+// Pure logic with no I/O — caller spawns `sw_vers`, captures stdout, and feeds
+// it through parseSwVers + isSupportedMacosVersion. Mirrors the apt-resolve.ts
+// pattern (Task 638): inputs in, decision out, every branch testable with
+// real captured fixtures.
+/**
+ * Parse the stdout of macOS's `sw_vers` command. Real output has the shape:
+ *
+ *   ProductName: macOS
+ *   ProductVersion: 14.4.1
+ *   BuildVersion: 23E224
+ *
+ * Returns null when either ProductName or ProductVersion is absent — the
+ * caller treats null as "refuse with malformed-stdout diagnostic" rather than
+ * silently coercing to undefined and producing a confusing version check.
+ */
+export function parseSwVers(stdout) {
+    const productMatch = stdout.match(/^ProductName:\s*(.+)$/m);
+    const versionMatch = stdout.match(/^ProductVersion:\s*(.+)$/m);
+    if (!productMatch || !versionMatch)
+        return null;
+    return {
+        product: productMatch[1].trim(),
+        version: versionMatch[1].trim(),
+    };
+}
+/**
+ * True when `version`'s major component is ≥ 14 (the floor required by Tasks
+ * 838 + 839). Returns false for empty strings, non-numeric leading components,
+ * and any major < 14. A numeric-only check is sufficient — Apple's published
+ * macOS versions use a strict `MAJOR.MINOR[.PATCH]` integer scheme.
+ */
+export function isSupportedMacosVersion(version) {
+    const m = version.match(/^(\d+)\./);
+    if (!m) {
+        // Fall back to whole-version-as-integer for the macOS 14.0 / 15 form
+        // where the leading number isn't followed by a dot. Defence in depth —
+        // the regex above already handles "14.0", but a bare "14" should also
+        // pass.
+        const bare = version.match(/^(\d+)$/);
+        if (!bare)
+            return false;
+        return parseInt(bare[1], 10) >= 14;
+    }
+    return parseInt(m[1], 10) >= 14;
+}

package/dist/platform-detect.js

@@ -0,0 +1,36 @@
+// Task 836 wedge — pure platform classification for the installer.
+//
+// The installer's existing `isLinux()` checks (26 sites in index.ts) collapse
+// process.platform into a boolean and treat every non-Linux value as "skip
+// silently." Follow-up tasks 838/839/840 widen that to an explicit ternary
+// (linux | darwin | unsupported) so unsupported targets refuse loudly with a
+// log line operators can grep, instead of completing in a non-functional state.
+//
+// This module ships dead until those follow-ups land. Pure logic with no I/O —
+// caller injects process.platform so tests pass arbitrary fixtures without
+// touching the host's actual platform.
+/**
+ * Classify a Node process.platform value into the ternary the installer cares
+ * about. Anything not in { linux, darwin } returns "unsupported"; the caller
+ * decides whether to refuse the install or no-op.
+ */
+export function detectPlatform(nodePlatform) {
+    if (nodePlatform === "linux")
+        return "linux";
+    if (nodePlatform === "darwin")
+        return "darwin";
+    return "unsupported";
+}
+/**
+ * Narrow a Node process.platform to a SupportedPlatform or throw with the
+ * literal refusal message follow-up tasks log + grep on. Use this at install
+ * pre-flight where continuing on an unsupported OS would silently complete a
+ * broken install.
+ */
+export function requireSupportedPlatform(nodePlatform) {
+    const detected = detectPlatform(nodePlatform);
+    if (detected === "unsupported") {
+        throw new Error(`[create-maxy] platform=${nodePlatform} — refusing: only linux and darwin are supported`);
+    }
+    return detected;
+}

package/dist/uninstall.js

@@ -64,6 +64,23 @@ function shell(command, args, options) {
 function isLinux() {
     return process.platform === "linux";
 }
+function isDarwin() {
+    return process.platform === "darwin";
+}
+// Task 838 — mirror the launchd identifiers from index.ts so the uninstall
+// can locate the LaunchAgent without reaching across modules. Per the
+// `uninstall.ts:` "Shell helpers (duplicated from index.ts ...)" policy,
+// these are intentionally duplicated rather than shared.
+function launchdLabel() {
+    return `com.rubytech.${BRAND.hostname}`;
+}
+function plistPath() {
+    return resolve(HOME, "Library/LaunchAgents", `${launchdLabel()}.plist`);
+}
+function gui() {
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    return `gui/${uid}`;
+}
 function commandExists(cmd) {
     try {
         execFileSync("which", [cmd], { stdio: "pipe" });
@@ -120,6 +137,15 @@ function peerBrandPresent() {
 // ---------------------------------------------------------------------------
 function stopServices() {
     log("1", "Stopping services...");
+    // Task 838 — darwin: bootout the LaunchAgent. bootout exits 0 on success,
+    // 113 ("Unknown service") when the agent isn't loaded — both are
+    // acceptable end-states for "service stopped". The plist removal in
+    // removeSystemdService() finishes the cleanup.
+    if (isDarwin()) {
+        spawnSync("launchctl", ["bootout", `${gui()}/${launchdLabel()}`], { stdio: "pipe", timeout: 15_000 });
+        console.log(`  Booted out ${launchdLabel()}`);
+        return;
+    }
     // Stop platform user service
     try {
         spawnSync("systemctl", ["--user", "stop", BRAND.serviceName.replace(".service", "")], { stdio: "pipe", timeout: 15_000 });
@@ -563,6 +589,27 @@ function removeSystemConfig() {
 // ---------------------------------------------------------------------------
 function removeSystemdService() {
     log("8", "Removing systemd service...");
+    // Task 838 — darwin: bootout (idempotent — already done in stopServices,
+    // re-running is a no-op exit 113) and delete the plist. The wrapper
+    // shell script lives in CONFIG_DIR which step 4 (removeAppDirs) wipes,
+    // so no separate cleanup is needed.
+    if (isDarwin()) {
+        spawnSync("launchctl", ["bootout", `${gui()}/${launchdLabel()}`], { stdio: "pipe", timeout: 15_000 });
+        const plist = plistPath();
+        if (existsSync(plist)) {
+            try {
+                rmSync(plist);
+                console.log(`  Removed ${plist}`);
+            }
+            catch (err) {
+                console.log(`  Failed to remove ${plist}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            console.log(`  ${plist} not found — skipping`);
+        }
+        return;
+    }
     // Disable the service
     const svcUnit = BRAND.serviceName.replace(".service", "");
     try {

package/package.json

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

package/payload/platform/lib/graph-search/src/__tests__/fulltext-coverage.test.ts

@@ -85,6 +85,14 @@ const CANONICAL_TEXT_PROPERTIES = [
   "contactValue",
   // ToolCall
   "toolName",
+  // Agent (Task 837) — public-agent projection. `displayName` mirrors
+  // config.json; `slug` is the directory-name identifier; `role` is the
+  // discriminator carried on the four owned :KnowledgeDocument projections
+  // ('identity' | 'soul' | 'knowledge' | 'knowledge-summary'). Adding any
+  // new agent-side text property to the projector requires extending both
+  // the schema's ON EACH list and this canon, otherwise BM25 silently
+  // misses operator queries that match the new field.
+  "displayName", "slug", "role",
 ];
 
 interface IndexDeclaration {

package/payload/platform/neo4j/edge-annotations.json

@@ -111,6 +111,26 @@
     "OBSERVED_IN": {
       "direction": "(*)-[:OBSERVED_IN]->(Conversation)",
       "note": "Observation provenance."
+    },
+    "HAS_IDENTITY": {
+      "direction": "(Agent)-[:HAS_IDENTITY]->(KnowledgeDocument)",
+      "note": "Task 837 — public-agent IDENTITY.md projection (KnowledgeDocument with role='identity', namespaced attachmentId='agent:<slug>:identity')."
+    },
+    "HAS_SOUL": {
+      "direction": "(Agent)-[:HAS_SOUL]->(KnowledgeDocument)",
+      "note": "Task 837 — public-agent SOUL.md projection (role='soul')."
+    },
+    "HAS_KNOWLEDGE": {
+      "direction": "(Agent)-[:HAS_KNOWLEDGE]->(KnowledgeDocument)",
+      "note": "Task 837 — public-agent KNOWLEDGE.md projection (role='knowledge'); KNOWLEDGE-SUMMARY.md uses the same edge with role='knowledge-summary'."
+    },
+    "USES_KNOWLEDGE": {
+      "direction": "(Agent)-[:USES_KNOWLEDGE]->(KnowledgeDocument)",
+      "note": "Task 837 — operator-tagged docs (slug ∈ k.agents). Materialised at projection time only; runtime memory-search reads k.agents directly."
+    },
+    "HANDLED_BY": {
+      "direction": "(Conversation)-[:HANDLED_BY]->(Agent)",
+      "note": "Task 837 — public conversations only. Written by ensureConversation via OPTIONAL MATCH so orphan slugs do not block conversation creation."
     }
   },
   "sublabels": {

package/payload/platform/neo4j/migrations/002-project-public-agents.ts

@@ -0,0 +1,191 @@
+/**
+ * Migration 002 — Project file-based public agents into the graph (Task 837).
+ *
+ * Two passes:
+ *
+ *   1. Walk every account directory under data/accounts/<accountId>/agents/
+ *      and call projectAgent(accountId, accountDir, slug) for each non-admin
+ *      agent that has a config.json. The projector is idempotent: re-running
+ *      this migration produces no duplicate nodes or edges.
+ *
+ *   2. For every existing public Conversation that carries an agentSlug
+ *      property, MATCH the corresponding :Agent and MERGE the
+ *      (:Conversation)-[:HANDLED_BY]->(:Agent) edge. Conversations whose
+ *      slug doesn't resolve to an Agent (orphan slugs from deleted agents,
+ *      or DM-channel public flows that haven't been extended to register a
+ *      slug) are left edge-less; they will gain the edge automatically once
+ *      the slug is registered or a new agent at that slug is projected.
+ *
+ * Run via the platform/ui standalone runtime so it picks up the same
+ * NEO4J_URI / accounts-directory resolution as the server:
+ *
+ *   cd platform/ui && \
+ *     NEO4J_URI=bolt://… NEO4J_PASSWORD=… \
+ *     npx tsx ../neo4j/migrations/002-project-public-agents.ts
+ *
+ * Output: structured `[agent-graph-backfill]` lines per account + a final
+ * totals line. A non-zero exit code on any per-account failure surfaces to
+ * the operator; subsequent accounts are still attempted (the migration is
+ * isolating by account, not all-or-nothing).
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  projectAgent,
+  getSession,
+} from "../../ui/app/lib/neo4j-store";
+import { ACCOUNTS_DIR } from "../../ui/app/lib/claude-agent/account";
+
+interface PerAccountStats {
+  accountId: string;
+  agents: number;
+  agentFailures: number;
+  convEdges: number;
+  convOrphans: number;
+  convCandidates: number;
+}
+
+async function projectAccountAgents(
+  accountId: string,
+  accountDir: string,
+): Promise<{ agents: number; agentFailures: number }> {
+  const agentsDir = resolve(accountDir, "agents");
+  if (!existsSync(agentsDir)) return { agents: 0, agentFailures: 0 };
+
+  let agents = 0;
+  let agentFailures = 0;
+  for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === "admin") continue;
+
+    const configPath = resolve(agentsDir, entry.name, "config.json");
+    if (!existsSync(configPath)) continue;
+
+    try {
+      await projectAgent(accountId, accountDir, entry.name);
+      agents++;
+    } catch (err) {
+      agentFailures++;
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[agent-graph-backfill] account=${accountId.slice(0, 8)} agent=${entry.name} project FAILED error="${msg}"`,
+      );
+    }
+  }
+  return { agents, agentFailures };
+}
+
+interface HandledByBackfillStats {
+  candidates: number;
+  edges: number;
+  orphans: number;
+}
+
+/**
+ * Two-pass: count candidate Conversations (those carrying agentSlug),
+ * then OPTIONAL MATCH to surface orphans separately from successful merges.
+ * A hard MATCH-then-MATCH chain would silently filter orphan-slug rows out,
+ * making `edges=0` indistinguishable from "no public conversations exist"
+ * vs "every slug is orphaned" — different incidents, different fixes.
+ */
+async function backfillHandledByEdges(accountId: string): Promise<HandledByBackfillStats> {
+  const session = getSession();
+  try {
+    const result = await session.run(
+      `MATCH (c:Conversation {accountId: $accountId, agentType: 'public'})
+       WHERE c.agentSlug IS NOT NULL
+       OPTIONAL MATCH (a:Agent {accountId: $accountId, slug: c.agentSlug})
+       FOREACH (_ IN CASE WHEN a IS NULL THEN [] ELSE [1] END | MERGE (c)-[:HANDLED_BY]->(a))
+       RETURN
+         count(c) AS candidates,
+         sum(CASE WHEN a IS NULL THEN 0 ELSE 1 END) AS edges,
+         sum(CASE WHEN a IS NULL THEN 1 ELSE 0 END) AS orphans`,
+      { accountId },
+    );
+    const toNum = (v: unknown): number => {
+      if (typeof v === "number") return v;
+      if (v && typeof (v as { toNumber: () => number }).toNumber === "function") {
+        return (v as { toNumber: () => number }).toNumber();
+      }
+      return 0;
+    };
+    return {
+      candidates: toNum(result.records[0]?.get("candidates")),
+      edges: toNum(result.records[0]?.get("edges")),
+      orphans: toNum(result.records[0]?.get("orphans")),
+    };
+  } finally {
+    await session.close();
+  }
+}
+
+async function main(): Promise<void> {
+  const start = Date.now();
+
+  if (!existsSync(ACCOUNTS_DIR)) {
+    console.error(`[agent-graph-backfill] ACCOUNTS_DIR missing at ${ACCOUNTS_DIR} — nothing to do`);
+    process.exit(0);
+  }
+
+  const accountEntries = readdirSync(ACCOUNTS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory());
+
+  console.error(`[agent-graph-backfill] start accounts=${accountEntries.length}`);
+
+  let totalAgents = 0;
+  let totalAgentFailures = 0;
+  let totalConvEdges = 0;
+  let totalConvOrphans = 0;
+  let totalConvCandidates = 0;
+  const perAccount: PerAccountStats[] = [];
+
+  for (const entry of accountEntries) {
+    const accountDir = resolve(ACCOUNTS_DIR, entry.name);
+    const accountId = entry.name;
+    const accountStart = Date.now();
+
+    const { agents, agentFailures } = await projectAccountAgents(accountId, accountDir);
+    totalAgents += agents;
+    totalAgentFailures += agentFailures;
+
+    let convStats: HandledByBackfillStats = { candidates: 0, edges: 0, orphans: 0 };
+    try {
+      convStats = await backfillHandledByEdges(accountId);
+      totalConvEdges += convStats.edges;
+      totalConvOrphans += convStats.orphans;
+      totalConvCandidates += convStats.candidates;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[agent-graph-backfill] account=${accountId.slice(0, 8)} handled-by-backfill FAILED error="${msg}"`,
+      );
+    }
+
+    perAccount.push({
+      accountId,
+      agents,
+      agentFailures,
+      convEdges: convStats.edges,
+      convOrphans: convStats.orphans,
+      convCandidates: convStats.candidates,
+    });
+    const ms = Date.now() - accountStart;
+    console.error(
+      `[agent-graph-backfill] account=${accountId.slice(0, 8)} agents=${agents} failures=${agentFailures} conv-candidates=${convStats.candidates} conv-edges=${convStats.edges} conv-orphans=${convStats.orphans} ms=${ms}`,
+    );
+  }
+
+  const ms = Date.now() - start;
+  console.error(
+    `[agent-graph-backfill] done totals: agents=${totalAgents} agent-failures=${totalAgentFailures} conv-candidates=${totalConvCandidates} conv-edges=${totalConvEdges} conv-orphans=${totalConvOrphans} ms=${ms}`,
+  );
+
+  process.exit(totalAgentFailures > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`[agent-graph-backfill] fatal error="${msg}"`);
+  process.exit(2);
+});

package/payload/platform/neo4j/schema.cypher

@@ -286,6 +286,7 @@ OPTIONS {
 //   - Email: Email, EmailAccount
 //   - Review signals: ReviewAlert
 //   - CV/career sublabels: Position, Credential
+//   - Public agents: Agent (Task 837 — projection of file-based public agents)
 //
 // Property union — every textual property the schema's writers assign:
 //   - Generic: name, title, summary, body, content, text, description, headline, abstract,
@@ -301,6 +302,11 @@ OPTIONS {
 //   - Credential: authority
 //   - AccessGrant: contactValue
 //   - ToolCall: toolName
+//   - Agent (Task 837): displayName, slug, role
+//     `displayName` = operator-facing name; `slug` = directory-name identifier;
+//     `role` = discriminator on KnowledgeDocument projections
+//     ('identity'|'soul'|'knowledge'|'knowledge-summary') so BM25 hits surface
+//     which file backed the result. Distinct from Person.role (no shadow).
 CREATE FULLTEXT INDEX entity_search IF NOT EXISTS
 FOR (n:LocalBusiness|Service|PriceSpecification|OpeningHoursSpecification|Organization
     |Person|UserProfile|Preference|AdminUser|AccessGrant
@@ -309,12 +315,13 @@ FOR (n:LocalBusiness|Service|PriceSpecification|OpeningHoursSpecification|Organi
     |Task|Project|Event
     |Workflow|WorkflowStep|WorkflowRun|StepResult
     |OnboardingState|Email|EmailAccount|ReviewAlert
-    |Position|Credential)
+    |Position|Credential|Agent)
 ON EACH [n.name, n.firstName, n.lastName, n.givenName, n.familyName,
          n.title, n.currentTitle, n.summary, n.body, n.content, n.text, n.description, n.headline, n.abstract,
          n.email, n.note, n.label, n.value, n.message, n.preview, n.tagline,
          n.subject, n.bodyPreview, n.fromName, n.fromAddress, n.agentAddress, n.screeningReason,
-         n.authority, n.contactValue, n.toolName];
+         n.authority, n.contactValue, n.toolName,
+         n.displayName, n.slug, n.role];
 
 // Project node (Task 740) — a standalone creative-output node distinct from
 // :Section. Anchored via (:UserProfile)-[:CREATED]->(:Project), with optional
@@ -724,6 +731,66 @@ FOR (ag:AccessGrant) ON (ag.magicToken);
 CREATE INDEX access_grant_status IF NOT EXISTS
 FOR (ag:AccessGrant) ON (ag.status);
 
+// ----------------------------------------------------------
+// Agent node — projection of file-based public agents (Task 837)
+//
+// Source of truth remains the filesystem: accountDir/agents/<slug>/
+// {config.json, IDENTITY.md, SOUL.md, KNOWLEDGE.md, KNOWLEDGE-SUMMARY.md}.
+// The Agent node is a graph projection so operators can see, on /graph,
+// which public agents exist, what knowledge they have access to, and
+// which conversations they have handled. Re-running the projector
+// is idempotent and never mutates the on-disk files.
+//
+// Properties (mirrored from config.json + filesystem mtime):
+//   slug              — directory name; immutable identifier within an account
+//   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)
+//   role              — always 'agent' (mirrors KnowledgeDocument.role
+//                       discriminator; surfaces in BM25 hits)
+//   createdAt         — ISO 8601, set on first projection
+//   updatedAt         — ISO 8601, set on every projection
+//
+// Owned KnowledgeDocument projections (deleted on agent delete):
+//   (Agent)-[:HAS_IDENTITY]->(:KnowledgeDocument {role:'identity'})
+//   (Agent)-[:HAS_SOUL    ]->(:KnowledgeDocument {role:'soul'})
+//   (Agent)-[:HAS_KNOWLEDGE]->(:KnowledgeDocument {role:'knowledge'})
+//   (Agent)-[:HAS_KNOWLEDGE]->(:KnowledgeDocument {role:'knowledge-summary'})
+// attachmentId is namespaced as "agent:<accountId>:<slug>:<role>" so the
+// projection reuses the existing knowledge_doc_id_unique constraint without
+// a parallel uniqueness scheme. The accountId segment is load-bearing —
+// without it, two accounts with the same agent slug would collide on the
+// global unique constraint and the second projection would silently
+// re-parent the first account's doc via the MERGE+SET path. Account
+// isolation is doctrine.
+//
+// Operator-tagged docs (NOT deleted on agent delete — only edges removed):
+//   (Agent)-[:USES_KNOWLEDGE]->(:KnowledgeDocument)
+// where slug ∈ KnowledgeDocument.agents. Materialised at projection time
+// only; the runtime memory-search path continues to read k.agents directly,
+// so a doc tagged after the last projection becomes graph-visible at the
+// next re-projection but is reachable at runtime immediately. The runtime
+// path is unchanged — see [public-agent.ts:130-160].
+//
+// Conversation→Agent edge (written by ensureConversation when
+// agentType='public' and agentSlug is set):
+//   (Conversation)-[:HANDLED_BY]->(Agent)
+// OPTIONAL MATCH on the Agent so a public conversation with an orphan
+// slug still writes (single `[agent-graph] handled-by-skip` log line).
+//
+// Composite uniqueness: one Agent per (accountId, slug) — the directory
+// name is the natural key within an account, slugs collide across
+// accounts and that's allowed.
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT agent_account_slug_unique IF NOT EXISTS
+FOR (a:Agent) REQUIRE (a.accountId, a.slug) IS UNIQUE;
+
+CREATE INDEX agent_account IF NOT EXISTS
+FOR (a:Agent) ON (a.accountId);
+
 // ----------------------------------------------------------
 // AdminUser node — device-level admin identity
 // Platform-native. Represents a human who administers one or

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

@@ -195,7 +195,8 @@ After creation, no template metadata persists in the agent's files. The resultin
 9. **KNOWLEDGE.md generation** — populate from the now-tagged set plus keyword matches using the `update-knowledge` skill workflow
 10. Write `config.json` with selected model, plugins, status "active", `liveMemory`, and `knowledgeKeywords`. This is the last gated write — placed after IDENTITY.md, SOUL.md, and KNOWLEDGE.md to prevent cascade failure if one gate stalls.
 11. Check context budget — auto-summarise if over threshold
-12. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
+12. **Project the agent into the graph** — delegate to the `database-operator` specialist with the instruction: "Project public agent `{slug}` into the graph by POSTing to `/api/admin/agents/{slug}/project` (Task 837 surface)." The route reads the on-disk files and idempotently MERGEs the `:Agent` node, the four owned `:KnowledgeDocument` projections (IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY when present, namespaced `attachmentId="agent:<slug>:<role>"`), the `HAS_*` edges, and the `USES_KNOWLEDGE` edges to every operator-tagged doc. Loud-fail: if the route returns non-2xx, surface the error to the user verbatim — the agent's files exist on disk but its graph projection is incomplete, which means the operator's /graph view will not show this agent. Re-running the projection is safe; it is the same idempotent MERGE.
+13. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
 
 ### List
 
@@ -231,6 +232,8 @@ For knowledge scope changes:
 - Allow toggling `liveMemory` on/off (update `config.json`).
 - After changes, offer to refresh KNOWLEDGE.md using the `update-knowledge` skill.
 
+**After every Edit operation that touches IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY/`config.json` (including `liveMemory`, `knowledgeKeywords`, or direct-tag mutations), delegate to `database-operator` to re-project: POST `/api/admin/agents/{slug}/project`.** Without re-projection the on-disk files diverge from the graph state — the operator sees stale `:Agent` properties and stale `USES_KNOWLEDGE` edges in /graph. Loud-fail: surface non-2xx errors verbatim.
+
 ### Delete
 
 Deletion removes the entire agent directory (`agents/{slug}/`) — not individual files. A partial deletion leaves ghost state that poisons future creation into the same slug.
@@ -242,7 +245,7 @@ Deletion removes the entire agent directory (`agents/{slug}/`) — not individua
 - If no other agents remain (or the user declines to set a new default), clear the `defaultAgent` field by calling `account-update` with `field: "defaultAgent"`, `value: ""`. Tell the user that visitors to the root URL will see a "no agents" message until a new agent is created.
 
 **Cleanup sequence:**
-- Remove the entire `agents/{slug}/` directory
+- Issue `DELETE /api/admin/agents/{slug}` — the route runs `deleteAgentProjection` (Task 837) FIRST to remove the `:Agent` node and its four owned `:KnowledgeDocument` projections, then `rmSync` the directory. Loud-fail: if graph cleanup throws, files are preserved and a 500 is returned with the error text. Re-issuing the DELETE is safe (idempotent on both layers). Operator-tagged docs survive the projection delete — only the `USES_KNOWLEDGE` edges from this Agent are removed.
 - Verify the directory no longer exists
 - Report what was removed (list the files that were in the directory)
 

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

@@ -2,11 +2,23 @@
 
 ## Hardware Requirements
 
-- Raspberry Pi 5 (16GB RAM minimum)
-- 256GB storage (microSD or NVMe)
-- Raspberry Pi OS
+- Raspberry Pi 5 (16GB RAM minimum) with Raspberry Pi OS, **or**
+- Mac with macOS 14 (Sonoma) or newer — both Apple Silicon and Intel
+- 256GB storage minimum
 - Always-on power and network connection
 
+## macOS install
+
+On macOS the installer uses Homebrew + launchd instead of apt + systemd, but the operator command is the same:
+
+```bash
+npx -y @rubytech/create-maxy
+```
+
+**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 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.
+
 ## Initial Setup
 
 The {{productName}} installer handles the full setup. Run it on your Pi:

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

@@ -65,7 +65,7 @@ There is no dashboard, no settings panel, no menus. Everything is done through c
 
 The chat input auto-grows as you type — it expands to fit your message and shrinks back when you delete text. You can also drag the resize handle above the input to set a custom height.
 
-The admin interface is a three-pane layout: a sidebar on the left with your brand mark, navigation (Chat, Projects, Artefacts), and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu — holding the surface side-by-side with the conversation so the chat stays live while you work in it. The sidebar's nav rows swap the list view in place — Chat shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable — type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood — clicking a second project swaps the focus rather than stacking on top. The chat / artefact divider is drag-resizable — drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat / artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On phones (<640px) the sidebar slides in as a drawer from the left when you tap the menu icon in the chat header.
+The admin interface is a three-pane layout: a sidebar on the left with your brand mark, navigation (Chat, People, Agents, Projects, Tasks, Artefacts), and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu — holding the surface side-by-side with the conversation so the chat stays live while you work in it. The sidebar's nav rows swap the list view in place — Chat shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list — the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable — type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood — clicking a second project swaps the focus rather than stacking on top. The chat / artefact divider is drag-resizable — drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat / artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On phones (<640px) the sidebar slides in as a drawer from the left when you tap the menu icon in the chat header.
 
 Page titles are brand-aware: the browser tab shows your product name (e.g. `Real Agent` instead of `Maxy`) on every shell — chat, graph, and data — so a non-default brand never leaks the default name in tab strips or browser history.