@rubytech/create-maxy-code 0.1.442 → 0.1.444

package/payload/platform/docs/superpowers/specs/2026-07-14-graph-top-level-labels-ontology-single-source-design.md

@@ -0,0 +1,119 @@
+# Single-source the `/graph` top-level label allowlist from the vertical ontology — Design
+
+Task: `.tasks/1624-single-source-graph-labels-top-level-from-vertical-ontology.md`.
+
+## Problem
+
+A businessType's top-level operator-entry node types live in the `## Top-level node
+types` table of each vertical's `schema-<vertical>.md` (established by 1622). A third
+encoding of "top-level entity" still lives apart: `platform/ui/app/lib/graph-labels.ts`
+`FILTER_TOP_LEVEL_LABELS` is a hand-maintained global union of every brand's top-level
+labels — the `/graph` filter-popover chip allowlist. It drifts from the ontology by
+construction: a top-level label added to a vertical schema does not become a chip until
+someone also edits this TypeScript set.
+
+## Goal
+
+Derive the `/graph` chip allowlist from the same per-vertical ontology source so a
+top-level label added to a vertical schema surfaces as a chip with no second edit, while
+preserving today's exact chip visibility as the acceptance baseline.
+
+## Blast radius (evidence)
+
+`FILTER_TOP_LEVEL_LABELS` has four real code consumers:
+
+1. `server/routes/admin/graph-labels-in-graph.ts` — popover chip allowlist (the route the
+   task names). Passes the set as the `$allowed` cypher param; the cypher count-gates.
+2. `server/routes/admin/graph-subgraph.ts:280` — default-view label set.
+3. `server/routes/admin/graph-default-view.ts:158` — default-view eligibility check.
+4. `app/data/searchHelpers.ts:46` — client-side `/data` search chip pre-filter, a
+   build-time static import that cannot read files.
+
+Scope decision (operator-confirmed): **the three server routes switch to the
+ontology-derived source. The client `searchHelpers.ts` keeps the static set**, with a
+follow-up task filed to close that last second source.
+
+## Facts that shape the mechanism
+
+- Only `schema-construction.md` and `schema-estate-agent.md` currently carry a
+  `## Top-level node types` section. Every other vertical (and 1626) adds theirs later.
+- `schema-base.md` has no top-level section; its `## Node Types` table mixes top-level and
+  child types (Message, Section, Chunk). Base labels therefore **cannot** be derived — they
+  stay an explicit list. This resolves the task's open base-list decision.
+- The construction top-level table includes `WhatsAppGroup` typed `cdm:Channel`. The 1622
+  Python file-bucket generator excludes non-`schema:` rows (a channel gets no file bucket),
+  but `WhatsAppGroup` **is** a current graph chip. So the graph derivation takes **every**
+  Neo4j Label row and applies **no** namespace filter.
+- The construction table has 5 columns, estate-agent 4. The Neo4j Label column is resolved
+  by header name, never by index.
+
+## Architecture
+
+New server-only module `platform/ui/server/lib/top-level-labels.ts`:
+
+```
+getTopLevelLabelAllowlist(opts?: { referencesDir?: string }): ReadonlySet<string>
+```
+
+- Resolves `referencesDir` to `${MAXY_PLATFORM_ROOT}/plugins/memory/references` (same
+  env/`__dirname` fallback the UI server already uses), or the injected override.
+- Reads every `schema-*.md`. For each, locates the `## Top-level node types` heading by
+  case-insensitive prefix, reads the first pipe-table beneath it (before the next `##`),
+  and extracts the `Neo4j Label` column by header name, stripping backticks.
+- Unions parsed labels with the module const `STATIC_TOP_LEVEL_LABELS` — the base-schema
+  infra plus any vertical whose schema has no top-level section yet (knowledge-work today).
+  Documented to shrink as 1626 adds sections.
+- Caches the result at module level (schema files are static per install). An injected
+  `referencesDir` bypasses the cache so tests are isolated.
+- Emits one observability line on computation:
+  `op=top-level-labels source=ontology count=<n> files=<...> derived=<d> static=<s>`.
+
+The three server routes replace `FILTER_TOP_LEVEL_LABELS` with
+`getTopLevelLabelAllowlist()` (a `ReadonlySet<string>`, so `.has()` and spread are
+preserved). Cypher count-gating is unchanged: a non-resident label surfaces no chip.
+
+Unchanged: `FILTER_TOP_LEVEL_LABELS` (client), `HIDDEN_BY_DEFAULT_LABELS`,
+`AGENT_ACTION_LABELS`, `EXCLUDED_EDGE_TYPES`.
+
+## Byte-identical guarantee
+
+Derived union = construction table (11) ∪ estate table (4) ∪ `STATIC_TOP_LEVEL_LABELS`
+(33) = the current 48-member `FILTER_TOP_LEVEL_LABELS`. Because the sets are equal, the
+existing route tests (which assert membership against `FILTER_TOP_LEVEL_LABELS`) keep
+passing unchanged.
+
+`STATIC_TOP_LEVEL_LABELS` (top-level labels not yet sourced from a vertical section):
+
+- Base-schema infra: `LocalBusiness`, `Service`, `PriceSpecification`,
+  `OpeningHoursSpecification`, `Organization`, `Person`, `UserProfile`, `Preference`,
+  `AdminUser`, `AccessGrant`, `KnowledgeDocument`, `DigitalDocument`, `CreativeWork`,
+  `Question`, `FAQPage`, `DefinedTerm`, `Review`, `ImageObject`, `Invoice`, `Task`,
+  `Project`, `Event`, `Workflow`, `Email`, `EmailAccount`, `Agent`.
+- Knowledge-work vertical (no top-level section yet; 1626): `Objective`, `KeyResult`,
+  `Decision`, `Risk`, `Source`, `Finding`, `Hypothesis`.
+
+## Testing
+
+Committed, colocated `platform/ui/server/lib/top-level-labels.test.ts`:
+
+1. `getTopLevelLabelAllowlist()` against the real references dir deep-equals
+   `FILTER_TOP_LEVEL_LABELS` (regression baseline).
+2. A fixture references dir with an added top-level row surfaces that label with no change
+   to any TypeScript set.
+3. A `cdm:`-namespaced row (e.g. `WhatsAppGroup`) is included (no namespace filter).
+
+The pre-existing `labels-in-graph` and `graph-default-topLevel` tests must still pass
+after the swap (count-gating and eligibility unchanged).
+
+## Observability
+
+`op=top-level-labels source=ontology count=<n>` on the server log, emitted when the
+allowlist is resolved, so an operator can confirm the chips come from the ontology, not a
+stale hardcoded list.
+
+## Out of scope
+
+- Client `searchHelpers.ts` static set — filed as a follow-up task.
+- `HIDDEN_BY_DEFAULT_LABELS`, `AGENT_ACTION_LABELS`, `EXCLUDED_EDGE_TYPES`.
+- Adding `## Top-level node types` sections to verticals that lack one (1626).
+- The file-schema generator and quotation reification (landed in 1622).

package/payload/platform/plugins/admin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "admin",
-  "description": "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), admin-hostname (the admin-host twin of public-hostname — resolves the host that serves /calendar and the rest of the admin shell behind sign-in from the same ingress + alias + operator files, so agents point the operator at the admin /calendar URL instead of the public host that 404s it), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge, account_channel_routing, account_channel_routing_set — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation; account_create requires a managing house admin (its userId) and refuses without one, recording it as the sub-account's managingAdminUserId, and also requires the client business owner's real name (ownerName), refusing a blank or the placeholder \"Owner\" and seeding it onto the sub-account's owner AdminUser and owner Person; account_reassign_admin repoints a client sub-account's managing admin to another live house admin (the repair path for a dangling managingAdminUserId); account_channel_routing_set repoints the install's single WhatsApp/Telegram inbound stream to a different sub-account), admin-add (refuses on a client sub-account, where admin access is already install-wide so a per-operator seat grants nothing — the sub-account's one identity, its business owner, is set at account creation; the house account, where operators hold PIN logins and admins[] rows, is unchanged), admin-remove (refuses to remove a house admin who still manages one or more client sub-accounts, naming them so the operator reassigns each with account_reassign_admin first — never silently orphans them), admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform.",
+  "description": "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), admin-hostname (the admin-host twin of public-hostname — resolves the host that serves /calendar and the rest of the admin shell behind sign-in from the same ingress + alias + operator files, so agents point the operator at the admin /calendar URL instead of the public host that 404s it), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge, account_channel_routing, account_channel_routing_set — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation; account_create requires the client business owner's real name (ownerName), refusing a blank or the placeholder \"Owner\" and seeding it onto the sub-account's owner AdminUser and owner Person, while a managing house admin (its userId) is optional — when supplied it is validated as a live house admin and recorded as the sub-account's managingAdminUserId, and when omitted the sub-account is unmanaged and its passive-intake tasks route to the install's primary admin; account_reassign_admin repoints a client sub-account's managing admin to another live house admin (the repair path for a dangling managingAdminUserId, or to record one on an unmanaged account); account_roster is the canonical per-account identity view — one row per sub-account giving business name, role, the managing house admin resolved to a name with status (assigned/absent/dangling), the business owner from the graph with status (named/nameless), and the WhatsApp account-manager binding if any, each field carrying what it means and does not (managing admin is the responsible house team member not the owner; account manager is WhatsApp routing only with no admin rights), so the agent never stitches admin-list + account.json + whatsapp-config; account_set_owner_name names (or corrects) a client sub-account's business owner by writing the owned Person — the canonical name source — refusing a blank or the placeholder \"Owner\", the guarded repair for a nameless owner (the standing identity-audit op=nameless-owned-person detector); account_channel_routing_set repoints the install's single WhatsApp/Telegram inbound stream to a different sub-account), admin-add (refuses on a client sub-account, where admin access is already install-wide so a per-operator seat grants nothing — the sub-account's one identity, its business owner, is set at account creation; the house account, where operators hold PIN logins and admins[] rows, is unchanged), admin-remove (refuses to remove a house admin who still manages one or more client sub-accounts, naming them so the operator reassigns each with account_reassign_admin first — never silently orphans them), admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

package/payload/platform/plugins/admin/PLUGIN.md

@@ -1,7 +1,7 @@
 ---
 name: admin
 surface: platform
-description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), admin-hostname (the admin-host twin of public-hostname — resolves the host that serves /calendar and the rest of the admin shell behind sign-in from the same ingress + alias + operator files, so agents point the operator at the admin /calendar URL instead of the public host that 404s it), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge, account_channel_routing, account_channel_routing_set — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation; account_create requires a managing house admin (its userId) and refuses without one, recording it as the sub-account's managingAdminUserId, and also requires the client business owner's real name (ownerName), refusing a blank or the placeholder "Owner" and seeding it onto the sub-account's owner AdminUser and owner Person; account_reassign_admin repoints a client sub-account's managing admin to another live house admin (the repair path for a dangling managingAdminUserId); account_channel_routing_set repoints the install's single WhatsApp/Telegram inbound stream to a different sub-account), admin-add (refuses on a client sub-account, where admin access is already install-wide so a per-operator seat grants nothing — the sub-account's one identity, its business owner, is set at account creation; the house account, where operators hold PIN logins and admins[] rows, is unchanged), admin-remove (refuses to remove a house admin who still manages one or more client sub-accounts, naming them so the operator reassigns each with account_reassign_admin first — never silently orphans them), admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform."
+description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), admin-hostname (the admin-host twin of public-hostname — resolves the host that serves /calendar and the rest of the admin shell behind sign-in from the same ingress + alias + operator files, so agents point the operator at the admin /calendar URL instead of the public host that 404s it), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge, account_channel_routing, account_channel_routing_set — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation; account_create requires the client business owner's real name (ownerName), refusing a blank or the placeholder "Owner" and seeding it onto the sub-account's owner AdminUser and owner Person, while a managing house admin (its userId) is optional — when supplied it is validated as a live house admin and recorded as the sub-account's managingAdminUserId, and when omitted the sub-account is unmanaged and its passive-intake tasks route to the install's primary admin; account_reassign_admin repoints a client sub-account's managing admin to another live house admin (the repair path for a dangling managingAdminUserId, or to record one on an unmanaged account); account_roster is the canonical per-account identity view — one row per sub-account giving business name, role, the managing house admin resolved to a name with status (assigned/absent/dangling), the business owner from the graph with status (named/nameless), and the WhatsApp account-manager binding if any, each field carrying what it means and does not (managing admin is the responsible house team member not the owner; account manager is WhatsApp routing only with no admin rights), so the agent never stitches admin-list + account.json + whatsapp-config; account_set_owner_name names (or corrects) a client sub-account's business owner by writing the owned Person — the canonical name source — refusing a blank or the placeholder "Owner", the guarded repair for a nameless owner (the standing identity-audit op=nameless-owned-person detector); account_channel_routing_set repoints the install's single WhatsApp/Telegram inbound stream to a different sub-account), admin-add (refuses on a client sub-account, where admin access is already install-wide so a per-operator seat grants nothing — the sub-account's one identity, its business owner, is set at account creation; the house account, where operators hold PIN logins and admins[] rows, is unchanged), admin-remove (refuses to remove a house admin who still manages one or more client sub-accounts, naming them so the operator reassigns each with account_reassign_admin first — never silently orphans them), admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform."
 tools:
   - name: system-status
     publicAllowlist: false
@@ -30,12 +30,18 @@ tools:
   - name: account_list
     publicAllowlist: false
     adminAllowlist: true
+  - name: account_roster
+    publicAllowlist: false
+    adminAllowlist: true
   - name: account_create
     publicAllowlist: false
     adminAllowlist: true
   - name: account_reassign_admin
     publicAllowlist: false
     adminAllowlist: true
+  - name: account_set_owner_name
+    publicAllowlist: false
+    adminAllowlist: true
   - name: account_delete
     publicAllowlist: false
     adminAllowlist: true

package/payload/platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh

@@ -27,13 +27,23 @@ trap 'rm -rf "$ACCT"' EXIT
 cp "$TEMPLATE" "$ACCT/SCHEMA.md"
 mkdir -p "$ACCT/projects/Acme" "$ACCT/documents" "$ACCT/output"
 
+# A second account modelling a provisioned construction account: jobs/ is a
+# derived domain bucket (the generator appends it to the allowed block, like a
+# plugin-owned dir). Kept separate so the template-parity assertion below still
+# checks the pristine shipped set.
+ACCT_D=$(mktemp -d)
+trap 'rm -rf "$ACCT" "$ACCT_D"' EXIT
+cp "$TEMPLATE" "$ACCT_D/SCHEMA.md"
+awk '1; /^```allowed-top-level$/{print "jobs"}' "$ACCT_D/SCHEMA.md" > "$ACCT_D/SCHEMA.md.tmp" && mv "$ACCT_D/SCHEMA.md.tmp" "$ACCT_D/SCHEMA.md"
+mkdir -p "$ACCT_D/jobs/5-oaktree/Quotations"
+
 PASS=0; FAIL=0
 # Run one case in the account dir as cwd.
 #   $1 name  $2 stdin  $3 expected_exit  $4 expected_log_re ("" = none)
 run_case() {
-  local name="$1" stdin="$2" exp="$3" re="$4" ef actual
+  local name="$1" stdin="$2" exp="$3" re="$4" acct="${5:-$ACCT}" ef actual
   ef=$(mktemp)
-  ( cd "$ACCT" && printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>"$ef" )
+  ( cd "$acct" && printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>"$ef" )
   actual=$?
   local sc; sc=$(cat "$ef"); rm -f "$ef"
   local ok=1
@@ -58,6 +68,13 @@ run_case "empty stdin block"     ""
 # JSON null file_path must coerce to empty (allow), not the literal string "None".
 run_case "null path allow"       '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":null}}' 0 ""
 
+# Derived domain buckets (construction account $ACCT_D): jobs/ passes at any
+# depth (it is outside the three flat operator-data buckets), an undeclared
+# top-level segment still blocks.
+run_case "domain bucket deep allow" "$(mkenv Write file_path 'jobs/5-oaktree/Quotations/quote.pdf')" 0 "" "$ACCT_D"
+run_case "domain bucket file allow"  "$(mkenv Write file_path 'jobs/5-oaktree/notes.md')"           0 "" "$ACCT_D"
+run_case "undeclared still blocks"   "$(mkenv Write file_path 'invoices/x.pdf')"                     2 "reason=top-level" "$ACCT_D"
+
 # Allowed-set parse == documented set.
 EXPECT="projects contacts documents url-get output generated extracted uploads agents specialists sites public cache secrets state logs tmp SCHEMA.md account.json AGENTS.md .claude .git"
 GOT=$(awk '/^```allowed-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCT/SCHEMA.md" | tr '\n' ' ' | sed 's/ *$//')

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -28,7 +28,7 @@ import { publishSite } from "./tools/publish-site.js";
 import { resolveCapabilitiesHere } from "./tools/capabilities-here.js";
 import { runCatalogueCensus } from "./lib/catalogue-census.js";
 import { lifelineTool } from "../../../../lib/mcp-lifeline/dist/index.js";
-import { listAccountsFromDir, isHouseAccount, archiveAccountDir, provisionClientAccount, findHouseAccount, getChannelRoutingAccountId, setChannelRoutingAccountId, seedAccountGraphRoot, isPlaceholderOwnerName, refuseClientAdminAdd, readHouseAdminUserIds, setManagingAdmin, findClientAccountsManagedBy, reassignManagingAdmin, ACCOUNT_NODE_COUNT_CYPHER, ACCOUNT_PURGE_CYPHER, } from "./tools/account-lifecycle.js";
+import { listAccountsFromDir, isHouseAccount, archiveAccountDir, provisionClientAccount, findHouseAccount, getChannelRoutingAccountId, setChannelRoutingAccountId, seedAccountGraphRoot, isPlaceholderOwnerName, refuseClientAdminAdd, readHouseAdminUserIds, setManagingAdmin, findClientAccountsManagedBy, reassignManagingAdmin, ACCOUNT_NODE_COUNT_CYPHER, ACCOUNT_PURGE_CYPHER, classifyManagingAdmin, ownerNameStatus, readManagingAdminUserId, setOwnerName, } from "./tools/account-lifecycle.js";
 function refusalGuidance(kind) {
     switch (kind) {
         case "unsafe-slug":
@@ -3313,19 +3313,121 @@ eagerTool(server, "account_list", "List every sub-account on this install (one h
         content: [{ type: "text", text: accounts.length ? lines.join("\n") : "No accounts found." }],
     };
 });
-eagerTool(server, "account_create", "Provision a new CLIENT sub-account on this install (managed service). REQUIRES two things: `adminUserId`, the userId of the house team member who will manage this client (get the choices from admin-list; ask the operator which one before creating); and `ownerName`, the real name of the client business's owner (ask the operator for it — never invent it or reuse the house operator's name). Mints a UUID, scaffolds the account directory (agents, specialists, settings, account.json with role:\"client\" and managingAdminUserId), seeds default plugins, and seeds the account's graph root (a :LocalBusiness plus its owner :AdminUser and owner :Person carrying ownerName) so you can populate it immediately. Refuses if adminUserId is missing/not a house admin, or if ownerName is missing/blank/the placeholder \"Owner\". Returns the new accountId. Operator-only; never creates the house sub-account (that is the install itself).", {
-    adminUserId: z.string().describe("The userId of the house admin who will manage this client sub-account. Must be a current house admin (see admin-list). Required — creation is refused without it."),
+eagerTool(server, "account_roster", "Canonical per-account identity roster for this install. One row per sub-account: accountId, business name, role (house/client), the managing house admin (the responsible house team member — NOT the owner) resolved to a name with status assigned/absent/dangling, the business owner (the client's owner identity on the graph) with status named/nameless, and the WhatsApp account-manager binding if any (WhatsApp routing only — carries NO admin rights). This is the single tool for 'who owns each account and which admin manages it'; never stitch admin-list + account.json + whatsapp-config for this. Operator-only.", {}, async () => {
+    if (!ACCOUNT_ID)
+        return refuseNoAccount("account_roster");
+    const TAG = "[account-roster]";
+    const accounts = listAccountsFromDir(ACCOUNTS_ROOT);
+    const liveHouse = readHouseAdminUserIds(ACCOUNTS_ROOT);
+    // Graph reads: business name, owner (role:owner AdminUser's owned Person),
+    // and managing-admin name (house AdminUser's owned Person). Best-effort — a
+    // Neo4j hiccup renders the graph-derived fields unknown, never fails the roster.
+    const businessName = new Map();
+    const ownerName = new Map();
+    const mgrName = new Map();
+    try {
+        const session = getSession();
+        try {
+            const ids = accounts.map((a) => a.accountId);
+            const bn = await session.run(`UNWIND $ids AS id MATCH (b:LocalBusiness {accountId: id}) RETURN id, b.name AS name`, { ids });
+            for (const r of bn.records)
+                businessName.set(r.get("id"), (r.get("name") ?? "").trim());
+            const own = await session.run(`UNWIND $ids AS id
+           MATCH (au:AdminUser {accountId: id, role: 'owner'})-[:OWNS]->(p:Person)
+           WHERE p.accountId = au.accountId
+           RETURN id, p.givenName AS givenName, p.familyName AS familyName`, { ids });
+            for (const r of own.records) {
+                const g = r.get("givenName")?.trim() ?? "";
+                const f = r.get("familyName")?.trim() ?? "";
+                ownerName.set(r.get("id"), g ? (f ? `${g} ${f}` : g) : null);
+            }
+            const mgrIds = accounts.map((a) => readManagingAdminUserId(ACCOUNTS_ROOT, a.accountId)).filter((u) => !!u);
+            if (mgrIds.length) {
+                const mg = await session.run(`UNWIND $ids AS uid MATCH (au:AdminUser {userId: uid})-[:OWNS]->(p:Person)
+             WHERE p.accountId = au.accountId
+             RETURN uid, p.givenName AS givenName, p.familyName AS familyName`, { ids: mgrIds });
+                for (const r of mg.records) {
+                    const g = r.get("givenName")?.trim() ?? "";
+                    const f = r.get("familyName")?.trim() ?? "";
+                    if (g)
+                        mgrName.set(r.get("uid"), f ? `${g} ${f}` : g);
+                }
+            }
+        }
+        finally {
+            await session.close();
+        }
+    }
+    catch { /* graph best-effort */ }
+    // WhatsApp account-manager map (phone -> {managesAccount, mode}); reached the
+    // same way admin already calls the UI server internal port (remote-auth).
+    // Best-effort — null column on any failure.
+    const amByAccount = new Map();
+    try {
+        const internalPort = parseInt(PLATFORM_PORT, 10);
+        // Task 1636 — the config route is house-scoped; forward this operator
+        // session's platform-stamped caller identity so the gate authorises the
+        // read. account_roster is operator-only, so its house session carries
+        // ACCOUNT_ID (+ HOUSE_ADMIN_SCOPE for a non-specialist house admin); the
+        // agent cannot forge either. Absent (e.g. a non-house context) the gate
+        // fails closed and this best-effort column stays null.
+        const scopeHeaders = { "content-type": "application/json" };
+        if (process.env.ACCOUNT_ID)
+            scopeHeaders["x-maxy-caller-account"] = process.env.ACCOUNT_ID;
+        if (process.env.HOUSE_ADMIN_SCOPE)
+            scopeHeaders["x-maxy-house-admin-scope"] = process.env.HOUSE_ADMIN_SCOPE;
+        const res = await fetch(`http://127.0.0.1:${internalPort}/api/whatsapp/config`, {
+            method: "POST",
+            headers: scopeHeaders,
+            body: JSON.stringify({ action: "list-account-managers" }),
+            signal: AbortSignal.timeout(5000),
+        });
+        if (res.ok) {
+            const body = await res.json();
+            for (const [phone, v] of Object.entries(body.accountManagers ?? {})) {
+                const managesAccount = typeof v === "string" ? v : v.managesAccount;
+                const mode = typeof v === "string" ? "active" : (v.mode ?? "active");
+                amByAccount.set(managesAccount, { phone, mode });
+            }
+        }
+    }
+    catch { /* account-manager column best-effort */ }
+    let namelessOwners = 0, absentMgr = 0, danglingMgr = 0;
+    const lines = accounts.map((a) => {
+        const biz = businessName.get(a.accountId) || "(unnamed)";
+        if (a.isHouse)
+            return `- **${biz}** — accountId: ${a.accountId}, role: house`;
+        const mgrId = readManagingAdminUserId(ACCOUNTS_ROOT, a.accountId);
+        const mgrStatus = classifyManagingAdmin(mgrId, liveHouse);
+        if (mgrStatus === "absent")
+            absentMgr++;
+        else if (mgrStatus === "dangling")
+            danglingMgr++;
+        const oName = ownerName.get(a.accountId) ?? null;
+        const oStatus = ownerNameStatus(oName);
+        if (oStatus === "nameless")
+            namelessOwners++;
+        const am = amByAccount.get(a.accountId);
+        const mgrLabel = mgrStatus === "assigned" ? `${mgrName.get(mgrId) ?? mgrId} (assigned)` : mgrStatus;
+        const ownerLabel = oStatus === "named" ? `${oName} (named)` : "nameless";
+        const amLabel = am ? `${am.phone}${am.mode === "passive" ? " (passive)" : " (active)"}` : "none";
+        return `- **${biz}** — accountId: ${a.accountId}, role: client, managing admin: ${mgrLabel}, owner: ${ownerLabel}, account manager: ${amLabel}`;
+    });
+    process.stderr.write(`${TAG} op=roster accounts=${accounts.length} nameless-owners=${namelessOwners} absent-mgr=${absentMgr} dangling-mgr=${danglingMgr}\n`);
+    return { content: [{ type: "text", text: accounts.length ? `Account roster:\n\n${lines.join("\n")}` : "No accounts found." }] };
+});
+eagerTool(server, "account_create", "Provision a new CLIENT sub-account on this install (managed service). REQUIRES `ownerName`, the real name of the client business's owner (ask the operator for it — never invent it or reuse the house operator's name). OPTIONALLY takes `adminUserId`, the userId of the house team member who will manage this client (get the choices from admin-list; ask the operator, but omit it if the client is run by its owner rather than a house admin). Mints a UUID, scaffolds the account directory (agents, specialists, settings, account.json with role:\"client\", and managingAdminUserId when an admin is named), seeds default plugins, and seeds the account's graph root (a :LocalBusiness plus its owner :AdminUser and owner :Person carrying ownerName) so you can populate it immediately. Refuses if ownerName is missing/blank/the placeholder \"Owner\", or if a supplied adminUserId is not a current house admin. When no managing admin is set, that account's passive-intake tasks route to the install's primary admin. Returns the new accountId. Operator-only; never creates the house sub-account (that is the install itself).", {
+    adminUserId: z.string().optional().describe("The userId of the house admin who will manage this client sub-account. Optional — omit it for a client run by its owner rather than a house admin (its passive-intake tasks then route to the install's primary admin). When supplied, it must be a current house admin (see admin-list) or creation is refused."),
     ownerName: z.string().describe("The real name of the client business's owner. Applied to both the owner AdminUser and owner Person for the new sub-account. Required — creation is refused when missing, blank, or the placeholder \"Owner\". Ask the operator; never reuse the house operator's name."),
 }, async ({ adminUserId, ownerName }) => {
     if (!ACCOUNT_ID)
         return refuseNoAccount("account_create");
-    // Task 1500 — every client sub-account must carry a responsible house admin.
-    // Refuse (tool error, never a silent default) when none is named, or when
-    // the named userId is not a current house admin.
-    if (!adminUserId || !adminUserId.trim()) {
-        process.stderr.write(`[account-lifecycle] op=create-refused reason=no-admin adminUserId=-\n`);
-        return { content: [{ type: "text", text: `account_create refused: name the managing house admin (adminUserId). Call admin-list to see the choices and ask the operator which one manages this client.` }], isError: true };
-    }
+    // Task 1630 — a managing admin is optional. `adminUserId` omitted/blank ⇒ the
+    // sub-account carries no managingAdminUserId and its passive-intake tasks fall
+    // back to the install's primary admin. A supplied adminUserId is normalized
+    // and still validated below (a named-but-wrong admin is an error, not a
+    // fallback — it catches operator typos, matching account_reassign_admin).
+    const managingAdminUserId = adminUserId && adminUserId.trim() ? adminUserId.trim() : undefined;
     // Task 1567 — the business owner's name is a hard precondition of the
     // sub-account. Refuse before any scaffold so a nameless create leaves no
     // partial account directory or rootless graph behind. The same predicate
@@ -3334,10 +3436,9 @@ eagerTool(server, "account_create", "Provision a new CLIENT sub-account on this
         process.stderr.write(`[account-create] op=refused reason=no-owner-name\n`);
         return { content: [{ type: "text", text: `account_create refused: give the client business owner's real name (ownerName). It cannot be blank or the placeholder "Owner". Ask the operator whose business this is.` }], isError: true };
     }
-    const houseAdminUserIds = readHouseAdminUserIds(ACCOUNTS_ROOT);
-    if (!houseAdminUserIds.includes(adminUserId)) {
-        process.stderr.write(`[account-lifecycle] op=create-refused reason=unknown-admin adminUserId=${adminUserId.slice(0, 8)}\n`);
-        return { content: [{ type: "text", text: `account_create refused: ${adminUserId} is not a current house admin. Call admin-list for the valid managing-admin choices.` }], isError: true };
+    if (managingAdminUserId && !readHouseAdminUserIds(ACCOUNTS_ROOT).includes(managingAdminUserId)) {
+        process.stderr.write(`[account-lifecycle] op=create-refused reason=unknown-admin adminUserId=${managingAdminUserId.slice(0, 8)}\n`);
+        return { content: [{ type: "text", text: `account_create refused: ${managingAdminUserId} is not a current house admin. Call admin-list for the valid managing-admin choices, or omit adminUserId to leave the client unmanaged.` }], isError: true };
     }
     const newId = randomUUID();
     try {
@@ -3380,26 +3481,33 @@ eagerTool(server, "account_create", "Provision a new CLIENT sub-account on this
         finally {
             await seedSession.close();
         }
-        process.stderr.write(`[account-lifecycle] op=create accountId=${newId} dir-exists=${dirExists} root-seeded=${rootSeeded} managingAdmin=${adminUserId.slice(0, 8)}\n`);
+        process.stderr.write(`[account-lifecycle] op=create accountId=${newId} dir-exists=${dirExists} root-seeded=${rootSeeded} managingAdmin=${managingAdminUserId ? managingAdminUserId.slice(0, 8) : "-"}\n`);
         if (!rootSeeded) {
             return { content: [{ type: "text", text: `account_create FAILED: graph root not seeded for ${newId} (business+admin read-back failed). The account directory was scaffolded but is rootless — run account_delete ${newId} and retry.` }], isError: true };
         }
-        // Task 1500 — persist the validated managing admin on the new sub-account.
+        // Task 1500/1630 — persist the managing admin on the new sub-account when
+        // one was named. Skipped when adminUserId was omitted: the account is left
+        // unmanaged and its passive-intake tasks fall back to the primary admin.
         // Done after the root seed so a rootless failure never leaves a half-created
         // account claiming a manager. Its own try: at this point the account is
         // fully created and seeded, so a write failure must not be reported as a
         // generic create failure (which would push the operator to retry and
         // orphan a second account). Report the real state — created but unmanaged —
         // with the recovery action.
-        try {
-            setManagingAdmin(ACCOUNTS_ROOT, newId, adminUserId);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`[account-lifecycle] op=create-admin-write-failed accountId=${newId} error=${msg}\n`);
-            return { content: [{ type: "text", text: `account_create: sub-account ${newId} was created and its graph root seeded, but recording the managing admin failed: ${msg}. The account exists with no managing admin — run account_delete ${newId} and retry.` }], isError: true };
+        if (managingAdminUserId) {
+            try {
+                setManagingAdmin(ACCOUNTS_ROOT, newId, managingAdminUserId);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[account-lifecycle] op=create-admin-write-failed accountId=${newId} error=${msg}\n`);
+                return { content: [{ type: "text", text: `account_create: sub-account ${newId} was created and its graph root seeded, but recording the managing admin failed: ${msg}. The account exists with no managing admin — run account_reassign_admin ${newId} <adminUserId> to record one.` }], isError: true };
+            }
         }
-        return { content: [{ type: "text", text: `Created client sub-account ${newId}, managed by admin ${adminUserId}. Switch to it from the sub-account picker to work in its data.` }] };
+        const managedNote = managingAdminUserId
+            ? `managed by admin ${managingAdminUserId}`
+            : `with no managing admin (its passive-intake tasks route to the primary admin; use account_reassign_admin to assign one)`;
+        return { content: [{ type: "text", text: `Created client sub-account ${newId}, ${managedNote}. Switch to it from the sub-account picker to work in its data.` }] };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -3425,6 +3533,39 @@ eagerTool(server, "account_reassign_admin", "Reassign a CLIENT sub-account's man
     process.stderr.write(`[account-lifecycle] op=reassign accountId=${accountId} from=${res.previousAdminUserId ? res.previousAdminUserId.slice(0, 8) : "-"} to=${adminUserId.slice(0, 8)}\n`);
     return { content: [{ type: "text", text: `Reassigned client sub-account ${accountId} to managing admin ${adminUserId}. It takes effect on the next passive intake.` }] };
 });
+eagerTool(server, "account_set_owner_name", "Name (or correct the name of) a CLIENT sub-account's business owner. Pass `accountId` and `name` (the owner's real name; refused if blank or the placeholder \"Owner\"). Writes the name onto the owner's owned Person — the canonical name source — renaming the existing one if present, else creating it. Use to repair a nameless owner (identity-audit flags these as op=nameless-owned-person). Does not touch managingAdminUserId. Operator-only.", {
+    accountId: z.string().describe("The client sub-account whose owner to name."),
+    name: z.string().describe("The owner's real name. Refused if blank or the placeholder \"Owner\"."),
+}, async ({ accountId, name }) => {
+    if (!ACCOUNT_ID)
+        return refuseNoAccount("account_set_owner_name");
+    const TAG = "[account-set-owner-name]";
+    if (isPlaceholderOwnerName(name)) {
+        process.stderr.write(`${TAG} op=refused reason=no-owner-name account=${accountId.slice(0, 8)}\n`);
+        return { content: [{ type: "text", text: `account_set_owner_name refused: give the owner's real name (not blank or "Owner").` }], isError: true };
+    }
+    // The tool names a CLIENT business owner. The house account's owner is an
+    // operator identity, not a client owner, so refuse it explicitly rather than
+    // renaming a house operator's Person by a mistyped id.
+    if (isHouseAccount(ACCOUNTS_ROOT, accountId)) {
+        process.stderr.write(`${TAG} op=refused reason=house-account account=${accountId.slice(0, 8)}\n`);
+        return { content: [{ type: "text", text: `account_set_owner_name refused: ${accountId} is the house account. This tool names a client sub-account's business owner.` }], isError: true };
+    }
+    const session = getSession();
+    try {
+        const r = await setOwnerName({ session, accountId, name });
+        process.stderr.write(`${TAG} op=named account=${accountId.slice(0, 8)} renamed=${r.personRenamed} created=${r.personCreated}\n`);
+        return { content: [{ type: "text", text: `Owner of ${accountId} set to ${r.givenName}${r.familyName ? " " + r.familyName : ""} (${r.personRenamed ? "renamed existing Person" : "created Person"}).` }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`${TAG} op=failed account=${accountId.slice(0, 8)} error=${msg}\n`);
+        return { content: [{ type: "text", text: `account_set_owner_name FAILED: ${msg}` }], isError: true };
+    }
+    finally {
+        await session.close();
+    }
+});
 eagerTool(server, "account_delete", "Archive a CLIENT sub-account: move its directory to data/accounts/.trash/ so it no longer appears in the sub-account list. Graph data is RETAINED — run account_purge with the typed confirmation to irreversibly delete it. Refuses to archive the house sub-account. Pass the accountId to archive.", {
     accountId: z.string().describe("The client accountId (UUID) to archive."),
 }, async ({ accountId }) => {